Migrating from Corefy
How to move a payment integration from Corefy (PayCore) to this API: calls, fields, statuses and callbacks side by side, keys and retries, checks and switching method by method.
There is no entry point compatible with the Corefy (PayCore) API: the checkout's payment client is rewritten for this API once. Below is what changes and the order in which payment methods move one at a time without stopping intake.
Calls
| Corefy | This API |
|---|---|
POST /api/payment-invoices | POST /api/v1/payments: Accepting a payment |
GET /api/payment-invoices/{id} | GET /api/v1/payments/:id |
Invoice list filtered by filter[reference_id] | GET /api/v1/payments?reference=…: zero or one payment |
POST /api/payment-invoices/{id}/refund | POST /api/v1/payments/:id/refunds: Refunds |
POST /public-api/payment-prerequest | GET /api/v1/services: Services and amounts |
POST /api/payout-invoices | POST /api/v1/payouts: Payouts; for now in the test environment only and not sent to a provider |
GET /api/payout-invoices/{id} | GET /api/v1/payouts/:id |
terminate of a payout invoice | POST /api/v1/payouts/:id/cancel: cancellation while the payout is not sent |
payout-prerequest | GET /api/v1/services, services with direction: PAYOUT |
Capture and void, payment retry, batch payouts and starting a payout (process), balances, reports | None |
There are no browser calls with a public key: only the merchant's server calls the API.
Creating a payment
The body is flat, without the data.attributes wrapper.
| Corefy | This API |
|---|---|
reference_id | reference: up to 128 characters, unique per merchant within an environment |
amount as a decimal in the account currency, service_amount in the service currency | amountMinor: a string holding an integer of minor units of the service currency. The divisor is minorUnit in the service list |
currency | None: the service sets the currency |
service | service: a code from GET /api/v1/services; the codes are different |
service_fields with provider names | fields keyed as in the service list (payer.tax_id, payer.name), or fieldsOnPage: true so that the payment page collects the fields |
customer, about twenty fields | customer.id and customer.country; the payer's data goes in fields |
return_url, return_urls | returnUrl, one address; with the payment page, an origin from the allowed list |
metadata | metadata |
test_mode | None: the key sets the environment |
callback_url | callbackUrl: the notification address of this payment instead of the environment address (refunds and payouts have the same field); signed with the environment secret, issued once with POST /api/v1/notifications/secret: Address in the request |
expires, description, descriptor, flow, options, token | None. The payment deadline is set by an administrator and comes in expiresAt |
Payment page
hpp_url maps to pageUrl: the link to the payment page of this payment. The payment method is not chosen on the page: the checkout chooses it by naming the service at creation. A checkout that draws the payment itself takes action: a redirect to the provider's page or payment details. Details: Payment page.
Response and statuses
idis thepr_…payment ID; keep it next to the order.resolutionmaps toreason.- Amounts come as strings in minor units, timestamps as ISO 8601 strings in UTC.
- The review flag is separate:
inReview. While it istrue, do not credit, whatever the status.
| Corefy | This API |
|---|---|
created | CREATED |
processing | PROCESSING, or AWAITING_CUSTOMER while waiting for the payer |
process_pending | PROCESSING with inReview: true: the outcome is unknown, this is not a decline |
process_error | No separate status: attempt retries happen inside the payment |
processed | SUCCEEDED. A payment never leaves it, and a refund does not change it |
partially_processed | PARTIALLY_PAID under review |
process_failed | FAILED |
expired | EXPIRED; late money moves it to SUCCEEDED, PARTIALLY_PAID or OVERPAID |
refunded, partially_refunded | SUCCEEDED; the refunded sum is in refundedMinor, the refunds themselves are separate objects |
| A Firewall decline | REJECTED with the reason firewall_blocked or customer_blocked; do not credit |
terminated | No counterpart: there is no payment cancellation through the API |
| Chargebacks, authorization and card verification | None |
What each status means and when to credit: Payment statuses.
Callbacks
A Corefy callback maps to a payment.updated, refund.updated or payout.updated notification: Notifications.
| Corefy | This API |
|---|---|
SHA-1 signature in the X-Signature header or the signature field | HMAC-SHA-256 per Standard Webhooks: the webhook-id, webhook-timestamp, webhook-signature headers |
| Body in the invoice format | Event body: id, type, sequence and a snapshot of the payment, refund or payout |
| Up to 100 retries | 30 attempts, about 20 hours |
Order by the updated field | Order by sequence |
Credit not by the notification body but by the payment you read: status SUCCEEDED, inReview is false, the amount in paidMinor, once per id.
Keys and authentication
| Corefy | This API |
|---|---|
| Basic made of the commerce account number and a key | Authorization: Bearer <key>; the key can also go as the Basic user name with an empty password |
Test and live keys, the test_mode flag | An ak_test_ or ak_live_ key: the key sets the environment, there is no flag in the body |
| A public key for the browser | None |
How to issue, rotate and revoke a key: Authentication.
Retrying a request
- Corefy has no retry header, this API has one:
Idempotency-Key. A retry with the same key and the same body returns the same payment: Retrying a request. For a refund and a payout the key is required. - A repeated
referencewithout a key gets a 409 error with the rulepayment_reference_exists, anddetails.paymentIdnames the payment already created. Per the Corefy specification, the same situation gets a 409 with the invoice already created. - A payment whose creation response never arrived is found by the order number:
GET /api/v1/payments?reference=….
Errors
The error body is the same on every endpoint: error.code, error.message, error.details. Handle code and details.rule, not the text: Errors. A body validation error that Corefy returned as 422 is a 400 here with the code validation_failed or bad_amount; a 422 means the payer's data failed validation.
Checks before switching
In the test environment, with a test key:
GET /api/v1/meanswers with theTESTenvironment.- The checkout takes the service code, fields and amount limits from
GET /api/v1/services, not from its own settings. - Every test data label behaves as the table says: crediting only on
SUCCEEDEDwithout review,timeout_paiddoes not turn into a decline,underpaidandoverpaidare not credited. - A dropped connection after sending a creation and a retry with the same
Idempotency-Keyresult in one payment. - A notification with a foreign signature is rejected, and a repeated notification with the same
idchanges nothing. - Without notifications, the checkout learns the outcome by reading no more often than once every 5 seconds per payment.
- The checkout re-reads expired payments in a reconciliation, with or without notifications.
- A 429 waits for
RateLimit-Resetand does not lose the order: Limits.
Switching method by method
- Running in parallel. The checkout holds both clients, Corefy and this API, and a setting chooses which one each payment method goes through. A payment lives out where it was created: its status and refunds are handled by whoever created it.
- Moving the flow. Methods move one at a time. Before the move a method passes the checks above; after it, new payments of that method are created here, and earlier ones are read to the end at Corefy.
- Rolling back. The method goes back to Corefy with the same setting. An unfinished payment is never recreated elsewhere: if the first one went through, the payer would pay twice. It is read here until it reaches a final status.
Live intake is closed: while it is closed, the switch is checked in the test environment.