API reference

The path, response fields and errors of every released API endpoint.

The reference is built from the server schemas, and a test bench checks errors, paths and responses of a running server against them wherever they can be triggered without a provider.

Common to all endpoints

  • Base URL: https://api.thetarget.cc.
  • Sign-in with an API key: Authentication.
  • Error shape and common errors: Errors.
  • Rate limit and the no-caching rule: Limits.

Check the key

GET/api/v1/mesince 2026-11-12

Returns the merchant, the environment and the public part of the key that signed the request. Changes nothing. Start your integration with this request: it shows that the key is accepted and which environment it belongs to.

  • The key secret is never returned in the response.
  • The labels an administrator gave the key in the console are not in the response.

Request

curl -sS https://api.thetarget.cc/api/v1/me \
  -H "Authorization: Bearer $TARGET_API_KEY"

No query parameters. A parameter with an unknown name is rejected.

The request has no body.

Response 200

FieldTypePresentDescription
merchantobjectalwaysThe merchant the key was issued to.
merchant.codestringalwaysMerchant code. Set when the merchant is created and never changes.
merchant.namestringalwaysMerchant name as registered with us.
environmentstringLIVE TESTalwaysThe key's environment. Every request made with this key runs in this environment.
keyobjectalwaysThe key that signed the request.
key.keyIdstringalwaysThe public part of the key. Not a secret: use it to refer to the key when talking to support.
key.expiresAtstring, ISO 8601 timestampor nullalwaysWhen the key stops being accepted, in UTC. null: no expiry is set.
Example response. The values are made up.
{
  "merchant": {
    "code": "example-shop",
    "name": "Example Shop"
  },
  "environment": "TEST",
  "key": {
    "keyId": "ak_test_examplekey000001",
    "expiresAt": "2027-02-10T00:00:00.000Z"
  }
}

Errors

The endpoint has no errors of its own, only the errors common to all endpoints.

List services

GET/api/v1/servicessince 2026-11-12

Returns the services the merchant can accept a payment with in the key's environment: payment method, currency, amount limits, payer fields and fee. Changes nothing.

  • The list contains only services that are fully ready to work. A service that is missing something on our side is absent from the response, not flagged.
  • The list depends on the key's environment: a test key and a live key of the same merchant may get different lists.
  • Amounts come as strings in minor units of the service currency. To show an amount to a person, divide it by minorUnit.
  • The list changes when an administrator enables or disables a service. Do not keep it for longer than a few minutes.

Request

curl -sS https://api.thetarget.cc/api/v1/services \
  -H "Authorization: Bearer $TARGET_API_KEY"

No query parameters. A parameter with an unknown name is rejected.

The request has no body.

Response 200

FieldTypePresentDescription
environmentstringLIVE TESTalwaysThe key's environment. The list is built for it.
itemsarray of objectsalwaysThe merchant's services ready to work right now; only PAYIN ones can accept a payment. May be empty.
items[].codestringalwaysService code. Use it to name the service when creating a payment.
items[].directionstringPAYIN PAYOUTalwaysDirection of money: PAYIN payment acceptance, PAYOUT payout.
items[].methodobjectalwaysPayment method.
items[].method.codestringalwaysPayment method code.
items[].method.namestringalwaysPayment method name to show to people.
items[].currencystringalwaysService currency: the payment amount, the limits and a fixed fee are set in it.
items[].networkstringor nullalwaysNetwork, if the currency has several (cryptocurrencies). null: no network.
items[].flowstringDIRECT REDIRECT REQUISITE HOSTED_FIELDSalwaysHow the payment goes: DIRECT the merchant's server sends the payer's data, REDIRECT the payer goes to the provider's page, REQUISITE the payer gets payment details (QR, code, account), HOSTED_FIELDS the payer fills in the provider's ready-made form.
items[].minorUnitintegeralwaysHow many minor units are in one unit of the currency: 100 for BRL, 1 for JPY.
items[].amountobjectalwaysAmount limits.
items[].amount.minMinorstringor nullalwaysThe smallest payment amount in minor units. null: no lower limit.
items[].amount.maxMinorstringor nullalwaysThe largest payment amount in minor units. null: no upper limit.
items[].fieldsarray of objectsalwaysPayer fields the service accepts, in the same order as on the payment form.
items[].fields[].keystringalwaysField name. The field is sent under this name when creating a payment.
items[].fields[].kindstringTEXT DIGITS EMAIL PHONE DATE COUNTRYalwaysValue kind: TEXT string, DIGITS digits only, EMAIL email address, PHONE phone number in E.164 format, DATE date as YYYY-MM-DD, COUNTRY two-letter ISO 3166-1 country code.
items[].fields[].requiredbooleanalwaysWhether the field is required for this service.
items[].fields[].patternstringor nullalwaysRegular expression the whole value must match. null: no pattern check.
items[].fields[].maxLengthintegeralwaysMaximum value length in characters.
items[].feeobjectalwaysThe merchant's fee for a payment with this service.
items[].fee.typestringPERCENT FIXEDalwaysFee kind: PERCENT a percentage of the amount, FIXED a fixed amount.
items[].fee.percentstringor nullalwaysPercentage as a string with four decimal places, such as "1.9000". Set for PERCENT, otherwise null.
items[].fee.amountMinorstringor nullalwaysFixed amount in minor units of the service currency. Set for FIXED, otherwise null.
Example response. The values are made up.
{
  "environment": "TEST",
  "items": [
    {
      "code": "pix_brl_requisite",
      "direction": "PAYIN",
      "method": {
        "code": "PIX",
        "name": "Pix"
      },
      "currency": "BRL",
      "network": null,
      "flow": "REQUISITE",
      "minorUnit": 100,
      "amount": {
        "minMinor": "100",
        "maxMinor": "10000000"
      },
      "fields": [
        {
          "key": "payer.tax_id",
          "kind": "DIGITS",
          "required": true,
          "pattern": "^(\\d{11}|\\d{14})$",
          "maxLength": 14
        },
        {
          "key": "payer.name",
          "kind": "TEXT",
          "required": false,
          "pattern": null,
          "maxLength": 128
        }
      ],
      "fee": {
        "type": "PERCENT",
        "percent": "1.9000",
        "amountMinor": null
      }
    },
    {
      "code": "pix_brl_redirect",
      "direction": "PAYIN",
      "method": {
        "code": "PIX",
        "name": "Pix"
      },
      "currency": "BRL",
      "network": null,
      "flow": "REDIRECT",
      "minorUnit": 100,
      "amount": {
        "minMinor": "100",
        "maxMinor": "10000000"
      },
      "fields": [
        {
          "key": "payer.tax_id",
          "kind": "DIGITS",
          "required": true,
          "pattern": "^(\\d{11}|\\d{14})$",
          "maxLength": 14
        },
        {
          "key": "payer.name",
          "kind": "TEXT",
          "required": false,
          "pattern": null,
          "maxLength": 128
        }
      ],
      "fee": {
        "type": "PERCENT",
        "percent": "1.9000",
        "amountMinor": null
      }
    },
    {
      "code": "boleto_brl_requisite",
      "direction": "PAYIN",
      "method": {
        "code": "BOLETO",
        "name": "Boleto bancário"
      },
      "currency": "BRL",
      "network": null,
      "flow": "REQUISITE",
      "minorUnit": 100,
      "amount": {
        "minMinor": "500",
        "maxMinor": "1000000"
      },
      "fields": [
        {
          "key": "payer.tax_id",
          "kind": "DIGITS",
          "required": true,
          "pattern": "^(\\d{11}|\\d{14})$",
          "maxLength": 14
        },
        {
          "key": "payer.name",
          "kind": "TEXT",
          "required": true,
          "pattern": null,
          "maxLength": 128
        },
        {
          "key": "payer.email",
          "kind": "EMAIL",
          "required": false,
          "pattern": null,
          "maxLength": 254
        }
      ],
      "fee": {
        "type": "FIXED",
        "percent": null,
        "amountMinor": "250"
      }
    }
  ]
}

Errors

The endpoint has no errors of its own, only the errors common to all endpoints.

Create a payment

POST/api/v1/paymentssince 2026-11-13

Creates a payment and makes the first attempt at the provider: at once, or with fieldsOnPage after the payer sends the fields on the payment page. The response holds the payment: its ID, its status and where to send the payer.

  • The Idempotency-Key header makes a retry safe: Retrying a request.
  • A new payment gets 201. A retry gets the same payment as it is now, code 200 or 201, and the Idempotency-Replayed: true header.
  • Live intake is closed: a live key cannot create a payment, a 403 error with the rule live_intake_closed.

Request

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"
    }
  }'

No query parameters. A parameter with an unknown name is rejected.

FieldTypeRequiredDescription
referencestringyesYour order number: 1 to 128 characters, with no leading or trailing spaces and no invisible characters. A second payment with the same number is not created within the environment.
servicestringyesService code from the service list. The service sets the currency, the payment method and the payer fields.
amountMinorstringyesThe amount as a string: an integer of minor units of the service currency, up to 15 digits. A JSON number instead of a string is rejected.
customerobjectyesThe customer who pays.
customer.idstringyesYour customer ID: 1 to 128 characters, with no leading or trailing spaces and no invisible characters.
customer.countrystringnoThe customer's country: a two-letter ISO 3166-1 code in capitals (GB, not UK).
fieldsobject with arbitrary keysnoPayer fields keyed as in the service list, for example payer.tax_id. A field the service does not have is rejected.
returnUrlstringnoWhere to return the payer after paying: https, up to 1024 characters, without a user name or password; with the payment page, an origin from the merchant's list. In the test environment http is allowed too: Payment page.
callbackUrlstringnoNotification address for this object (Corefy callback_url): its notifications go here instead of the environment address, signed with the environment secret. https up to 2048 characters, http also allowed in the test environment; a full internet host name; the default port, 443, 8443, 80 or 8080; without a user name or password. Requires the environment secret: Address in the request.
fieldsOnPagebooleannotrue: the payment page collects the payer fields, and fields is not sent. The payment waits for the fields in CREATED, the first attempt starts when the payer sends them. A blocked customer gets REJECTED at once: Payment page.
metadataobject with arbitrary keysnoYour labels: a JSON object of up to 4096 characters when serialized and up to 16 levels deep. Returned in the response as is. In the test environment the sandbox field sets the payment outcome: Test data.

Response 201

FieldTypePresentDescription
idstringalwaysPayment ID: pr_ followed by 22 characters. Use it to read the payment.
referencestringalwaysThe order number sent at creation.
servicestringor nullalwaysCode of the service the payment was created with.
environmentstringTEST LIVEalwaysThe payment's environment: the environment of the key that created it.
statusstringCREATED PROCESSING AWAITING_CUSTOMER SUCCEEDED PARTIALLY_PAID OVERPAID FAILED CANCELLED EXPIRED REJECTEDalwaysPayment status: Payment statuses.
reasonstringor nullalwaysReason for the status as a code; null when there is nothing to name: Reasons.
inReviewbooleanalwaysThe outcome is still being settled on our side: by a provider inquiry or by a person. While it is true, the payment is not credited.
amountMinorstringalwaysThe requested amount as a string, in minor units of the payment currency.
currencystringalwaysPayment currency: the service currency.
networkstringor nullalwaysNetwork, if the currency has several. null: no network.
paidMinorstringor nullalwaysThe amount confirmed by the provider, in minor units of the payment currency. This is the amount you credit, and only with SUCCEEDED. null: no money confirmed.
feeMinorstringor nullalwaysThe merchant's fee for the payment, in minor units of the payment currency, calculated at creation.
refundedMinorstringalwaysHow much has been returned to the payer by successful refunds, in minor units of the payment currency. Refunds do not change the payment status: Refunds.
actionobjector nullalwaysWhat the payer should do; present only while the payment waits for them: What to show the payer. null: nothing to show, wait by the status.
action.typestringredirect requisitealwaysredirect: send the payer to url; requisite: show the payment details.
action.urlstringnot alwaysWhere to send the payer: the provider's page or, with fieldsOnPage, the payment page. Only with redirect.
action.requisiteobjectnot alwaysPayment details. Only with requisite: Payment details.
action.requisite.presentationstringqr transfer voucheralwaysHow to show them: qr a code to scan and copy, transfer a transfer by bank details, voucher a number to pay at a cash desk.
action.requisite.payloadstringalwaysThe main string of the payment details: the code content, the account or voucher number.
action.requisite.fieldsobject with arbitrary keysalwaysLabels for the screen in display order: an upper-case key is an account name (CLABE, IBAN, ALIAS), lower-case ones are code, account, holder, bank, reference. May be empty.
action.requisite.payAmountMinorstringalwaysHow much to transfer, in minor units of payCurrency.
action.requisite.payCurrencystringalwaysCurrency of the amount to pay. With conversion it differs from the payment currency.
action.requisite.payAmountChangedbooleanalwaystrue: the provider asked for an amount different from the payment amount; tell the payer "transfer exactly this amount".
action.expiresAtstringor nullnot alwaysUntil when the payment details are valid, in UTC. null: no deadline named. Only with requisite.
customerobjectalwaysThe customer who pays.
customer.idstringalwaysThe customer ID sent at creation.
returnUrlstringor nullalwaysThe payer's return address as the server parsed it. null: not set.
callbackUrlstringor nullalwaysThe payment's notification address as the server parsed it. null: not set, notifications go to the environment address.
metadataany valuealwaysYour labels, as sent at creation.
createdAtstring, ISO 8601 timestampalwaysWhen the payment was created, in UTC.
expiresAtstring, ISO 8601 timestampor nullalwaysPayment deadline, in UTC: Payment deadline.
finalizedAtstring, ISO 8601 timestampor nullalwaysWhen the payment got a final status, in UTC. null: not yet.
pageUrlstringor nullalwaysLink to the payment page of this payment: send the payer there instead of your own form. null: there is no page or the link has expired: Payment page.
Example response. The values are made up.
{
  "id": "pr_8k3m2q7w9x4t6v5n2b8c4d",
  "reference": "order-1001",
  "service": "pix_brl_redirect",
  "environment": "TEST",
  "status": "AWAITING_CUSTOMER",
  "reason": null,
  "inReview": false,
  "amountMinor": "1250",
  "currency": "BRL",
  "network": null,
  "paidMinor": null,
  "feeMinor": "24",
  "refundedMinor": "0",
  "action": {
    "type": "redirect",
    "url": "https://pay.provider.example/checkout/7Hq2xW"
  },
  "customer": {
    "id": "player-42"
  },
  "returnUrl": "https://shop.example/return/order-1001",
  "callbackUrl": null,
  "metadata": {
    "cartId": "c-77"
  },
  "createdAt": "2026-11-13T09:15:02.481Z",
  "expiresAt": "2026-11-13T09:45:02.481Z",
  "finalizedAt": null,
  "pageUrl": "https://pay.example/#u30M8e5ErKC8wPc5t3uTXxOuwv1Tf1wp3t2IPdQpuoNsmxnLlntWPZ2Ws0E"
}

Errors

In addition to the common errors:

HTTPCode and ruleWhen it happens and what to do
400validation_failed

The body failed the shape check: an extra field, a value of the wrong type (such as the amount as a JSON number rather than a string) or a missing required field. details.issues names the fields.

Fix the body against the field table.

Example response
POST /api/v1/payments

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "Request body failed validation",
    "details": {
      "issues": [
        {
          "field": "amountMinor",
          "message": "Expected string, received number"
        }
      ]
    }
  }
}
400validation_failed

A value failed validation: details.field names the field, details.rule the rule.

  • reference_shape: reference is empty, longer than 128 characters, or has leading or trailing spaces, control or invisible characters.
  • external_ref_shape: The same for customer.id.
  • country_code: customer.country is not an assigned two-letter ISO 3166-1 code in capitals.
  • return_url: returnUrl is not https (http is allowed in the test environment), has no host name, has a user name or password, or is longer than 1024 characters.
  • return_url_not_allowed: The installation has a payment page, and the returnUrl origin is not in the merchant's list of allowed origins: an administrator adds it.
  • metadata_shape: metadata is not a JSON object, is longer than 4096 characters when serialized, is deeper than 16 levels or holds a number that JSON cannot represent exactly.
  • reserved_key: The body has a __proto__ key.
  • fields_on_page_conflict: Both fields and fieldsOnPage: true are sent.
  • idempotency_key_shape: The Idempotency-Key header is empty, longer than 128 characters, or holds spaces or characters outside visible ASCII.
  • unknown_field: fields has a key the service does not have.
  • field_not_accepted: The service has the field, but payment intake does not accept it.
  • required: A field the service requires is missing.
  • field_shape: The field value is empty or has leading or trailing spaces, control or invisible characters; the payer's name has no letters at all.
  • field_too_long: The value is longer than the service field's maxLength.
  • field_kind: The value is not of the kind the service field's kind requires.
  • field_pattern: The value does not match the service field's pattern.
  • callback_url_invalid: callbackUrl is not a URL, is longer than 2048 characters, or has a user name or password, a fragment, a space or a control character, or a port other than 443, 8443, 80, 8080.
  • callback_url_scheme: callbackUrl is not https (http is allowed in the test environment).
  • callback_url_internal: callbackUrl leads to an internal or service network: an IP address of a private or service network, localhost, a name without a dot, or a service domain (.local, .internal, .lan, .localdomain, .home.arpa).

Fix the value named by details.field.

Example response
POST /api/v1/payments

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "Order reference: 1 to 128 characters without leading or trailing spaces, control or invisible characters",
    "details": {
      "field": "reference",
      "rule": "reference_shape"
    }
  }
}
400bad_amount

amountMinor is not a string holding a positive integer of up to 15 digits: for example "12.50" or "0".

Send the amount as a string in minor units: "1250", not "12.50".

Example response
POST /api/v1/payments

HTTP/1.1 400

{
  "error": {
    "code": "bad_amount",
    "message": "Amount is a string with a positive integer number of minor currency units, up to 15 digits",
    "details": {
      "field": "amountMinor"
    }
  }
}
400bad_amount

The amount is well-formed, but the service does not accept it.

  • amount_out_of_range: The amount is outside the service limits; details.minMinor and details.maxMinor name the limits.
  • amount_not_above_fee: The amount is not greater than the service fee: the merchant would receive nothing.

Send an amount within the service limits and above its fee.

Example response
POST /api/v1/payments

HTTP/1.1 400

{
  "error": {
    "code": "bad_amount",
    "message": "Amount is outside the service limits",
    "details": {
      "field": "amountMinor",
      "rule": "amount_out_of_range",
      "minMinor": "100",
      "maxMinor": "10000000"
    }
  }
}
403forbiddenlive_intake_closed

A payment is created with a live key, and live intake is closed. Checked before the request body.

Create payments with a test key.

Example response
POST /api/v1/payments

HTTP/1.1 403

{
  "error": {
    "code": "forbidden",
    "message": "Live payment intake is closed: the test environment is open",
    "details": {
      "rule": "live_intake_closed"
    }
  }
}
409conflict

No payment can be created with the requested service right now.

  • service_unavailable: The service is not in the key's service list or is no longer available.
  • service_not_payin: The service is not for accepting payments.
  • card_data_not_accepted: The service requires card details, and payment intake does not accept them.
  • service_field_unsupported: The service requires a field that payment intake does not accept; details.field names it.

Take the service from a fresh service list.

Example response
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "Service unavailable: GET /api/v1/services lists the available services",
    "details": {
      "rule": "service_unavailable"
    }
  }
}
409conflictpayment_reference_exists

A payment with this reference has already been created in the environment; details.paymentId names it.

Read that payment instead of creating a new one.

Example response
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "A payment with this order reference has already been created",
    "details": {
      "rule": "payment_reference_exists",
      "paymentId": "pr_8k3m2q7w9x4t6v5n2b8c4d"
    }
  }
}
409conflictrequest_in_progress

A request with this retry key is still running.

Retry in a few seconds with the same key and the same body.

Example response
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "A request with this idempotency key is still running: retry later",
    "details": {
      "rule": "request_in_progress"
    }
  }
}
409conflictidempotency_key_reused

The retry key has already been used by another request: with a different body or for another operation.

A retry sends the same request; a new operation gets a new key.

Example response
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "This idempotency key has already been used with another request",
    "details": {
      "rule": "idempotency_key_reused"
    }
  }
}
409conflictidempotency_key_unverifiable

The retry key was recorded in a way that our side cannot check the body against.

Give support the retry key and the time of the request.

Example response
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "The idempotency key was recorded under an encryption key that is not available here: the request cannot be checked",
    "details": {
      "rule": "idempotency_key_unverifiable"
    }
  }
}
409conflict

A parallel request changed the same data at the same moment, for example the customer. No payment was created; details.requestId names the request.

Retry the same request.

Example response
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "The operation conflicts with the current state of the data",
    "details": {
      "requestId": "00000000-0000-4000-8000-000000000000"
    }
  }
}
409keyring_unavailable

The encryption keys that record the retry key and the payer's data are unavailable on our side. The request was not executed.

Retry later. If it keeps happening, give support the time of the request.

Example response
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "keyring_unavailable",
    "message": "The test environment encryption keys are not loaded",
    "details": {
      "environment": "TEST"
    }
  }
}
422identifier_invalid

The payer's data failed validation, for example the checksum of a tax ID. details.field names the field, details.kind the kind of data, details.rule the check; the value is not echoed in the response.

Fix the field value.

Example response
POST /api/v1/payments

HTTP/1.1 422

{
  "error": {
    "code": "identifier_invalid",
    "message": "Identifier failed validation",
    "details": {
      "field": "fields.payer.tax_id",
      "kind": "TAX_ID",
      "rule": "cpf_checksum"
    }
  }
}
409conflict

The payment page cannot collect the payer fields right now.

  • pay_page_unavailable: There is no payment page, and the service has payer fields.
  • fields_on_page_ttl_too_short: The merchant's payment deadline is shorter than five minutes: the payer would not have time to fill in the fields.

Collect the fields with your own form and send them in fields.

Example response
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "The payment page is not enabled for this installation: send the payer fields in fields",
    "details": {
      "rule": "pay_page_unavailable"
    }
  }
}
409conflictcallback_secret_missing

callbackUrl is set, but the API key's environment has no notification signing secret: there is nothing to sign the notifications with. For a payment the retry key is released; for a refund and a payout the refusal is recorded on the key, like their other refusals after the key.

Issue a secret with POST /api/v1/notifications/secret, or ask an administrator for an environment address. Then repeat the request; for a refund and a payout, with a new retry key: the old key keeps this refusal.

Example response
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "callbackUrl needs the notification signing secret of the environment: POST /api/v1/notifications/secret",
    "details": {
      "rule": "callback_secret_missing"
    }
  }
}
503dependency_unavailable

Payment intake is temporarily not working; no payment was created.

  • transition_policy_missing: Payment intake is not configured on our side.
  • transition_policy_incomplete: Payment intake cannot send the attempt to the provider.
  • transaction_timeout: Payment intake did not finish in time on our side.

Retry later with the same retry key.

Example response
POST /api/v1/payments

HTTP/1.1 503

{
  "error": {
    "code": "dependency_unavailable",
    "message": "Payment intake is not working: it is not configured on our side",
    "details": {
      "rule": "transition_policy_missing"
    }
  }
}

Find a payment by order number

GET/api/v1/paymentssince 2026-11-17

Returns the payment with this order number in the key's environment: zero or one item. This is how you find a payment whose creation response never arrived and that had no retry key.

  • Without reference the path answers with a 501 error: there is no payment list.
  • The rate limit is shared with reading a payment by ID.

Request

curl -sS 'https://api.thetarget.cc/api/v1/payments?reference=order-1001' \
  -H "Authorization: Bearer $TARGET_API_KEY"
FieldTypeRequiredDescription
referencestringyesThe order number as sent at creation, encoded as part of the address: the characters +, &, # and a space would otherwise change the number. Without the parameter the path answers with a 501 error.

The request has no body.

Response 200

FieldTypePresentDescription
itemsarray of objectsalwaysThe payment with this order number, zero or one. Empty: there is no such order in the key's environment.
items[].idstringalwaysPayment ID: pr_ followed by 22 characters. Use it to read the payment.
items[].referencestringalwaysThe order number sent at creation.
items[].servicestringor nullalwaysCode of the service the payment was created with.
items[].environmentstringTEST LIVEalwaysThe payment's environment: the environment of the key that created it.
items[].statusstringCREATED PROCESSING AWAITING_CUSTOMER SUCCEEDED PARTIALLY_PAID OVERPAID FAILED CANCELLED EXPIRED REJECTEDalwaysPayment status: Payment statuses.
items[].reasonstringor nullalwaysReason for the status as a code; null when there is nothing to name: Reasons.
items[].inReviewbooleanalwaysThe outcome is still being settled on our side: by a provider inquiry or by a person. While it is true, the payment is not credited.
items[].amountMinorstringalwaysThe requested amount as a string, in minor units of the payment currency.
items[].currencystringalwaysPayment currency: the service currency.
items[].networkstringor nullalwaysNetwork, if the currency has several. null: no network.
items[].paidMinorstringor nullalwaysThe amount confirmed by the provider, in minor units of the payment currency. This is the amount you credit, and only with SUCCEEDED. null: no money confirmed.
items[].feeMinorstringor nullalwaysThe merchant's fee for the payment, in minor units of the payment currency, calculated at creation.
items[].refundedMinorstringalwaysHow much has been returned to the payer by successful refunds, in minor units of the payment currency. Refunds do not change the payment status: Refunds.
items[].actionobjector nullalwaysWhat the payer should do; present only while the payment waits for them: What to show the payer. null: nothing to show, wait by the status.
items[].action.typestringredirect requisitealwaysredirect: send the payer to url; requisite: show the payment details.
items[].action.urlstringnot alwaysWhere to send the payer: the provider's page or, with fieldsOnPage, the payment page. Only with redirect.
items[].action.requisiteobjectnot alwaysPayment details. Only with requisite: Payment details.
items[].action.requisite.presentationstringqr transfer voucheralwaysHow to show them: qr a code to scan and copy, transfer a transfer by bank details, voucher a number to pay at a cash desk.
items[].action.requisite.payloadstringalwaysThe main string of the payment details: the code content, the account or voucher number.
items[].action.requisite.fieldsobject with arbitrary keysalwaysLabels for the screen in display order: an upper-case key is an account name (CLABE, IBAN, ALIAS), lower-case ones are code, account, holder, bank, reference. May be empty.
items[].action.requisite.payAmountMinorstringalwaysHow much to transfer, in minor units of payCurrency.
items[].action.requisite.payCurrencystringalwaysCurrency of the amount to pay. With conversion it differs from the payment currency.
items[].action.requisite.payAmountChangedbooleanalwaystrue: the provider asked for an amount different from the payment amount; tell the payer "transfer exactly this amount".
items[].action.expiresAtstringor nullnot alwaysUntil when the payment details are valid, in UTC. null: no deadline named. Only with requisite.
items[].customerobjectalwaysThe customer who pays.
items[].customer.idstringalwaysThe customer ID sent at creation.
items[].returnUrlstringor nullalwaysThe payer's return address as the server parsed it. null: not set.
items[].callbackUrlstringor nullalwaysThe payment's notification address as the server parsed it. null: not set, notifications go to the environment address.
items[].metadataany valuealwaysYour labels, as sent at creation.
items[].createdAtstring, ISO 8601 timestampalwaysWhen the payment was created, in UTC.
items[].expiresAtstring, ISO 8601 timestampor nullalwaysPayment deadline, in UTC: Payment deadline.
items[].finalizedAtstring, ISO 8601 timestampor nullalwaysWhen the payment got a final status, in UTC. null: not yet.
items[].pageUrlstringor nullalwaysLink to the payment page of this payment: send the payer there instead of your own form. null: there is no page or the link has expired: Payment page.
Example response. The values are made up.
{
  "items": [
    {
      "id": "pr_8k3m2q7w9x4t6v5n2b8c4d",
      "reference": "order-1001",
      "service": "pix_brl_redirect",
      "environment": "TEST",
      "status": "SUCCEEDED",
      "reason": null,
      "inReview": false,
      "amountMinor": "1250",
      "currency": "BRL",
      "network": null,
      "paidMinor": "1250",
      "feeMinor": "24",
      "refundedMinor": "500",
      "action": null,
      "customer": {
        "id": "player-42"
      },
      "returnUrl": "https://shop.example/return/order-1001",
      "callbackUrl": null,
      "metadata": {
        "cartId": "c-77"
      },
      "createdAt": "2026-11-13T09:15:02.481Z",
      "expiresAt": "2026-11-13T09:45:02.481Z",
      "finalizedAt": "2026-11-13T09:17:40.112Z",
      "pageUrl": null
    }
  ]
}

Errors

In addition to the common errors:

HTTPCode and ruleWhen it happens and what to do
400validation_failed

reference is sent twice or as a list.

Send one order number.

Example response
GET /api/v1/payments?reference=order-1001&reference=order-1002

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "Order reference must be sent once, as a string",
    "details": {
      "field": "reference"
    }
  }
}
400validation_failedreference_shape

The order number is empty, longer than 128 characters, or has leading or trailing spaces, control or invisible characters.

Check the number and encode it as part of the address.

Example response
GET /api/v1/payments?reference=%20order-1001

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "Order reference: 1 to 128 characters without leading or trailing spaces, control or invisible characters",
    "details": {
      "field": "reference",
      "rule": "reference_shape"
    }
  }
}
501not_implemented

A request without reference: there is no payment list.

Read a payment by its ID or by its order number.

Example response
GET /api/v1/payments

HTTP/1.1 501

{
  "error": {
    "code": "not_implemented",
    "message": "The payment list is not open yet. Read a payment by its ID: GET /api/v1/payments/{id}, or by its order reference: GET /api/v1/payments?reference={reference}, with the reference encoded as part of the URL (otherwise + & # and spaces change it)."
  }
}

Read a payment

GET/api/v1/payments/:idsince 2026-11-13

Returns the payment by its ID within the key's environment. Changes nothing. This is how you learn the outcome if the notification did not arrive, and check it before crediting.

  • Another merchant's payment, a payment of another environment and a malformed ID all get the same 404 response.
  • Reading has its own rate limit, separate from creation: Limits.

Request

curl -sS https://api.thetarget.cc/api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d \
  -H "Authorization: Bearer $TARGET_API_KEY"

No query parameters. A parameter with an unknown name is rejected.

The request has no body.

Response 200

FieldTypePresentDescription
idstringalwaysPayment ID: pr_ followed by 22 characters. Use it to read the payment.
referencestringalwaysThe order number sent at creation.
servicestringor nullalwaysCode of the service the payment was created with.
environmentstringTEST LIVEalwaysThe payment's environment: the environment of the key that created it.
statusstringCREATED PROCESSING AWAITING_CUSTOMER SUCCEEDED PARTIALLY_PAID OVERPAID FAILED CANCELLED EXPIRED REJECTEDalwaysPayment status: Payment statuses.
reasonstringor nullalwaysReason for the status as a code; null when there is nothing to name: Reasons.
inReviewbooleanalwaysThe outcome is still being settled on our side: by a provider inquiry or by a person. While it is true, the payment is not credited.
amountMinorstringalwaysThe requested amount as a string, in minor units of the payment currency.
currencystringalwaysPayment currency: the service currency.
networkstringor nullalwaysNetwork, if the currency has several. null: no network.
paidMinorstringor nullalwaysThe amount confirmed by the provider, in minor units of the payment currency. This is the amount you credit, and only with SUCCEEDED. null: no money confirmed.
feeMinorstringor nullalwaysThe merchant's fee for the payment, in minor units of the payment currency, calculated at creation.
refundedMinorstringalwaysHow much has been returned to the payer by successful refunds, in minor units of the payment currency. Refunds do not change the payment status: Refunds.
actionobjector nullalwaysWhat the payer should do; present only while the payment waits for them: What to show the payer. null: nothing to show, wait by the status.
action.typestringredirect requisitealwaysredirect: send the payer to url; requisite: show the payment details.
action.urlstringnot alwaysWhere to send the payer: the provider's page or, with fieldsOnPage, the payment page. Only with redirect.
action.requisiteobjectnot alwaysPayment details. Only with requisite: Payment details.
action.requisite.presentationstringqr transfer voucheralwaysHow to show them: qr a code to scan and copy, transfer a transfer by bank details, voucher a number to pay at a cash desk.
action.requisite.payloadstringalwaysThe main string of the payment details: the code content, the account or voucher number.
action.requisite.fieldsobject with arbitrary keysalwaysLabels for the screen in display order: an upper-case key is an account name (CLABE, IBAN, ALIAS), lower-case ones are code, account, holder, bank, reference. May be empty.
action.requisite.payAmountMinorstringalwaysHow much to transfer, in minor units of payCurrency.
action.requisite.payCurrencystringalwaysCurrency of the amount to pay. With conversion it differs from the payment currency.
action.requisite.payAmountChangedbooleanalwaystrue: the provider asked for an amount different from the payment amount; tell the payer "transfer exactly this amount".
action.expiresAtstringor nullnot alwaysUntil when the payment details are valid, in UTC. null: no deadline named. Only with requisite.
customerobjectalwaysThe customer who pays.
customer.idstringalwaysThe customer ID sent at creation.
returnUrlstringor nullalwaysThe payer's return address as the server parsed it. null: not set.
callbackUrlstringor nullalwaysThe payment's notification address as the server parsed it. null: not set, notifications go to the environment address.
metadataany valuealwaysYour labels, as sent at creation.
createdAtstring, ISO 8601 timestampalwaysWhen the payment was created, in UTC.
expiresAtstring, ISO 8601 timestampor nullalwaysPayment deadline, in UTC: Payment deadline.
finalizedAtstring, ISO 8601 timestampor nullalwaysWhen the payment got a final status, in UTC. null: not yet.
pageUrlstringor nullalwaysLink to the payment page of this payment: send the payer there instead of your own form. null: there is no page or the link has expired: Payment page.
Example response. The values are made up.
{
  "id": "pr_8k3m2q7w9x4t6v5n2b8c4d",
  "reference": "order-1001",
  "service": "pix_brl_redirect",
  "environment": "TEST",
  "status": "SUCCEEDED",
  "reason": null,
  "inReview": false,
  "amountMinor": "1250",
  "currency": "BRL",
  "network": null,
  "paidMinor": "1250",
  "feeMinor": "24",
  "refundedMinor": "500",
  "action": null,
  "customer": {
    "id": "player-42"
  },
  "returnUrl": "https://shop.example/return/order-1001",
  "callbackUrl": null,
  "metadata": {
    "cartId": "c-77"
  },
  "createdAt": "2026-11-13T09:15:02.481Z",
  "expiresAt": "2026-11-13T09:45:02.481Z",
  "finalizedAt": "2026-11-13T09:17:40.112Z",
  "pageUrl": null
}

Errors

In addition to the common errors:

HTTPCode and ruleWhen it happens and what to do
404not_found

There is no payment or refund with this ID in the key's environment: the ID is malformed, or it belongs to someone else or to another environment. For a refund read the message names both: the response has no rule saying which of the two is missing.

Check the ID and the key.

Example response
GET /api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d

HTTP/1.1 404

{
  "error": {
    "code": "not_found",
    "message": "Payment not found"
  }
}
400validation_failed

The ID in the path is badly encoded: % is not followed by two hex digits, or the bytes do not form UTF-8.

Pass the ID exactly as the creation response returned it.

Example response
GET /api/v1/payments/pr_%ZZ

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "The request path has an invalid encoding",
    "details": {
      "field": "path"
    }
  }
}

Create a refund

POST/api/v1/payments/:id/refundssince 2026-11-17

Returns money of a successful payment to the payer, in full or in part. The response holds the refund: its ID, status and review flag.

  • The Idempotency-Key header is required. A 409 error with a rule, except request_in_progress and refund_in_progress, takes the key: a retry with the same key gets the same error.
  • An API key, merchant or environment error with a correct secret (401 api_key_disabled, api_key_revoked, api_key_expired, 403 merchant_not_active, environment_closed) also takes the retry key: a retry with the same key gets the same error and Idempotency-Replayed: true, even after the API key is enabled or the merchant is opened. A revoked or expired API key takes the retry key only for a day after the key ended; after that its 401 does not take the key, but it still gets what was recorded for the same body on a retry.
  • The first response does not show whether a 401 was recorded on the retry key: retry the same request with the same retry key using a valid API key. A recorded error comes back with Idempotency-Replayed: true; otherwise the request is executed.
  • A 503 dependency_unavailable response is not a failure: the refund may have been created. Retry the same request with the same retry key.
  • A new refund gets 201. A retry gets the same refund as it is now and the Idempotency-Replayed: true header.
  • Order and limits: Refunds.

Request

curl -sS -X POST https://api.thetarget.cc/api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds \
  -H "Authorization: Bearer $TARGET_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b8e4f3a-6c21-4d7e-9a15-2f4c8b7d1e90" \
  -d '{
    "reference": "refund-1001-1",
    "amountMinor": "500",
    "description": "Partial refund, ticket T-5521",
    "metadata": {
      "ticket": "T-5521"
    }
  }'

No query parameters. A parameter with an unknown name is rejected.

FieldTypeRequiredDescription
referencestringyesYour refund number: 1 to 128 characters, with no leading or trailing spaces and no invisible characters. Unique per merchant within an environment: a second refund with the same number is not created.
amountMinorstringyesThe refund amount as a string: an integer of minor units of the payment currency, up to 15 digits, not more than what remains to refund.
descriptionstringnoA note for employees, up to 255 characters. The payer does not see it.
metadataobject with arbitrary keysnoYour labels: a JSON object, as for a payment. Returned in the response as is.
callbackUrlstringnoNotification address for this object (Corefy callback_url): its notifications go here instead of the environment address, signed with the environment secret. https up to 2048 characters, http also allowed in the test environment; a full internet host name; the default port, 443, 8443, 80 or 8080; without a user name or password. Requires the environment secret: Address in the request.

Response 201

FieldTypePresentDescription
idstringalwaysRefund ID: rf_ followed by 22 characters.
paymentstringalwaysID of the payment whose money is returned.
referencestringalwaysThe refund number sent at creation.
environmentstringTEST LIVEalwaysThe refund's environment: the payment's environment.
statusstringPENDING SUCCEEDED FAILEDalwaysPENDING the refund is in progress or its outcome is unknown, SUCCEEDED the money went out, FAILED there was no refund. Read an unknown status as PENDING.
reasonstringor nullrefund_declined technical_failure operator_declinedalwaysReason for a failure: refund_declined the provider declined, technical_failure a technical failure, operator_declined an employee declined. null for other statuses.
inReviewbooleanalwaysThe refund outcome is in question. With PENDING a provider inquiry or an employee decision names it, or a manual correction if the provider returned a different amount; with FAILED and SUCCEEDED this is a late disputed answer from the provider, and it is not lifted by itself. While it is true, do not return the same money.
amountMinorstringalwaysThe refund amount in minor units of the payment currency.
currencystringalwaysRefund currency: the payment currency.
feeMinorstringalwaysThe refund fee in minor units of the payment currency, on top of the refund amount.
providerRefundIdstringor nullalwaysThe provider's refund operation number, if it named one: quote it to the payer's bank.
descriptionstringor nullalwaysThe description sent at creation. null: not set.
metadataany valuealwaysYour labels, as sent at creation.
callbackUrlstringor nullalwaysThe refund's notification address as the server parsed it. null: not set, notifications go to the environment address.
createdAtstring, ISO 8601 timestampalwaysWhen the refund was created, in UTC.
finalizedAtstring, ISO 8601 timestampor nullalwaysWhen the refund got its outcome, in UTC. null: not yet.
Example response. The values are made up.
{
  "id": "rf_5n7q2w8x4k3m9t6v2b8c4d",
  "payment": "pr_8k3m2q7w9x4t6v5n2b8c4d",
  "reference": "refund-1001-1",
  "environment": "TEST",
  "status": "PENDING",
  "reason": null,
  "inReview": false,
  "amountMinor": "500",
  "currency": "BRL",
  "feeMinor": "0",
  "providerRefundId": null,
  "description": "Partial refund, ticket T-5521",
  "metadata": {
    "ticket": "T-5521"
  },
  "callbackUrl": null,
  "createdAt": "2026-11-14T10:02:11.904Z",
  "finalizedAt": null
}

Errors

In addition to the common errors:

HTTPCode and ruleWhen it happens and what to do
400validation_failed

The body failed the shape check: an extra field, a value of the wrong type (such as the amount as a JSON number rather than a string) or a missing required field. details.issues names the fields.

Fix the body against the field table.

Example response
POST /api/v1/payments

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "Request body failed validation",
    "details": {
      "issues": [
        {
          "field": "amountMinor",
          "message": "Expected string, received number"
        }
      ]
    }
  }
}
400validation_failed

A value failed validation: details.field names the field, details.rule the rule.

  • idempotency_key_required: There is no Idempotency-Key header: a refund requires it.
  • idempotency_key_shape: The Idempotency-Key header is empty, longer than 128 characters, or holds spaces or characters outside visible ASCII.
  • reference_shape: The refund reference is empty, longer than 128 characters, or has leading or trailing spaces, control or invisible characters.
  • description_shape: description is empty, longer than 255 characters, or holds control or invisible characters.
  • metadata_shape: metadata is not a JSON object, is longer than 4096 characters when serialized, is deeper than 16 levels or holds a number that JSON cannot represent exactly.
  • reserved_key: The body has a __proto__ key.
  • callback_url_invalid: callbackUrl is not a URL, is longer than 2048 characters, or has a user name or password, a fragment, a space or a control character, or a port other than 443, 8443, 80, 8080.
  • callback_url_scheme: callbackUrl is not https (http is allowed in the test environment).
  • callback_url_internal: callbackUrl leads to an internal or service network: an IP address of a private or service network, localhost, a name without a dot, or a service domain (.local, .internal, .lan, .localdomain, .home.arpa).

Fix the value named by details.field.

Example response
POST /api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "The Idempotency-Key header is required to create a refund: a retry without it would refund the money twice",
    "details": {
      "field": "Idempotency-Key",
      "rule": "idempotency_key_required"
    }
  }
}
400bad_amount

amountMinor is not a string holding a positive integer of up to 15 digits.

Send the amount as a string in minor units of the payment currency.

Example response
POST /api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds

HTTP/1.1 400

{
  "error": {
    "code": "bad_amount",
    "message": "Amount is a string with a positive integer number of minor currency units, up to 15 digits",
    "details": {
      "field": "amountMinor"
    }
  }
}
404not_found

There is no payment or refund with this ID in the key's environment: the ID is malformed, or it belongs to someone else or to another environment. For a refund read the message names both: the response has no rule saying which of the two is missing.

Check the ID and the key.

Example response
GET /api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d

HTTP/1.1 404

{
  "error": {
    "code": "not_found",
    "message": "Payment not found"
  }
}
409conflictrefund_reference_exists

A refund with this reference already exists in the environment; details.refundId and details.paymentId name it.

Read that refund instead of creating a new one.

Example response
POST /api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "A refund with this reference already exists",
    "details": {
      "rule": "refund_reference_exists",
      "refundId": "rf_5n7q2w8x4k3m9t6v2b8c4d",
      "paymentId": "pr_8k3m2q7w9x4t6v5n2b8c4d"
    }
  }
}
409conflictrefund_in_progress

A refund of the payment is already in progress at the provider.

Read the payment's refunds: if the running one is this one, no second is needed. Otherwise retry the same request with the same key after its outcome.

Example response
POST /api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "A refund of this payment is already in progress at the provider: wait for its outcome",
    "details": {
      "rule": "refund_in_progress"
    }
  }
}
409conflict

This refund is not possible.

  • payment_not_refundable: The payment is not successful, is under review or was not created through the API.
  • refund_exceeds_remaining: The amount is greater than what remains to refund; details.remainingMinor names the remainder.
  • refund_amount_too_small: The amount is so small that it comes to zero in the provider's currency.
  • refund_limit_reached: The payment already has 50 refunds, not counting failed ones, or 200 in total.
  • insufficient_balance: The merchant's account lacks available money for the refund.

A retry with the same key gets the same error: send the corrected request with a new retry key.

Example response
POST /api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "The payment cannot be refunded: only a successful payment that is not under review can be refunded",
    "details": {
      "rule": "payment_not_refundable"
    }
  }
}
409conflictcallback_secret_missing

callbackUrl is set, but the API key's environment has no notification signing secret: there is nothing to sign the notifications with. For a payment the retry key is released; for a refund and a payout the refusal is recorded on the key, like their other refusals after the key.

Issue a secret with POST /api/v1/notifications/secret, or ask an administrator for an environment address. Then repeat the request; for a refund and a payout, with a new retry key: the old key keeps this refusal.

Example response
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "callbackUrl needs the notification signing secret of the environment: POST /api/v1/notifications/secret",
    "details": {
      "rule": "callback_secret_missing"
    }
  }
}
409conflictrequest_in_progress

A request with this retry key is still running.

Retry in a few seconds with the same key and the same body.

Example response
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "A request with this idempotency key is still running: retry later",
    "details": {
      "rule": "request_in_progress"
    }
  }
}
409conflictidempotency_key_reused

The retry key has already been used by another request: with a different body or for another operation.

A retry sends the same request; a new operation gets a new key.

Example response
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "This idempotency key has already been used with another request",
    "details": {
      "rule": "idempotency_key_reused"
    }
  }
}
503dependency_unavailable

There is no answer on the merits: this is not a failure, the refund may have been created or may still be in progress.

  • transaction_timeout: The refund did not finish in time on our side and was not created.
  • transaction_conflict: Writing the refund collided with a parallel write on our side; the refund was not created.
  • idempotency_unrecorded: The outcome of the request could not be recorded on the retry key, or the first request with this key is still going to the provider.
  • keyring_unavailable: The keys that record the retry key are unavailable on our side; the key was not taken.
  • idempotency_key_unverifiable: The retry key was recorded in a way our side cannot check the body against right now; the refund may have been created.

Retry the same request with the same retry key; do not treat the refund as refused on this response. The payment's refunds show whether it was created. If the response repeats, give support the retry key and the time of the request.

Example response
POST /api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds

HTTP/1.1 503

{
  "error": {
    "code": "dependency_unavailable",
    "message": "The refund did not finish within the transaction time: no answer, retry the request with the same idempotency key",
    "details": {
      "rule": "transaction_timeout"
    }
  }
}

Refunds of a payment

GET/api/v1/payments/:id/refundssince 2026-11-17

Returns all refunds of the payment, newest first. Changes nothing.

  • Reading refunds has its own rate limit, separate from creation.

Request

curl -sS https://api.thetarget.cc/api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds \
  -H "Authorization: Bearer $TARGET_API_KEY"

No query parameters. A parameter with an unknown name is rejected.

The request has no body.

Response 200

FieldTypePresentDescription
itemsarray of objectsalwaysAll refunds of the payment, newest first. Empty: there are no refunds.
items[].idstringalwaysRefund ID: rf_ followed by 22 characters.
items[].paymentstringalwaysID of the payment whose money is returned.
items[].referencestringalwaysThe refund number sent at creation.
items[].environmentstringTEST LIVEalwaysThe refund's environment: the payment's environment.
items[].statusstringPENDING SUCCEEDED FAILEDalwaysPENDING the refund is in progress or its outcome is unknown, SUCCEEDED the money went out, FAILED there was no refund. Read an unknown status as PENDING.
items[].reasonstringor nullrefund_declined technical_failure operator_declinedalwaysReason for a failure: refund_declined the provider declined, technical_failure a technical failure, operator_declined an employee declined. null for other statuses.
items[].inReviewbooleanalwaysThe refund outcome is in question. With PENDING a provider inquiry or an employee decision names it, or a manual correction if the provider returned a different amount; with FAILED and SUCCEEDED this is a late disputed answer from the provider, and it is not lifted by itself. While it is true, do not return the same money.
items[].amountMinorstringalwaysThe refund amount in minor units of the payment currency.
items[].currencystringalwaysRefund currency: the payment currency.
items[].feeMinorstringalwaysThe refund fee in minor units of the payment currency, on top of the refund amount.
items[].providerRefundIdstringor nullalwaysThe provider's refund operation number, if it named one: quote it to the payer's bank.
items[].descriptionstringor nullalwaysThe description sent at creation. null: not set.
items[].metadataany valuealwaysYour labels, as sent at creation.
items[].callbackUrlstringor nullalwaysThe refund's notification address as the server parsed it. null: not set, notifications go to the environment address.
items[].createdAtstring, ISO 8601 timestampalwaysWhen the refund was created, in UTC.
items[].finalizedAtstring, ISO 8601 timestampor nullalwaysWhen the refund got its outcome, in UTC. null: not yet.
Example response. The values are made up.
{
  "items": [
    {
      "id": "rf_5n7q2w8x4k3m9t6v2b8c4d",
      "payment": "pr_8k3m2q7w9x4t6v5n2b8c4d",
      "reference": "refund-1001-1",
      "environment": "TEST",
      "status": "SUCCEEDED",
      "reason": null,
      "inReview": false,
      "amountMinor": "500",
      "currency": "BRL",
      "feeMinor": "0",
      "providerRefundId": "RF-88213",
      "description": "Partial refund, ticket T-5521",
      "metadata": {
        "ticket": "T-5521"
      },
      "callbackUrl": null,
      "createdAt": "2026-11-14T10:02:11.904Z",
      "finalizedAt": "2026-11-14T10:03:12.550Z"
    }
  ]
}

Errors

In addition to the common errors:

HTTPCode and ruleWhen it happens and what to do
404not_found

There is no payment or refund with this ID in the key's environment: the ID is malformed, or it belongs to someone else or to another environment. For a refund read the message names both: the response has no rule saying which of the two is missing.

Check the ID and the key.

Example response
GET /api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d

HTTP/1.1 404

{
  "error": {
    "code": "not_found",
    "message": "Payment not found"
  }
}
400validation_failed

The ID in the path is badly encoded: % is not followed by two hex digits, or the bytes do not form UTF-8.

Pass the ID exactly as the creation response returned it.

Example response
GET /api/v1/payments/pr_%ZZ

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "The request path has an invalid encoding",
    "details": {
      "field": "path"
    }
  }
}

Read a refund

GET/api/v1/payments/:id/refunds/:refundIdsince 2026-11-17

Returns one refund of the payment by its ID. Changes nothing. This is how you learn the outcome of a refund if the notification did not arrive.

  • A refund ID of another payment gets the same 404 response as a non-existent one.

Request

curl -sS https://api.thetarget.cc/api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds/rf_5n7q2w8x4k3m9t6v2b8c4d \
  -H "Authorization: Bearer $TARGET_API_KEY"

No query parameters. A parameter with an unknown name is rejected.

The request has no body.

Response 200

FieldTypePresentDescription
idstringalwaysRefund ID: rf_ followed by 22 characters.
paymentstringalwaysID of the payment whose money is returned.
referencestringalwaysThe refund number sent at creation.
environmentstringTEST LIVEalwaysThe refund's environment: the payment's environment.
statusstringPENDING SUCCEEDED FAILEDalwaysPENDING the refund is in progress or its outcome is unknown, SUCCEEDED the money went out, FAILED there was no refund. Read an unknown status as PENDING.
reasonstringor nullrefund_declined technical_failure operator_declinedalwaysReason for a failure: refund_declined the provider declined, technical_failure a technical failure, operator_declined an employee declined. null for other statuses.
inReviewbooleanalwaysThe refund outcome is in question. With PENDING a provider inquiry or an employee decision names it, or a manual correction if the provider returned a different amount; with FAILED and SUCCEEDED this is a late disputed answer from the provider, and it is not lifted by itself. While it is true, do not return the same money.
amountMinorstringalwaysThe refund amount in minor units of the payment currency.
currencystringalwaysRefund currency: the payment currency.
feeMinorstringalwaysThe refund fee in minor units of the payment currency, on top of the refund amount.
providerRefundIdstringor nullalwaysThe provider's refund operation number, if it named one: quote it to the payer's bank.
descriptionstringor nullalwaysThe description sent at creation. null: not set.
metadataany valuealwaysYour labels, as sent at creation.
callbackUrlstringor nullalwaysThe refund's notification address as the server parsed it. null: not set, notifications go to the environment address.
createdAtstring, ISO 8601 timestampalwaysWhen the refund was created, in UTC.
finalizedAtstring, ISO 8601 timestampor nullalwaysWhen the refund got its outcome, in UTC. null: not yet.
Example response. The values are made up.
{
  "id": "rf_5n7q2w8x4k3m9t6v2b8c4d",
  "payment": "pr_8k3m2q7w9x4t6v5n2b8c4d",
  "reference": "refund-1001-1",
  "environment": "TEST",
  "status": "SUCCEEDED",
  "reason": null,
  "inReview": false,
  "amountMinor": "500",
  "currency": "BRL",
  "feeMinor": "0",
  "providerRefundId": "RF-88213",
  "description": "Partial refund, ticket T-5521",
  "metadata": {
    "ticket": "T-5521"
  },
  "callbackUrl": null,
  "createdAt": "2026-11-14T10:02:11.904Z",
  "finalizedAt": "2026-11-14T10:03:12.550Z"
}

Errors

In addition to the common errors:

HTTPCode and ruleWhen it happens and what to do
404not_found

There is no payment or refund with this ID in the key's environment: the ID is malformed, or it belongs to someone else or to another environment. For a refund read the message names both: the response has no rule saying which of the two is missing.

Check the ID and the key.

Example response
GET /api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d

HTTP/1.1 404

{
  "error": {
    "code": "not_found",
    "message": "Payment not found"
  }
}
400validation_failed

The ID in the path is badly encoded: % is not followed by two hex digits, or the bytes do not form UTF-8.

Pass the ID exactly as the creation response returned it.

Example response
GET /api/v1/payments/pr_%ZZ

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "The request path has an invalid encoding",
    "details": {
      "field": "path"
    }
  }
}

Create a payout

POST/api/v1/payoutssince 2026-11-17

Creates a payout to a player: reserves the amount plus fee from the merchant's available balance and decides moderation. The response is the payout: its ID, status and moderation decision. The requisite and beneficiary data are not in the response.

  • The Idempotency-Key header is required. An error is recorded on the retry key: a retry of the same body gets the same error even after the cause is fixed, and a different body gets 409 idempotency_key_reused; after fixing it, send the request with a new key. Not recorded: request_in_progress; errors that come before the retry key (401 without a rule when there is no API key or the secret is wrong, signing in other than with an API key, the rate limit, an extra query parameter, the size and form of the header and the body; if this same body is already recorded under the key, the recorded answer comes instead of the form error); an error for an API key that ended more than a day ago (counting from the earlier of revocation and expiry): such a key only reads what is recorded and gets 401 for a different body; a live key on a server without the live environment keyring. A 5xx response or a dropped connection is not a refusal: the payout may have been created, retry the same request with the same key.
  • A new payout gets 201. A retry gets the same payout as it is now and the Idempotency-Replayed: true header.
  • Live payouts are closed for now, and payouts are not sent yet: an approved payout stays CREATED and can be cancelled.

Request

curl -sS -X POST https://api.thetarget.cc/api/v1/payouts \
  -H "Authorization: Bearer $TARGET_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c1d9e42-3a5b-4f80-b6d2-91e4a0c58f17" \
  -d '{
    "reference": "withdrawal-2001",
    "service": "payout_pix_brl_direct",
    "amountMinor": "15000",
    "customer": {
      "id": "player-1001",
      "country": "BR"
    },
    "fields": {
      "beneficiary.pix_key": "player1001@example.com",
      "beneficiary.tax_id": "52998224725"
    },
    "metadata": {
      "withdrawalId": "W-2001"
    }
  }'

No query parameters. A parameter with an unknown name is rejected.

FieldTypeRequiredDescription
referencestringyesYour withdrawal number: 1 to 128 characters, no leading or trailing spaces and no invisible characters. A second payout with the same number is not created in the environment.
servicestringyesPayout service code from the service list (direction = PAYOUT). The service sets the currency, method and beneficiary fields.
amountMinorstringyesWhat the player receives, as a string: a whole number of minor units of the service currency, up to 15 digits. The fee is charged on top of this amount.
customerobjectyesThe customer the payout is for.
customer.idstringyesYour customer ID: 1 to 128 characters, no leading or trailing spaces and no invisible characters.
customer.countrystringnoCustomer country: an ISO 3166-1 code of two capital letters (GB, not UK).
fieldsobject with arbitrary keysyesRequisite and beneficiary data by the keys in the service list: beneficiary.pix_key, beneficiary.clabe, beneficiary.iban, beneficiary.name, beneficiary.tax_id. Exactly one requisite to pay to. The account country is the first two letters of the IBAN. They are not in the response.
metadataobject with arbitrary keysnoYour labels: a JSON object up to 4096 characters per entry and up to 16 levels deep. Returned in the response as is.
callbackUrlstringnoNotification address for this object (Corefy callback_url): its notifications go here instead of the environment address, signed with the environment secret. https up to 2048 characters, http also allowed in the test environment; a full internet host name; the default port, 443, 8443, 80 or 8080; without a user name or password. Requires the environment secret: Address in the request.

Response 201

FieldTypePresentDescription
idstringalwaysPayout ID: po_ followed by 22 characters. Use it to read and cancel the payout.
referencestringalwaysThe withdrawal number sent at creation.
servicestringalwaysThe service code the payout was created with.
environmentstringTEST LIVEalwaysThe payout's environment: the environment of the key it was created with.
statusstringCREATED PROCESSING SUCCEEDED FAILED REJECTED CANCELLEDalwaysCREATED created and waiting for a decision or sending, PROCESSING sent, SUCCEEDED the money went out, FAILED it did not, REJECTED rejected, CANCELLED cancelled before sending. Read an unknown status as PROCESSING.
reasonstringor nullcustomer_blocked rejected_by_operator cancelled_by_merchantalwaysWhy it closed: customer_blocked the customer or requisite is blocked, rejected_by_operator an employee rejected it, cancelled_by_merchant you cancelled it. null otherwise.
approvalstringPENDING APPROVED REJECTED WITHDRAWNalwaysModeration decision: APPROVED approved, PENDING waiting for an employee, REJECTED rejected, WITHDRAWN withdrawn by your cancellation.
inReviewbooleanalwaysThe payout outcome is being decided on our side. While it is true, do not return the balance to the player and do not count the payout as done.
amountMinorstringalwaysWhat the player receives, in minor units of the payout currency.
currencystringalwaysPayout currency: the service currency.
feeMinorstringalwaysThe payout fee in minor units of the payout currency, on top of the amount.
metadataany valuealwaysYour labels, as sent at creation.
callbackUrlstringor nullalwaysThe payout's notification address as the server parsed it. null: not set, notifications go to the environment address if there is one.
createdAtstring, ISO 8601 timestampalwaysWhen the payout was created, in UTC.
finalizedAtstring, ISO 8601 timestampor nullalwaysWhen the payout closed, in UTC. null: not yet.
Example response. The values are made up.
{
  "id": "po_3m8q2w7k9x4t6v5n2b8c4d",
  "reference": "withdrawal-2001",
  "service": "payout_pix_brl_direct",
  "environment": "TEST",
  "status": "CREATED",
  "reason": null,
  "approval": "APPROVED",
  "inReview": false,
  "amountMinor": "15000",
  "currency": "BRL",
  "feeMinor": "250",
  "metadata": {
    "withdrawalId": "W-2001"
  },
  "callbackUrl": null,
  "createdAt": "2026-11-17T09:41:07.312Z",
  "finalizedAt": null
}

Errors

In addition to the common errors:

HTTPCode and ruleWhen it happens and what to do
400validation_failed

The body failed the shape check: an extra field, a value of the wrong type (such as the amount as a JSON number rather than a string) or a missing required field. details.issues names the fields.

Fix the body against the field table.

Example response
POST /api/v1/payments

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "Request body failed validation",
    "details": {
      "issues": [
        {
          "field": "amountMinor",
          "message": "Expected string, received number"
        }
      ]
    }
  }
}
400validation_failed

A header or value failed validation: details.field names the field, details.rule the rule. An error in the form of the header or the body comes before the retry key and does not take it; if this same body is already recorded under the key, the recorded answer comes. An error from checking fields against the service fields (rules from destination_required to field_pattern) comes after the key is taken and is recorded on it.

  • idempotency_key_required: There is no Idempotency-Key header: a payout requires it.
  • idempotency_key_shape: The Idempotency-Key header is empty, longer than 128 characters or has spaces or characters outside visible ASCII.
  • reference_shape: reference is empty, longer than 128 characters, or has leading or trailing spaces, control or invisible characters.
  • external_ref_shape: The same for customer.id.
  • country_code: customer.country is not an assigned ISO 3166-1 code of two capital letters.
  • metadata_shape: metadata is not a JSON object, is longer than 4096 characters per entry, deeper than 16 levels, or has a number JSON cannot hold exactly.
  • reserved_key: The body has a __proto__ key.
  • callback_url_invalid: callbackUrl is not a URL, is longer than 2048 characters, or has a user name or password, a fragment, a space or a control character, or a port other than 443, 8443, 80, 8080.
  • callback_url_scheme: callbackUrl is not https (http is allowed in the test environment).
  • callback_url_internal: callbackUrl leads to an internal or service network: an IP address of a private or service network, localhost, a name without a dot, or a service domain (.local, .internal, .lan, .localdomain, .home.arpa).
  • destination_required: fields does not have exactly one requisite to pay to.
  • unknown_field: fields has a key the service does not have.
  • field_not_accepted: The service has the field, but the payout does not accept it.
  • required: A field the service requires is missing.
  • field_shape: The field value is empty, has leading or trailing spaces, control or invisible characters; the beneficiary name has no letter.
  • field_too_long: The value is longer than the service field's maxLength.
  • field_kind: The value is not of the kind the service field's kind requires.
  • field_pattern: The value does not match the service field's pattern.

Fix the value named in details.field. After an error from checking fields, send the fixed request with a new retry key: with the old key the same body gets the recorded error and a fixed body gets 409 idempotency_key_reused.

Example response
POST /api/v1/payouts

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "The Idempotency-Key header is required to create a payout: a retry without it would pay out the money twice",
    "details": {
      "field": "Idempotency-Key",
      "rule": "idempotency_key_required"
    }
  }
}
400bad_amount

amountMinor is not a string with a positive whole number of up to 15 digits: for example «12.50» or «0».

Send the amount as a string in minor units: «1250», not «12.50».

Example response
POST /api/v1/payouts

HTTP/1.1 400

{
  "error": {
    "code": "bad_amount",
    "message": "Amount is a string with a positive integer number of minor currency units, up to 15 digits",
    "details": {
      "field": "amountMinor"
    }
  }
}
400bad_amountamount_out_of_range

The amount is well formed but outside the service limits; details.minMinor and details.maxMinor name them. The error takes the retry key.

Send an amount within the service limits with a new retry key.

Example response
POST /api/v1/payouts

HTTP/1.1 400

{
  "error": {
    "code": "bad_amount",
    "message": "Amount is outside the service limits",
    "details": {
      "field": "amountMinor",
      "rule": "amount_out_of_range",
      "minMinor": "100",
      "maxMinor": "5000000"
    }
  }
}
403forbidden

A live payout cannot be created now. Checked after the header and body format.

  • live_payouts_closed: The payout is created with a live key, and live payouts are closed.
  • live_payouts_disabled: Live payouts are not enabled for this merchant.

Create payouts with a test key.

Example response
POST /api/v1/payouts

HTTP/1.1 403

{
  "error": {
    "code": "forbidden",
    "message": "Live payouts are closed: the test environment is open",
    "details": {
      "rule": "live_payouts_closed"
    }
  }
}
409conflict

A payout cannot be created with the service from the request now. The error takes the retry key.

  • service_unavailable: The service is not in the key's service list, is no longer available, or its only route converts currency.
  • service_not_payout: The service is not for payouts.
  • service_field_unsupported: The service requires a field this API version does not accept for payouts yet; details.field names it.

Take a payout service from a fresh service list and send the request with a new retry key.

Example response
POST /api/v1/payouts

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "Service unavailable: GET /api/v1/services lists the available services",
    "details": {
      "rule": "service_unavailable"
    }
  }
}
409conflictpayout_reference_exists

A payout with this reference already exists in the environment; details.payoutId names it.

Read that payout instead of creating a new one.

Example response
POST /api/v1/payouts

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "A payout with this reference already exists",
    "details": {
      "rule": "payout_reference_exists",
      "payoutId": "po_3m8q2w7k9x4t6v5n2b8c4d"
    }
  }
}
409conflictinsufficient_balance

The merchant's account lacks available money for the amount plus fee. The error takes the retry key: a retry with the same key gets it again.

Top up the available balance; send a new withdrawal with a new retry key.

Example response
POST /api/v1/payouts

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "The merchant's available balance is not enough for the payout with its fee",
    "details": {
      "rule": "insufficient_balance"
    }
  }
}
422identifier_invalid

The requisite or beneficiary data failed validation, for example a tax ID or IBAN checksum. details.field names the field, details.kind the data kind, details.rule the check; the value is not in the response. The error is recorded on the retry key.

Fix the field value and send the request with a new retry key.

Example response
POST /api/v1/payouts

HTTP/1.1 422

{
  "error": {
    "code": "identifier_invalid",
    "message": "Identifier failed validation",
    "details": {
      "field": "fields.beneficiary.pix_key",
      "kind": "PIX_KEY",
      "rule": "pix_key_unrecognized"
    }
  }
}
409conflictcallback_secret_missing

callbackUrl is set, but the API key's environment has no notification signing secret: there is nothing to sign the notifications with. For a payment the retry key is released; for a refund and a payout the refusal is recorded on the key, like their other refusals after the key.

Issue a secret with POST /api/v1/notifications/secret, or ask an administrator for an environment address. Then repeat the request; for a refund and a payout, with a new retry key: the old key keeps this refusal.

Example response
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "callbackUrl needs the notification signing secret of the environment: POST /api/v1/notifications/secret",
    "details": {
      "rule": "callback_secret_missing"
    }
  }
}
409conflictrequest_in_progress

A request with this retry key is still running.

Retry in a few seconds with the same key and the same body.

Example response
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "A request with this idempotency key is still running: retry later",
    "details": {
      "rule": "request_in_progress"
    }
  }
}
409conflictidempotency_key_reused

The retry key has already been used by another request: with a different body or for another operation.

A retry sends the same request; a new operation gets a new key.

Example response
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "This idempotency key has already been used with another request",
    "details": {
      "rule": "idempotency_key_reused"
    }
  }
}
503dependency_unavailable

There is no answer on the merits: the payout was not created, or it was created and the answer did not arrive. This is not a refusal.

  • idempotency_unrecorded: The answer could not be recorded on the retry key.
  • transaction_timeout: The payout did not finish in time on our side.
  • transaction_conflict: A parallel request changed the same data at the same moment.
  • keyring_unavailable: Encryption keys of the environment are unavailable on our side.
  • idempotency_key_unverifiable: The retry key was recorded in a way we cannot check the body against.
  • idempotency_key_unreadable: The retry key could not be read on our side while checking a body form error.

Do not return the balance to the player. Retry the same request with the same retry key: the retry returns the payout if it was created.

Example response
POST /api/v1/payouts

HTTP/1.1 503

{
  "error": {
    "code": "dependency_unavailable",
    "message": "No answer: retry the request with the same idempotency key",
    "details": {
      "rule": "idempotency_unrecorded"
    }
  }
}

Read a payout

GET/api/v1/payouts/:idsince 2026-11-17

Returns the payout by its ID. Changes nothing.

  • Another merchant's payout ID gets the same 404 response as a non-existent one.

Request

curl -sS https://api.thetarget.cc/api/v1/payouts/po_3m8q2w7k9x4t6v5n2b8c4d \
  -H "Authorization: Bearer $TARGET_API_KEY"

No query parameters. A parameter with an unknown name is rejected.

The request has no body.

Response 200

FieldTypePresentDescription
idstringalwaysPayout ID: po_ followed by 22 characters. Use it to read and cancel the payout.
referencestringalwaysThe withdrawal number sent at creation.
servicestringalwaysThe service code the payout was created with.
environmentstringTEST LIVEalwaysThe payout's environment: the environment of the key it was created with.
statusstringCREATED PROCESSING SUCCEEDED FAILED REJECTED CANCELLEDalwaysCREATED created and waiting for a decision or sending, PROCESSING sent, SUCCEEDED the money went out, FAILED it did not, REJECTED rejected, CANCELLED cancelled before sending. Read an unknown status as PROCESSING.
reasonstringor nullcustomer_blocked rejected_by_operator cancelled_by_merchantalwaysWhy it closed: customer_blocked the customer or requisite is blocked, rejected_by_operator an employee rejected it, cancelled_by_merchant you cancelled it. null otherwise.
approvalstringPENDING APPROVED REJECTED WITHDRAWNalwaysModeration decision: APPROVED approved, PENDING waiting for an employee, REJECTED rejected, WITHDRAWN withdrawn by your cancellation.
inReviewbooleanalwaysThe payout outcome is being decided on our side. While it is true, do not return the balance to the player and do not count the payout as done.
amountMinorstringalwaysWhat the player receives, in minor units of the payout currency.
currencystringalwaysPayout currency: the service currency.
feeMinorstringalwaysThe payout fee in minor units of the payout currency, on top of the amount.
metadataany valuealwaysYour labels, as sent at creation.
callbackUrlstringor nullalwaysThe payout's notification address as the server parsed it. null: not set, notifications go to the environment address if there is one.
createdAtstring, ISO 8601 timestampalwaysWhen the payout was created, in UTC.
finalizedAtstring, ISO 8601 timestampor nullalwaysWhen the payout closed, in UTC. null: not yet.
Example response. The values are made up.
{
  "id": "po_3m8q2w7k9x4t6v5n2b8c4d",
  "reference": "withdrawal-2001",
  "service": "payout_pix_brl_direct",
  "environment": "TEST",
  "status": "CREATED",
  "reason": null,
  "approval": "APPROVED",
  "inReview": false,
  "amountMinor": "15000",
  "currency": "BRL",
  "feeMinor": "250",
  "metadata": {
    "withdrawalId": "W-2001"
  },
  "callbackUrl": null,
  "createdAt": "2026-11-17T09:41:07.312Z",
  "finalizedAt": null
}

Errors

In addition to the common errors:

HTTPCode and ruleWhen it happens and what to do
404not_found

There is no payout with this ID in the key's environment: the ID is malformed, belongs to someone else or to another environment.

Check the ID and the key.

Example response
GET /api/v1/payouts/po_3m8q2w7k9x4t6v5n2b8c4d

HTTP/1.1 404

{
  "error": {
    "code": "not_found",
    "message": "Payout not found"
  }
}
400validation_failed

The ID in the path is badly encoded: % is not followed by two hex digits, or the bytes do not form UTF-8.

Pass the ID exactly as the creation response returned it.

Example response
GET /api/v1/payments/pr_%ZZ

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "The request path has an invalid encoding",
    "details": {
      "field": "path"
    }
  }
}

Cancel a payout

POST/api/v1/payouts/:id/cancelsince 2026-11-17

Cancels the payout while it has not been sent and returns the reserve to the available balance. The response is the payout with status CANCELLED.

  • Cancelling an already cancelled payout returns it again.

Request

curl -sS -X POST https://api.thetarget.cc/api/v1/payouts/po_3m8q2w7k9x4t6v5n2b8c4d/cancel \
  -H "Authorization: Bearer $TARGET_API_KEY"

No query parameters. A parameter with an unknown name is rejected.

The request has no body.

Response 200

FieldTypePresentDescription
idstringalwaysPayout ID: po_ followed by 22 characters. Use it to read and cancel the payout.
referencestringalwaysThe withdrawal number sent at creation.
servicestringalwaysThe service code the payout was created with.
environmentstringTEST LIVEalwaysThe payout's environment: the environment of the key it was created with.
statusstringCREATED PROCESSING SUCCEEDED FAILED REJECTED CANCELLEDalwaysCREATED created and waiting for a decision or sending, PROCESSING sent, SUCCEEDED the money went out, FAILED it did not, REJECTED rejected, CANCELLED cancelled before sending. Read an unknown status as PROCESSING.
reasonstringor nullcustomer_blocked rejected_by_operator cancelled_by_merchantalwaysWhy it closed: customer_blocked the customer or requisite is blocked, rejected_by_operator an employee rejected it, cancelled_by_merchant you cancelled it. null otherwise.
approvalstringPENDING APPROVED REJECTED WITHDRAWNalwaysModeration decision: APPROVED approved, PENDING waiting for an employee, REJECTED rejected, WITHDRAWN withdrawn by your cancellation.
inReviewbooleanalwaysThe payout outcome is being decided on our side. While it is true, do not return the balance to the player and do not count the payout as done.
amountMinorstringalwaysWhat the player receives, in minor units of the payout currency.
currencystringalwaysPayout currency: the service currency.
feeMinorstringalwaysThe payout fee in minor units of the payout currency, on top of the amount.
metadataany valuealwaysYour labels, as sent at creation.
callbackUrlstringor nullalwaysThe payout's notification address as the server parsed it. null: not set, notifications go to the environment address if there is one.
createdAtstring, ISO 8601 timestampalwaysWhen the payout was created, in UTC.
finalizedAtstring, ISO 8601 timestampor nullalwaysWhen the payout closed, in UTC. null: not yet.
Example response. The values are made up.
{
  "id": "po_3m8q2w7k9x4t6v5n2b8c4d",
  "reference": "withdrawal-2001",
  "service": "payout_pix_brl_direct",
  "environment": "TEST",
  "status": "CANCELLED",
  "reason": "cancelled_by_merchant",
  "approval": "APPROVED",
  "inReview": false,
  "amountMinor": "15000",
  "currency": "BRL",
  "feeMinor": "250",
  "metadata": {
    "withdrawalId": "W-2001"
  },
  "callbackUrl": null,
  "createdAt": "2026-11-17T09:41:07.312Z",
  "finalizedAt": "2026-11-17T09:43:52.018Z"
}

Errors

In addition to the common errors:

HTTPCode and ruleWhen it happens and what to do
404not_found

There is no payout with this ID in the key's environment: the ID is malformed, belongs to someone else or to another environment.

Check the ID and the key.

Example response
GET /api/v1/payouts/po_3m8q2w7k9x4t6v5n2b8c4d

HTTP/1.1 404

{
  "error": {
    "code": "not_found",
    "message": "Payout not found"
  }
}
409conflictpayout_not_cancellable

The payout can no longer be cancelled: it was sent or closed; details.status names its status.

Read the payout and wait for its outcome.

Example response
POST /api/v1/payouts/po_3m8q2w7k9x4t6v5n2b8c4d/cancel

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "The payout cannot be cancelled: it has already been sent or closed",
    "details": {
      "rule": "payout_not_cancellable",
      "status": "PROCESSING"
    }
  }
}
400validation_failed

The ID in the path is badly encoded: % is not followed by two hex digits, or the bytes do not form UTF-8.

Pass the ID exactly as the creation response returned it.

Example response
GET /api/v1/payments/pr_%ZZ

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "The request path has an invalid encoding",
    "details": {
      "field": "path"
    }
  }
}

Issue the notification signing secret

POST/api/v1/notifications/secretsince 2026-11-17

Issues the notification signing secret for the API key's environment if there is none yet. You need it to send callbackUrl in requests and to verify notification signatures. The secret is shown once.

  • No body. The API key sets the environment.
  • A secret already exists: 409 notify_secret_exists. An API key cannot change it: it is changed in the merchant cabinet or by an administrator.
  • The response is not cached. Keep the secret like a password, next to the API key.
  • Own rate limit: 10 requests a minute from one address.

Request

curl -sS -X POST https://api.thetarget.cc/api/v1/notifications/secret \
  -H "Authorization: Bearer $TARGET_API_KEY"

No query parameters. A parameter with an unknown name is rejected.

The request has no body.

Response 201

FieldTypePresentDescription
secretstringalwayswhsec_…: the notification signing secret; verify signatures with it per Standard Webhooks. Shown once.
environmentstringTEST LIVEalwaysThe secret's environment: the API key's environment.
createdAtstringalwaysWhen the secret was issued, UTC.
Example response. The values are made up.
{
  "secret": "whsec_<base64 of 32 bytes>",
  "environment": "TEST",
  "createdAt": "2026-11-17T10:00:00.000Z"
}

Errors

In addition to the common errors:

HTTPCode and ruleWhen it happens and what to do
400validation_failed

The body failed the shape check: an extra field, a value of the wrong type (such as the amount as a JSON number rather than a string) or a missing required field. details.issues names the fields.

Fix the body against the field table.

Example response
POST /api/v1/payments

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "Request body failed validation",
    "details": {
      "issues": [
        {
          "field": "amountMinor",
          "message": "Expected string, received number"
        }
      ]
    }
  }
}
409conflictnotify_secret_exists

The API key's environment already has a signing secret: it was issued by this endpoint, in the merchant cabinet or by an administrator together with the environment address. The secret is not shown again.

Take the secret where it was issued. A lost secret is changed in the merchant cabinet (the Notifications page, with a code from the authenticator app) or by an administrator; an API key cannot change it.

Example response
POST /api/v1/notifications/secret

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "The notification signing secret of this environment has already been issued and is shown only once: a new one is issued in the merchant cabinet or by the administrator",
    "details": {
      "rule": "notify_secret_exists"
    }
  }
}
409conflictkeyring_not_loaded

The keys from which this environment's signing secret is derived are not loaded on our side. No secret was issued.

Retry later. If it keeps happening, tell support the time of the request.

Example response
POST /api/v1/notifications/secret

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "The encryption keys of this environment are not loaded on the server: the signing secret cannot be derived, retry later",
    "details": {
      "rule": "keyring_not_loaded"
    }
  }
}

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.