2.1 Create withdrawal

POST /api/v2/withdrawals

Send one JSON object and no query string. Use the v2 authentication headers. The successful response is HTTP 200.

Field	Type	Required	Description
order_id	string, max 255 characters	Yes	Your withdrawal identifier. Unique per merchant and operation type for idempotency.
amount	JSON number	Yes	Positive amount, at most two decimal places. Do not send a quoted string.
currency	string, 3 letters	Yes	Use BOB for this guide; it must match the selected shop's currency.
method	string	No	Exact active shop code. Omit to use your default active shop. Do not add surrounding spaces.
customer_account_id	JSON integer	No	Your customer's account identifier used by the shared payment checks. Send an integer, not a quoted number; 0 is preserved. Omit or use null when unavailable.
callback_url	HTTPS URL	Yes	Absolute callback URL without embedded credentials.
account_number	string, max 255 characters	Yes	Recipient account. For a card shop, 12–19 digits; for a mobile shop, + followed by 8–15 digits, with the first digit non-zero. Other formats depend on the shop.
fields	JSON object	No*	Additional data defined by the selected shop's PayOut schema. See shop fields.
fields.merchant_user_ip	string (IPv4 or IPv6)	Shop-dependent	Customer IP address. Supported for every shop; required only when the selected shop's input schema requires it. Omit or use null when optional and unavailable.

The mobile rule applies to the selected shop's mobile method, not every wallet or opaque identifier. Card identifiers contain digits only, without spaces or hyphens. callback_url must be an absolute HTTPS URL string without embedded credentials, whitespace, or control characters.

The v2 protocol does not require fields, but the selected shop may require individual keys. fields must be a JSON object, not an array. It cannot override protocol fields such as method, customer_account_id, account_number, recipient_account, or account_channel.

Example for an active BOB card shop configured with recipient_name and bank_name. Replace your_bob_shop with your actual shop code and use the field schema assigned to that shop:

{
  "order_id": "WD-BOB-1001",
  "amount": 500,
  "currency": "BOB",
  "method": "your_bob_shop",
  "customer_account_id": 77,
  "callback_url": "https://merchant.example.com/webhooks/payfield",
  "account_number": "4111111111111111",
  "fields": {
    "recipient_name": "Ana Perez",
    "bank_name": "Banco Ejemplo",
    "merchant_user_ip": "203.0.113.10"
  }
}

Response 200:

{
  "transaction_id": "12345"
}

A successful create response does not confirm that the recipient was paid. Retrieve the current result even after HTTP 200.

Store transaction_id and check its status. A retry with the same order_id and equivalent request returns the same response without creating another withdrawal. Reusing the order_id with different request data returns 409. Idempotency is scoped to the merchant and withdrawal type, across shops; an existing v1 withdrawal with the same ID also conflicts. See API errors.