Get Payout Orders by Reference ID¶

Returns payout orders by the merchant-side order reference identifier.

Use this endpoint when you need to retrieve one or more payout orders associated with the same reference_id value in the merchant system.

Endpoint¶

GET /api/v1/orders/payout?reference_id={reference_id}

GET /api/v1/orders/payout?reference_id=merchant-payout-12345 HTTP/1.1
X-Api-Key-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
X-Signature: <generated-signature>
X-Timestamp: 1234567
Accept: application/json

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "reference_id": "merchant-payout-12345",
    "status": "CREATED",
    "resolution": "OK",
    "resolution_code": "WORKFLOW_EXECUTION_SKIPPED",
    "resolution_message": "Order created successfully.",
    "provider_error_message": "",
    "payment_source": "CARD",
    "currency": "USD",
    "amount": 100.0,
    "destination_account": "destination-account-12345",
    "fee_percent": 1,
    "fee_fixed": 3,
    "fee_min": 1,
    "fee_max": 7,
    "fee_total": 4,
    "total": 104,
    "payment_method_data": {
      "bank_id": "bank_001",
      "cpf": "11371142882",
      "iban": "GB82WEST12345698765432",
      "ifsc": "ifsc_001",
      "pix_key": "customer@example.com",
      "tckn": "30641505382"
    },
    "customer": {
      "reference_id": "customer-12345",
      "first_name": "John",
      "last_name": "Doe",
      "email": "user@example.com",
      "phone": "+12025550123",
      "address": {
        "country": "FR",
        "city": "Paris",
        "street": "Main Street 10",
        "post_code": "75001"
      }
    },
    "create_date": 1783705454,
    "update_date": 1783705454,
    "comment": "Payout order comment."
  }
]

X-Api-Key-Id string · uuid required

API key identifier issued for the merchant integration.

X-Signature string required

Request signature generated from the HTTP method, request path without query string, raw request body, and timestamp.

X-Timestamp integer · int64 required

Unix epoch timestamp in seconds used in the signature base string.

Request signature

This endpoint requires the X-Signature header. This GET request has no request body, so the signature base string uses an empty request body value. For signature generation rules, see Request Signature Authentication.

reference_id string required

Merchant-side order reference identifier. Use this parameter to retrieve payout orders created with the specified reference value.

Responses

200 OK. Payout orders returned successfully. application/json

Returns an array of payout order objects matching the provided reference ID.

Items array<object>

Payout order object returned in the response array.

id string · uuid

System-generated unique payout order identifier. Use this value to retrieve a specific payout order by ID.

group_id string · uuid

Identifier used to group related orders. Orders created or processed as part of the same operation can share this value.

reference_id string

Order reference identifier provided by the merchant system. Use this value to match the payout order with the corresponding order in the merchant system.

status string · enum

Current payout order processing status.

Possible values:

CREATEDIN_PROGRESSPROCESS_PENDINGSUCCESSFAILEDCLOSED

resolution string · enum

High-level processing resolution for the order.

Possible values:

OKSYSTEM_ERRORPROVIDER_ERROR

resolution_code string · enum

Machine-readable resolution reason code returned for the order.

Possible values:

ACCESS_DENIEDAMOUNT_OVER_LIMITAMOUNT_UNDER_LIMITBALANCE_INSUFFICIENTBALANCE_UPDATE_FAILEDBLACKLISTED_INPUT_DATACURRENCY_INVALIDDESTINATION_ACCOUNT_INVALIDMERCHANT_MISCONFIGURATIONMETHOD_INACTIVEMETHOD_NOT_FOUNDORDER_CANNOT_BE_PROCESSEDORDER_CANNOT_BE_ROUTEDORDER_FAILED_MANUALLYPAYMENT_METHOD_NOT_SUPPORTEDPROVIDER_NOT_SUPPORTEDREPORT_GENERATION_FAILEDRESOURCE_NOT_FOUNDUNKNOWN_ERRORVALIDATION_FAILEDWORKFLOW_EXECUTION_SKIPPED

resolution_message string

Human-readable message with additional details about the order resolution.

provider_error_message string

Error message returned by the payment provider, if available.

payment_source string · enum

Payment source used for the payout order.

Possible values:

CARDP2PCRYPTOPHONEPIXBLIK

currency string · enum

Payout order currency.

Possible values:

USDEURUAHKZTUSDT_TRON

amount number

Original payout order amount in the order currency.

destination_account string

External destination account to which the payout is sent. Depending on the payment method, this can represent a bank account, card, wallet, phone number, crypto address, PIX key, or another destination identifier.

fee_percent number

Percentage-based fee rate applied to the order amount.

fee_fixed number

Fixed fee amount charged for the order.

fee_min number

Minimum fee amount that can be applied to the order.

fee_max number

Maximum fee amount that can be applied to the order.

fee_total number

Final fee amount calculated for the order after applying percentage, fixed, minimum, and maximum fee rules.

total number

Calculated payout total after fee calculation. In payout flows, this usually represents the amount written off from the merchant or gate balance.

payment_method_data object

Payment-method-specific data returned for the order.

bank_id string

Bank identifier used by a payment method or provider.

Constraints: Matches ^[a-z0-9_-]{1,200}$

cpf string

CPF value used for payment methods that require CPF.

Constraints: Matches ^[0-9]{11}$

iban string

IBAN value used for bank transfer or account-based payment methods.

Constraints: Matches ^[A-Z0-9]{15,36}$

ifsc string

IFSC value used for payment methods that require IFSC.

Constraints: Matches ^[a-z0-9_-]{1,200}$

pix_key string

PIX key used for PIX-based payment methods.

Constraints: 0-1024 characters

tckn string

TCKN value used for payment methods that require TCKN.

Constraints: Matches ^[0-9]{11}$

customer object

Customer information associated with the order.

reference_id string

Customer identifier in the merchant system.

Constraints: Matches ^[a-zA-Z0-9_-]{1,64}$

first_name string

Customer first name.

Constraints: Matches ^[\p{L} .'-]+$; 0-50 characters

last_name string

Customer last name.

Constraints: Matches ^[\p{L} .'-]+$; 0-50 characters

email string · email

Customer email address.

phone string

Customer phone number in international format.

Constraints: Matches ^\+[0-9]{5,30}$

address object

Customer address information.

country string

Two-letter country code in ISO 3166-1 alpha-2 format.

Example: FR

city string

Customer city.

Constraints: Matches ^[\p{L} .'-]+$; 0-100 characters

street string

Customer street address.

Constraints: 0-255 characters

post_code string

Customer postal code.

Constraints: 0-50 characters

create_date integer · int64

Unix timestamp in seconds indicating when the order was created.

update_date integer · int64

Unix timestamp in seconds indicating when the order was last updated.

comment string

Comment associated with the order.

Get Payout Orders by Reference ID¶

Endpoint¶

Headers

Query parameters

Responses