Payment page guide
How to build, step by step, a checkout that sends the payer to the payment page, and how to check it in the test environment.
A guide for a checkout without its own payment form: the payer is sent to the payment page, and the outcome comes in a notification or from reading the payment. What the page itself can do: Payment page.
Before you start
- A test key and a checked
GET /api/v1/mecall: Getting started. - The list of return address origins: ask a Target administrator to add the scheme, host name and port of the page the payer returns to. Without this,
returnUrlgets an error. - A notification address and its secret, if the checkout will wait for notifications rather than only read the payment: Notifications.
Step 1. Create the payment
Create the payment with a retry key, a return address and fieldsOnPage: true if the page should collect the payer fields:
{
"reference": "order-1001",
"service": "pix_brl_requisite",
"amountMinor": "1250",
"customer": { "id": "player-42", "country": "BR" },
"returnUrl": "https://shop.example/return/order-1001",
"fieldsOnPage": true
}Keep id and pageUrl from the response next to the order. If the connection drops, retry the same request with the same key: Retrying a request.
Step 2. Send the payer
Send the payer to pageUrl by navigation. The lang parameter before # sets the language. If pageUrl is null, there is no page. Show a payment with fields in fields in your own form by action. A fieldsOnPage payment cannot be paid without the page and will expire: collect the fields in your own form and create a new payment with fields and a new order number.
Step 3. Learn the outcome
The payer's return to returnUrl does not report the outcome. The outcome comes in one of two ways:
- a
payment.updatednotification to your address: check the signature, then read the payment bypayment.idfrom the notification; - reading
GET /api/v1/payments/:id, no more often than once every 5 seconds, until a final status without review, orPARTIALLY_PAIDorOVERPAID.
Either way, re-read expired payments in a reconciliation: money for them may arrive later, and a notification may not arrive.
Credit on SUCCEEDED when inReview is false, exactly paidMinor, once per payment: When to credit.
Step 4. Check in the test environment
- A payment with
fieldsOnPage: trueopens bypageUrl, the form asks for the service fields, and after submission the payment leavesCREATED. - A payment without
fieldsOnPagewith the fields infieldsopens straight on the payment details or the redirect to the provider. - A
returnUrloutside the origin list gets thereturn_url_not_allowederror; an address from the list is accepted. - The test data labels
paid,declined,timeout_paidandunderpaidgive the same outcome on the page and in the checkout, and only the paid one without review is credited. - A link with
lang=esopens the page in Spanish. - A creation retry with the same key returns the same
pageUrl.