Accepting a payment
How to create a payment, where to send the payer and how to learn the outcome.
The merchant's server creates a payment with one request. The response to the creation already names the payment: its ID, its status and where to send the payer. You learn the outcome of the payment by reading it.
Steps
- Pick a service from the service list. The service defines the currency, the payment method and the payer fields: you do not send them again.
Create the payment with a retry key in the
Idempotency-Keyheader:curl -sS -X POST https://api.paydex.co.uk/api/v1/payments \ -H "Authorization: Bearer $PAYDEX_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 5f0c2b9e-8d41-4a7c-9e2f-3b6d1a4c8e07" \ -d '{ "reference": "order-1001", "service": "pix_brl_redirect", "amountMinor": "1250", "customer": { "id": "player-42", "country": "BR" }, "fields": { "payer.tax_id": "12345678909", "payer.name": "Maria Silva" }, "returnUrl": "https://shop.example/return/order-1001", "metadata": { "cartId": "c-77" } }'A 201 response carries the payment. Request and response fields: reference.
- Send the payer by
action: What to show the payer. - Read the payment until its outcome is known: Learning the outcome.
- Credit only on
SUCCEEDEDwithinReviewequal tofalse, and exactlypaidMinor: Payment statuses.
The order number reference is unique per merchant within an environment: a second payment for the same order is not created. How to retry a request whose response never arrived: Retrying a request.
What to show the payer
Send the payer to the payment page by pageUrl, or show them action in your own form:
redirect: send the payer toaction.url. ThereturnUrl, if you set it, is passed to the provider: the payer comes back there after paying.requisite: show the payment details, Payment details.
action is present only while the payment waits for the payer: it is not under review and has not reached expiresAt. null means "wait": the payment is still being created or processed, is under review, the payment details are not issued yet, or the deadline has passed. A decline is shown by the status, not by an empty action.
Payment details
presentationsays how to show them:qra code to scan and copy,transferbank transfer details,vouchera number to pay at a cash desk.payloadis the main string of the payment details,fieldsare the labels for the screen in display order.- Show the amount
payAmountMinorin the currencypayCurrency, not the payment amount: with a conversion they differ. WithpayAmountChanged: true, tell the payer "transfer exactly this amount": the provider recognizes the transfer by its amount. - The payment details are valid until
action.expiresAt.
Payment deadline
Every payment has a deadline, expiresAt; its length is set for the merchant by a Paydex administrator. A payment that is not paid by the deadline gets the EXPIRED status. If the provider confirms the money later, the payment still moves to SUCCEEDED, or to PARTIALLY_PAID or OVERPAID if the amount does not match: Late money.
Learning the outcome
The outcome comes in a payment.updated notification, or you learn it by reading the payment by the id from the creation response. The checkout reads an unfinished payment itself, even if it waits for notifications:
curl -sS https://api.paydex.co.uk/api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d \
-H "Authorization: Bearer $PAYDEX_API_KEY"- Read each unfinished payment no more often than once every 5 seconds. Reading has its own rate limit, shared by all your payments, and does not use up the creation limit: Limits.
- Stop when the status is final and
inReviewisfalse, or the status isPARTIALLY_PAIDorOVERPAID: their review is never lifted through the API, our side decides about the money.EXPIREDis the only final status that can still change: a notification tells you about late money, but delivery is not guaranteed, so re-read expired payments in a reconciliation, for example once a day, with or without notifications. - The outcome of a payment under review (
inReview: true) is settled on our side, by a provider inquiry or by a person. Read it once every few minutes.
Live environment
A live key cannot create a payment: the request gets a 403 error with the rule live_intake_closed, described under Environments. The test environment works fully, and test data sets the outcome there.