Create Payout Order¶

Creates a new payout order.

Payout Order

A payout order is a payout operation created for a merchant gate payment method. Payout orders represent outgoing funds from a merchant or gate balance to a destination account.

Idempotency

Idempotency prevents duplicate payout requests by using the unique reference_id value.

Each reference_id should identify one payout request and must be unique within the merchant context. If the same reference_id is submitted again for the same context, the system can detect the request as a duplicate.

Use a newly generated UUID or another stable unique value for each new payout request, especially when generating reference_id values automatically.

Endpoint¶

POST /api/v1/orders/payout

POST /api/v1/orders/payout HTTP/1.1
X-Api-Key-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
X-Signature: <generated-signature>
X-Timestamp: 1234567
Content-Type: application/json
Accept: application/json

{
  "reference_id": "merchant-payout-12345",
  "currency": "USD",
  "amount": 100.00,
  "destination_account": "4111111111111111",
  "merchant_gate_method_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "payment_method_data": {
    "payment_url": "https://merchant.example/payment/12345"
  },
  "customer": {
    "reference_id": "customer-12345",
    "first_name": "John",
    "last_name": "Doe",
    "email": "user@example.com",
    "phone": "+12025550123",
    "address": {
      "country": "FR",
      "city": "New York",
      "street": "Main Street 10",
      "post_code": "10001"
    }
  },
  "comment": "Payout order comment"
}

{
  "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": "4111111111111111",
  "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. For signature generation rules, see Request Signature Authentication.

Request body for creating a payout order.

reference_id string required

Merchant-side order identifier. Use this value to match the payout order with the corresponding order in the merchant system and to prevent duplicate payout requests.

Constraints: 0-255 characters; matches [A-Za-z0-9.=-]*

currency string required

Currency in which the payout order amount is processed.

Possible values:

USDEURUAHKZTUSDT_TRON

amount number required

Payout order amount.

Constraints: Use a dot as the decimal separator; maximum 2 decimal places.

destination_account string required

Destination account value used for the payout. For card payouts, this value can be the destination card number.

Example: 4111111111111111

Constraints: 0-255 characters

merchant_gate_method_id string · uuid required

Identifier of the merchant gate payment method used to create and process the payout order.

payment_method_data object optional

Additional payment method data used for the selected merchant gate payment method.

payment_url string optional

URL of the merchant website or payment page associated with the payment.

Constraints: 0-2048 characters

customer object required

Customer information associated with the payout order.

reference_id string optional

Customer identifier in the merchant system.

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

first_name string optional

Customer first name. Use Latin letters and supported special characters only.

Constraints: 0-50 characters; Latin letters, spaces, hyphens and apostrophes only.

last_name string optional

Customer last name. Use Latin letters and supported special characters only.

Constraints: 0-50 characters; Latin letters, spaces, hyphens and apostrophes only.

email string · email optional

Customer email address in a standard email format, such as local-part@domain. The value must contain a local part, the @ symbol, and a valid domain.

phone string optional

Customer phone number in international format. The value must start with + and contain digits after the country calling code.

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

address object optional

Customer address information.

country string optional

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

Example: FR

city string optional

Customer city name.

Constraints: 0-100 characters; Latin letters, digits, spaces, hyphens, and dots only.

street string optional

Customer street address.

Constraints: 0-255 characters; Latin letters, digits, spaces, hyphens, and dots only.

post_code string optional

Customer postal or ZIP code.

Constraints: 0-50 characters

comment string optional

Comment associated with the payout order.

Constraints: 0-255 characters

Responses

200 OK. Payout order created successfully. application/json

Returns the created payout order object.

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. For card payouts, this can be the destination card number. Depending on the payment method, this can also represent a bank account, wallet, phone number, crypto address, PIX key, or another destination identifier.

Example: 4111111111111111

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.

Create Payout Order¶

Endpoint¶

Headers

Request body

Responses