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

  1. 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.
  2. Create the payment with a retry key in the Idempotency-Key header:

    curl -sS -X POST https://api.thetarget.cc/api/v1/payments \
      -H "Authorization: Bearer $TARGET_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.

  3. Send the payer by action: What to show the payer.
  4. Read the payment until its outcome is known: Learning the outcome.
  5. Credit only on SUCCEEDED with inReview equal to false, and exactly paidMinor: 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 to action.url. The returnUrl, 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

  • presentation says how to show them: qr a code to scan and copy, transfer bank transfer details, voucher a number to pay at a cash desk.
  • payload is the main string of the payment details, fields are the labels for the screen in display order.
  • Show the amount payAmountMinor in the currency payCurrency, not the payment amount: with a conversion they differ. With payAmountChanged: 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 Target 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.thetarget.cc/api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d \
  -H "Authorization: Bearer $TARGET_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 inReview is false, or the status is PARTIALLY_PAID or OVERPAID: their review is never lifted through the API, our side decides about the money. EXPIRED is 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.

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.