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

CorefyThis API
POST /api/payment-invoicesPOST /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}/refundPOST /api/v1/payments/:id/refunds: Refunds
POST /public-api/payment-prerequestGET /api/v1/services: Services and amounts
POST /api/payout-invoicesPOST /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 invoicePOST /api/v1/payouts/:id/cancel: cancellation while the payout is not sent
payout-prerequestGET /api/v1/services, services with direction: PAYOUT
Capture and void, payment retry, batch payouts and starting a payout (process), balances, reportsNone

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.

CorefyThis API
reference_idreference: up to 128 characters, unique per merchant within an environment
amount as a decimal in the account currency, service_amount in the service currencyamountMinor: a string holding an integer of minor units of the service currency. The divisor is minorUnit in the service list
currencyNone: the service sets the currency
serviceservice: a code from GET /api/v1/services; the codes are different
service_fields with provider namesfields 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 fieldscustomer.id and customer.country; the payer's data goes in fields
return_url, return_urlsreturnUrl, one address; with the payment page, an origin from the allowed list
metadatametadata
test_modeNone: the key sets the environment
callback_urlcallbackUrl: 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, tokenNone. 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

  • id is the pr_… payment ID; keep it next to the order.
  • resolution maps to reason.
  • Amounts come as strings in minor units, timestamps as ISO 8601 strings in UTC.
  • The review flag is separate: inReview. While it is true, do not credit, whatever the status.
CorefyThis API
createdCREATED
processingPROCESSING, or AWAITING_CUSTOMER while waiting for the payer
process_pendingPROCESSING with inReview: true: the outcome is unknown, this is not a decline
process_errorNo separate status: attempt retries happen inside the payment
processedSUCCEEDED. A payment never leaves it, and a refund does not change it
partially_processedPARTIALLY_PAID under review
process_failedFAILED
expiredEXPIRED; late money moves it to SUCCEEDED, PARTIALLY_PAID or OVERPAID
refunded, partially_refundedSUCCEEDED; the refunded sum is in refundedMinor, the refunds themselves are separate objects
A Firewall declineREJECTED with the reason firewall_blocked or customer_blocked; do not credit
terminatedNo counterpart: there is no payment cancellation through the API
Chargebacks, authorization and card verificationNone

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.

CorefyThis API
SHA-1 signature in the X-Signature header or the signature fieldHMAC-SHA-256 per Standard Webhooks: the webhook-id, webhook-timestamp, webhook-signature headers
Body in the invoice formatEvent body: id, type, sequence and a snapshot of the payment, refund or payout
Up to 100 retries30 attempts, about 20 hours
Order by the updated fieldOrder 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

CorefyThis API
Basic made of the commerce account number and a keyAuthorization: Bearer <key>; the key can also go as the Basic user name with an empty password
Test and live keys, the test_mode flagAn ak_test_ or ak_live_ key: the key sets the environment, there is no flag in the body
A public key for the browserNone

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 reference without a key gets a 409 error with the rule payment_reference_exists, and details.paymentId names 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:

  1. GET /api/v1/me answers with the TEST environment.
  2. The checkout takes the service code, fields and amount limits from GET /api/v1/services, not from its own settings.
  3. Every test data label behaves as the table says: crediting only on SUCCEEDED without review, timeout_paid does not turn into a decline, underpaid and overpaid are not credited.
  4. A dropped connection after sending a creation and a retry with the same Idempotency-Key result in one payment.
  5. A notification with a foreign signature is rejected, and a repeated notification with the same id changes nothing.
  6. Without notifications, the checkout learns the outcome by reading no more often than once every 5 seconds per payment.
  7. The checkout re-reads expired payments in a reconciliation, with or without notifications.
  8. A 429 waits for RateLimit-Reset and does not lose the order: Limits.

Switching method by method

  1. 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.
  2. 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.
  3. 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.

API v1 · built 2026-11-18 · release f13e6bf

The API reference is built from the server code: it never describes an endpoint that does not exist.