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
| Field | Type | Present | Description |
|---|---|---|---|
merchant | object | always | The merchant the key was issued to. |
merchant.code | string | always | Merchant code. Set when the merchant is created and never changes. |
merchant.name | string | always | Merchant name as registered with us. |
environment | stringLIVE TEST | always | The key's environment. Every request made with this key runs in this environment. |
key | object | always | The key that signed the request. |
key.keyId | string | always | The public part of the key. Not a secret: use it to refer to the key when talking to support. |
key.expiresAt | string, ISO 8601 timestampor null | always | When the key stops being accepted, in UTC. null: no expiry is set. |
{
"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
| Field | Type | Present | Description |
|---|---|---|---|
environment | stringLIVE TEST | always | The key's environment. The list is built for it. |
items | array of objects | always | The merchant's services ready to work right now; only PAYIN ones can accept a payment. May be empty. |
items[].code | string | always | Service code. Use it to name the service when creating a payment. |
items[].direction | stringPAYIN PAYOUT | always | Direction of money: PAYIN payment acceptance, PAYOUT payout. |
items[].method | object | always | Payment method. |
items[].method.code | string | always | Payment method code. |
items[].method.name | string | always | Payment method name to show to people. |
items[].currency | string | always | Service currency: the payment amount, the limits and a fixed fee are set in it. |
items[].network | stringor null | always | Network, if the currency has several (cryptocurrencies). null: no network. |
items[].flow | stringDIRECT REDIRECT REQUISITE HOSTED_FIELDS | always | How 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[].minorUnit | integer | always | How many minor units are in one unit of the currency: 100 for BRL, 1 for JPY. |
items[].amount | object | always | Amount limits. |
items[].amount.minMinor | stringor null | always | The smallest payment amount in minor units. null: no lower limit. |
items[].amount.maxMinor | stringor null | always | The largest payment amount in minor units. null: no upper limit. |
items[].fields | array of objects | always | Payer fields the service accepts, in the same order as on the payment form. |
items[].fields[].key | string | always | Field name. The field is sent under this name when creating a payment. |
items[].fields[].kind | stringTEXT DIGITS EMAIL PHONE DATE COUNTRY | always | Value 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[].required | boolean | always | Whether the field is required for this service. |
items[].fields[].pattern | stringor null | always | Regular expression the whole value must match. null: no pattern check. |
items[].fields[].maxLength | integer | always | Maximum value length in characters. |
items[].fee | object | always | The merchant's fee for a payment with this service. |
items[].fee.type | stringPERCENT FIXED | always | Fee kind: PERCENT a percentage of the amount, FIXED a fixed amount. |
items[].fee.percent | stringor null | always | Percentage as a string with four decimal places, such as "1.9000". Set for PERCENT, otherwise null. |
items[].fee.amountMinor | stringor null | always | Fixed amount in minor units of the service currency. Set for FIXED, otherwise null. |
{
"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-Keyheader 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: trueheader. - 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.
| Field | Type | Required | Description |
|---|---|---|---|
reference | string | yes | Your 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. |
service | string | yes | Service code from the service list. The service sets the currency, the payment method and the payer fields. |
amountMinor | string | yes | The 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. |
customer | object | yes | The customer who pays. |
customer.id | string | yes | Your customer ID: 1 to 128 characters, with no leading or trailing spaces and no invisible characters. |
customer.country | string | no | The customer's country: a two-letter ISO 3166-1 code in capitals (GB, not UK). |
fields | object with arbitrary keys | no | Payer fields keyed as in the service list, for example payer.tax_id. A field the service does not have is rejected. |
returnUrl | string | no | Where 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. |
callbackUrl | string | no | Notification 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. |
fieldsOnPage | boolean | no | true: 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. |
metadata | object with arbitrary keys | no | Your 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
| Field | Type | Present | Description |
|---|---|---|---|
id | string | always | Payment ID: pr_ followed by 22 characters. Use it to read the payment. |
reference | string | always | The order number sent at creation. |
service | stringor null | always | Code of the service the payment was created with. |
environment | stringTEST LIVE | always | The payment's environment: the environment of the key that created it. |
status | stringCREATED PROCESSING AWAITING_CUSTOMER SUCCEEDED PARTIALLY_PAID OVERPAID FAILED CANCELLED EXPIRED REJECTED | always | Payment status: Payment statuses. |
reason | stringor null | always | Reason for the status as a code; null when there is nothing to name: Reasons. |
inReview | boolean | always | The 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. |
amountMinor | string | always | The requested amount as a string, in minor units of the payment currency. |
currency | string | always | Payment currency: the service currency. |
network | stringor null | always | Network, if the currency has several. null: no network. |
paidMinor | stringor null | always | The 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. |
feeMinor | stringor null | always | The merchant's fee for the payment, in minor units of the payment currency, calculated at creation. |
refundedMinor | string | always | How 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. |
action | objector null | always | What 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.type | stringredirect requisite | always | redirect: send the payer to url; requisite: show the payment details. |
action.url | string | not always | Where to send the payer: the provider's page or, with fieldsOnPage, the payment page. Only with redirect. |
action.requisite | object | not always | Payment details. Only with requisite: Payment details. |
action.requisite.presentation | stringqr transfer voucher | always | How 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.payload | string | always | The main string of the payment details: the code content, the account or voucher number. |
action.requisite.fields | object with arbitrary keys | always | Labels 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.payAmountMinor | string | always | How much to transfer, in minor units of payCurrency. |
action.requisite.payCurrency | string | always | Currency of the amount to pay. With conversion it differs from the payment currency. |
action.requisite.payAmountChanged | boolean | always | true: the provider asked for an amount different from the payment amount; tell the payer "transfer exactly this amount". |
action.expiresAt | stringor null | not always | Until when the payment details are valid, in UTC. null: no deadline named. Only with requisite. |
customer | object | always | The customer who pays. |
customer.id | string | always | The customer ID sent at creation. |
returnUrl | stringor null | always | The payer's return address as the server parsed it. null: not set. |
callbackUrl | stringor null | always | The payment's notification address as the server parsed it. null: not set, notifications go to the environment address. |
metadata | any value | always | Your labels, as sent at creation. |
createdAt | string, ISO 8601 timestamp | always | When the payment was created, in UTC. |
expiresAt | string, ISO 8601 timestampor null | always | Payment deadline, in UTC: Payment deadline. |
finalizedAt | string, ISO 8601 timestampor null | always | When the payment got a final status, in UTC. null: not yet. |
pageUrl | stringor null | always | Link 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. |
{
"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:
| HTTP | Code and rule | When it happens and what to do |
|---|---|---|
| 400 | validation_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. Fix the body against the field table. |
Example response | ||
| 400 | validation_failed | A value failed validation:
Fix the value named by |
Example response | ||
| 400 | bad_amount |
Send the amount as a string in minor units: "1250", not "12.50". |
Example response | ||
| 400 | bad_amount | The amount is well-formed, but the service does not accept it.
Send an amount within the service limits and above its fee. |
Example response | ||
| 403 | forbiddenlive_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 | ||
| 409 | conflict | No payment can be created with the requested service right now.
Take the service from a fresh service list. |
Example response | ||
| 409 | conflictpayment_reference_exists | A payment with this Read that payment instead of creating a new one. |
Example response | ||
| 409 | conflictrequest_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 | ||
| 409 | conflictidempotency_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 | ||
| 409 | conflictidempotency_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 | ||
| 409 | conflict | A parallel request changed the same data at the same moment, for example the customer. No payment was created; Retry the same request. |
Example response | ||
| 409 | keyring_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 | ||
| 422 | identifier_invalid | The payer's data failed validation, for example the checksum of a tax ID. Fix the field value. |
Example response | ||
| 409 | conflict | The payment page cannot collect the payer fields right now.
Collect the fields with your own form and send them in |
Example response | ||
| 409 | conflictcallback_secret_missing |
Issue a secret with |
Example response | ||
| 503 | dependency_unavailable | Payment intake is temporarily not working; no payment was created.
Retry later with the same retry key. |
Example response | ||
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
referencethe 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"| Field | Type | Required | Description |
|---|---|---|---|
reference | string | yes | The 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
| Field | Type | Present | Description |
|---|---|---|---|
items | array of objects | always | The payment with this order number, zero or one. Empty: there is no such order in the key's environment. |
items[].id | string | always | Payment ID: pr_ followed by 22 characters. Use it to read the payment. |
items[].reference | string | always | The order number sent at creation. |
items[].service | stringor null | always | Code of the service the payment was created with. |
items[].environment | stringTEST LIVE | always | The payment's environment: the environment of the key that created it. |
items[].status | stringCREATED PROCESSING AWAITING_CUSTOMER SUCCEEDED PARTIALLY_PAID OVERPAID FAILED CANCELLED EXPIRED REJECTED | always | Payment status: Payment statuses. |
items[].reason | stringor null | always | Reason for the status as a code; null when there is nothing to name: Reasons. |
items[].inReview | boolean | always | The 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[].amountMinor | string | always | The requested amount as a string, in minor units of the payment currency. |
items[].currency | string | always | Payment currency: the service currency. |
items[].network | stringor null | always | Network, if the currency has several. null: no network. |
items[].paidMinor | stringor null | always | The 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[].feeMinor | stringor null | always | The merchant's fee for the payment, in minor units of the payment currency, calculated at creation. |
items[].refundedMinor | string | always | How 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[].action | objector null | always | What 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.type | stringredirect requisite | always | redirect: send the payer to url; requisite: show the payment details. |
items[].action.url | string | not always | Where to send the payer: the provider's page or, with fieldsOnPage, the payment page. Only with redirect. |
items[].action.requisite | object | not always | Payment details. Only with requisite: Payment details. |
items[].action.requisite.presentation | stringqr transfer voucher | always | How 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.payload | string | always | The main string of the payment details: the code content, the account or voucher number. |
items[].action.requisite.fields | object with arbitrary keys | always | Labels 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.payAmountMinor | string | always | How much to transfer, in minor units of payCurrency. |
items[].action.requisite.payCurrency | string | always | Currency of the amount to pay. With conversion it differs from the payment currency. |
items[].action.requisite.payAmountChanged | boolean | always | true: the provider asked for an amount different from the payment amount; tell the payer "transfer exactly this amount". |
items[].action.expiresAt | stringor null | not always | Until when the payment details are valid, in UTC. null: no deadline named. Only with requisite. |
items[].customer | object | always | The customer who pays. |
items[].customer.id | string | always | The customer ID sent at creation. |
items[].returnUrl | stringor null | always | The payer's return address as the server parsed it. null: not set. |
items[].callbackUrl | stringor null | always | The payment's notification address as the server parsed it. null: not set, notifications go to the environment address. |
items[].metadata | any value | always | Your labels, as sent at creation. |
items[].createdAt | string, ISO 8601 timestamp | always | When the payment was created, in UTC. |
items[].expiresAt | string, ISO 8601 timestampor null | always | Payment deadline, in UTC: Payment deadline. |
items[].finalizedAt | string, ISO 8601 timestampor null | always | When the payment got a final status, in UTC. null: not yet. |
items[].pageUrl | stringor null | always | Link 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. |
{
"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:
| HTTP | Code and rule | When it happens and what to do |
|---|---|---|
| 400 | validation_failed |
Send one order number. |
Example response | ||
| 400 | validation_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 | ||
| 501 | not_implemented | A request without Read a payment by its ID or by its order number. |
Example response | ||
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
| Field | Type | Present | Description |
|---|---|---|---|
id | string | always | Payment ID: pr_ followed by 22 characters. Use it to read the payment. |
reference | string | always | The order number sent at creation. |
service | stringor null | always | Code of the service the payment was created with. |
environment | stringTEST LIVE | always | The payment's environment: the environment of the key that created it. |
status | stringCREATED PROCESSING AWAITING_CUSTOMER SUCCEEDED PARTIALLY_PAID OVERPAID FAILED CANCELLED EXPIRED REJECTED | always | Payment status: Payment statuses. |
reason | stringor null | always | Reason for the status as a code; null when there is nothing to name: Reasons. |
inReview | boolean | always | The 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. |
amountMinor | string | always | The requested amount as a string, in minor units of the payment currency. |
currency | string | always | Payment currency: the service currency. |
network | stringor null | always | Network, if the currency has several. null: no network. |
paidMinor | stringor null | always | The 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. |
feeMinor | stringor null | always | The merchant's fee for the payment, in minor units of the payment currency, calculated at creation. |
refundedMinor | string | always | How 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. |
action | objector null | always | What 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.type | stringredirect requisite | always | redirect: send the payer to url; requisite: show the payment details. |
action.url | string | not always | Where to send the payer: the provider's page or, with fieldsOnPage, the payment page. Only with redirect. |
action.requisite | object | not always | Payment details. Only with requisite: Payment details. |
action.requisite.presentation | stringqr transfer voucher | always | How 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.payload | string | always | The main string of the payment details: the code content, the account or voucher number. |
action.requisite.fields | object with arbitrary keys | always | Labels 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.payAmountMinor | string | always | How much to transfer, in minor units of payCurrency. |
action.requisite.payCurrency | string | always | Currency of the amount to pay. With conversion it differs from the payment currency. |
action.requisite.payAmountChanged | boolean | always | true: the provider asked for an amount different from the payment amount; tell the payer "transfer exactly this amount". |
action.expiresAt | stringor null | not always | Until when the payment details are valid, in UTC. null: no deadline named. Only with requisite. |
customer | object | always | The customer who pays. |
customer.id | string | always | The customer ID sent at creation. |
returnUrl | stringor null | always | The payer's return address as the server parsed it. null: not set. |
callbackUrl | stringor null | always | The payment's notification address as the server parsed it. null: not set, notifications go to the environment address. |
metadata | any value | always | Your labels, as sent at creation. |
createdAt | string, ISO 8601 timestamp | always | When the payment was created, in UTC. |
expiresAt | string, ISO 8601 timestampor null | always | Payment deadline, in UTC: Payment deadline. |
finalizedAt | string, ISO 8601 timestampor null | always | When the payment got a final status, in UTC. null: not yet. |
pageUrl | stringor null | always | Link 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. |
{
"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:
| HTTP | Code and rule | When it happens and what to do |
|---|---|---|
| 404 | not_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 | ||
| 400 | validation_failed | The ID in the path is badly encoded: Pass the ID exactly as the creation response returned it. |
Example response | ||
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-Keyheader is required. A 409 error with a rule, exceptrequest_in_progressandrefund_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, 403merchant_not_active,environment_closed) also takes the retry key: a retry with the same key gets the same error andIdempotency-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_unavailableresponse 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: trueheader. - 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.
| Field | Type | Required | Description |
|---|---|---|---|
reference | string | yes | Your 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. |
amountMinor | string | yes | The 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. |
description | string | no | A note for employees, up to 255 characters. The payer does not see it. |
metadata | object with arbitrary keys | no | Your labels: a JSON object, as for a payment. Returned in the response as is. |
callbackUrl | string | no | Notification 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
| Field | Type | Present | Description |
|---|---|---|---|
id | string | always | Refund ID: rf_ followed by 22 characters. |
payment | string | always | ID of the payment whose money is returned. |
reference | string | always | The refund number sent at creation. |
environment | stringTEST LIVE | always | The refund's environment: the payment's environment. |
status | stringPENDING SUCCEEDED FAILED | always | PENDING 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. |
reason | stringor nullrefund_declined technical_failure operator_declined | always | Reason for a failure: refund_declined the provider declined, technical_failure a technical failure, operator_declined an employee declined. null for other statuses. |
inReview | boolean | always | The 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. |
amountMinor | string | always | The refund amount in minor units of the payment currency. |
currency | string | always | Refund currency: the payment currency. |
feeMinor | string | always | The refund fee in minor units of the payment currency, on top of the refund amount. |
providerRefundId | stringor null | always | The provider's refund operation number, if it named one: quote it to the payer's bank. |
description | stringor null | always | The description sent at creation. null: not set. |
metadata | any value | always | Your labels, as sent at creation. |
callbackUrl | stringor null | always | The refund's notification address as the server parsed it. null: not set, notifications go to the environment address. |
createdAt | string, ISO 8601 timestamp | always | When the refund was created, in UTC. |
finalizedAt | string, ISO 8601 timestampor null | always | When the refund got its outcome, in UTC. null: not yet. |
{
"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:
| HTTP | Code and rule | When it happens and what to do |
|---|---|---|
| 400 | validation_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. Fix the body against the field table. |
Example response | ||
| 400 | validation_failed | A value failed validation:
Fix the value named by |
Example response | ||
| 400 | bad_amount |
Send the amount as a string in minor units of the payment currency. |
Example response | ||
| 404 | not_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 | ||
| 409 | conflictrefund_reference_exists | A refund with this Read that refund instead of creating a new one. |
Example response | ||
| 409 | conflictrefund_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 | ||
| 409 | conflict | This refund is not possible.
A retry with the same key gets the same error: send the corrected request with a new retry key. |
Example response | ||
| 409 | conflictcallback_secret_missing |
Issue a secret with |
Example response | ||
| 409 | conflictrequest_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 | ||
| 409 | conflictidempotency_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 | ||
| 503 | dependency_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.
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 | ||
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
| Field | Type | Present | Description |
|---|---|---|---|
items | array of objects | always | All refunds of the payment, newest first. Empty: there are no refunds. |
items[].id | string | always | Refund ID: rf_ followed by 22 characters. |
items[].payment | string | always | ID of the payment whose money is returned. |
items[].reference | string | always | The refund number sent at creation. |
items[].environment | stringTEST LIVE | always | The refund's environment: the payment's environment. |
items[].status | stringPENDING SUCCEEDED FAILED | always | PENDING 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[].reason | stringor nullrefund_declined technical_failure operator_declined | always | Reason for a failure: refund_declined the provider declined, technical_failure a technical failure, operator_declined an employee declined. null for other statuses. |
items[].inReview | boolean | always | The 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[].amountMinor | string | always | The refund amount in minor units of the payment currency. |
items[].currency | string | always | Refund currency: the payment currency. |
items[].feeMinor | string | always | The refund fee in minor units of the payment currency, on top of the refund amount. |
items[].providerRefundId | stringor null | always | The provider's refund operation number, if it named one: quote it to the payer's bank. |
items[].description | stringor null | always | The description sent at creation. null: not set. |
items[].metadata | any value | always | Your labels, as sent at creation. |
items[].callbackUrl | stringor null | always | The refund's notification address as the server parsed it. null: not set, notifications go to the environment address. |
items[].createdAt | string, ISO 8601 timestamp | always | When the refund was created, in UTC. |
items[].finalizedAt | string, ISO 8601 timestampor null | always | When the refund got its outcome, in UTC. null: not yet. |
{
"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:
| HTTP | Code and rule | When it happens and what to do |
|---|---|---|
| 404 | not_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 | ||
| 400 | validation_failed | The ID in the path is badly encoded: Pass the ID exactly as the creation response returned it. |
Example response | ||
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
| Field | Type | Present | Description |
|---|---|---|---|
id | string | always | Refund ID: rf_ followed by 22 characters. |
payment | string | always | ID of the payment whose money is returned. |
reference | string | always | The refund number sent at creation. |
environment | stringTEST LIVE | always | The refund's environment: the payment's environment. |
status | stringPENDING SUCCEEDED FAILED | always | PENDING 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. |
reason | stringor nullrefund_declined technical_failure operator_declined | always | Reason for a failure: refund_declined the provider declined, technical_failure a technical failure, operator_declined an employee declined. null for other statuses. |
inReview | boolean | always | The 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. |
amountMinor | string | always | The refund amount in minor units of the payment currency. |
currency | string | always | Refund currency: the payment currency. |
feeMinor | string | always | The refund fee in minor units of the payment currency, on top of the refund amount. |
providerRefundId | stringor null | always | The provider's refund operation number, if it named one: quote it to the payer's bank. |
description | stringor null | always | The description sent at creation. null: not set. |
metadata | any value | always | Your labels, as sent at creation. |
callbackUrl | stringor null | always | The refund's notification address as the server parsed it. null: not set, notifications go to the environment address. |
createdAt | string, ISO 8601 timestamp | always | When the refund was created, in UTC. |
finalizedAt | string, ISO 8601 timestampor null | always | When the refund got its outcome, in UTC. null: not yet. |
{
"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:
| HTTP | Code and rule | When it happens and what to do |
|---|---|---|
| 404 | not_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 | ||
| 400 | validation_failed | The ID in the path is badly encoded: Pass the ID exactly as the creation response returned it. |
Example response | ||
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-Keyheader 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 409idempotency_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: trueheader. - Live payouts are closed for now, and payouts are not sent yet: an approved payout stays
CREATEDand 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.
| Field | Type | Required | Description |
|---|---|---|---|
reference | string | yes | Your 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. |
service | string | yes | Payout service code from the service list (direction = PAYOUT). The service sets the currency, method and beneficiary fields. |
amountMinor | string | yes | What 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. |
customer | object | yes | The customer the payout is for. |
customer.id | string | yes | Your customer ID: 1 to 128 characters, no leading or trailing spaces and no invisible characters. |
customer.country | string | no | Customer country: an ISO 3166-1 code of two capital letters (GB, not UK). |
fields | object with arbitrary keys | yes | Requisite 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. |
metadata | object with arbitrary keys | no | Your labels: a JSON object up to 4096 characters per entry and up to 16 levels deep. Returned in the response as is. |
callbackUrl | string | no | Notification 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
| Field | Type | Present | Description |
|---|---|---|---|
id | string | always | Payout ID: po_ followed by 22 characters. Use it to read and cancel the payout. |
reference | string | always | The withdrawal number sent at creation. |
service | string | always | The service code the payout was created with. |
environment | stringTEST LIVE | always | The payout's environment: the environment of the key it was created with. |
status | stringCREATED PROCESSING SUCCEEDED FAILED REJECTED CANCELLED | always | CREATED 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. |
reason | stringor nullcustomer_blocked rejected_by_operator cancelled_by_merchant | always | Why 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. |
approval | stringPENDING APPROVED REJECTED WITHDRAWN | always | Moderation decision: APPROVED approved, PENDING waiting for an employee, REJECTED rejected, WITHDRAWN withdrawn by your cancellation. |
inReview | boolean | always | The 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. |
amountMinor | string | always | What the player receives, in minor units of the payout currency. |
currency | string | always | Payout currency: the service currency. |
feeMinor | string | always | The payout fee in minor units of the payout currency, on top of the amount. |
metadata | any value | always | Your labels, as sent at creation. |
callbackUrl | stringor null | always | The payout's notification address as the server parsed it. null: not set, notifications go to the environment address if there is one. |
createdAt | string, ISO 8601 timestamp | always | When the payout was created, in UTC. |
finalizedAt | string, ISO 8601 timestampor null | always | When the payout closed, in UTC. null: not yet. |
{
"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:
| HTTP | Code and rule | When it happens and what to do |
|---|---|---|
| 400 | validation_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. Fix the body against the field table. |
Example response | ||
| 400 | validation_failed | A header or value failed validation:
Fix the value named in |
Example response | ||
| 400 | bad_amount |
Send the amount as a string in minor units: «1250», not «12.50». |
Example response | ||
| 400 | bad_amountamount_out_of_range | The amount is well formed but outside the service limits; Send an amount within the service limits with a new retry key. |
Example response | ||
| 403 | forbidden | A live payout cannot be created now. Checked after the header and body format.
Create payouts with a test key. |
Example response | ||
| 409 | conflict | A payout cannot be created with the service from the request now. The error takes the retry key.
Take a payout service from a fresh service list and send the request with a new retry key. |
Example response | ||
| 409 | conflictpayout_reference_exists | A payout with this Read that payout instead of creating a new one. |
Example response | ||
| 409 | conflictinsufficient_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 | ||
| 422 | identifier_invalid | The requisite or beneficiary data failed validation, for example a tax ID or IBAN checksum. Fix the field value and send the request with a new retry key. |
Example response | ||
| 409 | conflictcallback_secret_missing |
Issue a secret with |
Example response | ||
| 409 | conflictrequest_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 | ||
| 409 | conflictidempotency_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 | ||
| 503 | dependency_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.
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 | ||
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
| Field | Type | Present | Description |
|---|---|---|---|
id | string | always | Payout ID: po_ followed by 22 characters. Use it to read and cancel the payout. |
reference | string | always | The withdrawal number sent at creation. |
service | string | always | The service code the payout was created with. |
environment | stringTEST LIVE | always | The payout's environment: the environment of the key it was created with. |
status | stringCREATED PROCESSING SUCCEEDED FAILED REJECTED CANCELLED | always | CREATED 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. |
reason | stringor nullcustomer_blocked rejected_by_operator cancelled_by_merchant | always | Why 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. |
approval | stringPENDING APPROVED REJECTED WITHDRAWN | always | Moderation decision: APPROVED approved, PENDING waiting for an employee, REJECTED rejected, WITHDRAWN withdrawn by your cancellation. |
inReview | boolean | always | The 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. |
amountMinor | string | always | What the player receives, in minor units of the payout currency. |
currency | string | always | Payout currency: the service currency. |
feeMinor | string | always | The payout fee in minor units of the payout currency, on top of the amount. |
metadata | any value | always | Your labels, as sent at creation. |
callbackUrl | stringor null | always | The payout's notification address as the server parsed it. null: not set, notifications go to the environment address if there is one. |
createdAt | string, ISO 8601 timestamp | always | When the payout was created, in UTC. |
finalizedAt | string, ISO 8601 timestampor null | always | When the payout closed, in UTC. null: not yet. |
{
"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:
| HTTP | Code and rule | When it happens and what to do |
|---|---|---|
| 404 | not_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 | ||
| 400 | validation_failed | The ID in the path is badly encoded: Pass the ID exactly as the creation response returned it. |
Example response | ||
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
| Field | Type | Present | Description |
|---|---|---|---|
id | string | always | Payout ID: po_ followed by 22 characters. Use it to read and cancel the payout. |
reference | string | always | The withdrawal number sent at creation. |
service | string | always | The service code the payout was created with. |
environment | stringTEST LIVE | always | The payout's environment: the environment of the key it was created with. |
status | stringCREATED PROCESSING SUCCEEDED FAILED REJECTED CANCELLED | always | CREATED 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. |
reason | stringor nullcustomer_blocked rejected_by_operator cancelled_by_merchant | always | Why 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. |
approval | stringPENDING APPROVED REJECTED WITHDRAWN | always | Moderation decision: APPROVED approved, PENDING waiting for an employee, REJECTED rejected, WITHDRAWN withdrawn by your cancellation. |
inReview | boolean | always | The 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. |
amountMinor | string | always | What the player receives, in minor units of the payout currency. |
currency | string | always | Payout currency: the service currency. |
feeMinor | string | always | The payout fee in minor units of the payout currency, on top of the amount. |
metadata | any value | always | Your labels, as sent at creation. |
callbackUrl | stringor null | always | The payout's notification address as the server parsed it. null: not set, notifications go to the environment address if there is one. |
createdAt | string, ISO 8601 timestamp | always | When the payout was created, in UTC. |
finalizedAt | string, ISO 8601 timestampor null | always | When the payout closed, in UTC. null: not yet. |
{
"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:
| HTTP | Code and rule | When it happens and what to do |
|---|---|---|
| 404 | not_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 | ||
| 409 | conflictpayout_not_cancellable | The payout can no longer be cancelled: it was sent or closed; Read the payout and wait for its outcome. |
Example response | ||
| 400 | validation_failed | The ID in the path is badly encoded: Pass the ID exactly as the creation response returned it. |
Example response | ||
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
| Field | Type | Present | Description |
|---|---|---|---|
secret | string | always | whsec_…: the notification signing secret; verify signatures with it per Standard Webhooks. Shown once. |
environment | stringTEST LIVE | always | The secret's environment: the API key's environment. |
createdAt | string | always | When the secret was issued, UTC. |
{
"secret": "whsec_<base64 of 32 bytes>",
"environment": "TEST",
"createdAt": "2026-11-17T10:00:00.000Z"
}Errors
In addition to the common errors:
| HTTP | Code and rule | When it happens and what to do |
|---|---|---|
| 400 | validation_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. Fix the body against the field table. |
Example response | ||
| 409 | conflictnotify_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 | ||
| 409 | conflictkeyring_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 | ||