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

  1. A test key and a checked GET /api/v1/me call: Getting started.
  2. 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, returnUrl gets an error.
  3. 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:

Request body
{
  "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.updated notification to your address: check the signature, then read the payment by payment.id from the notification;
  • reading GET /api/v1/payments/:id, no more often than once every 5 seconds, until a final status without review, or PARTIALLY_PAID or OVERPAID.

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

  1. A payment with fieldsOnPage: true opens by pageUrl, the form asks for the service fields, and after submission the payment leaves CREATED.
  2. A payment without fieldsOnPage with the fields in fields opens straight on the payment details or the redirect to the provider.
  3. A returnUrl outside the origin list gets the return_url_not_allowed error; an address from the list is accepted.
  4. The test data labels paid, declined, timeout_paid and underpaid give the same outcome on the page and in the checkout, and only the paid one without review is credited.
  5. A link with lang=es opens the page in Spanish.
  6. A creation retry with the same key returns the same pageUrl.

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.