> For the complete documentation index, see [llms.txt](https://docs.newlandsgate.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.newlandsgate.com/api-documentation/payouts.md).

# Payouts

## Create a new payout

> Creates a new payout\
> \
> \*\*Fields Description:\*\*\
> \
> \*\*Required Fields:\*\*\
> \- \`amount\`: Transaction amount as string (e.g., "1000.50"). Must be positive with up to 3 decimal places\
> \- \`requisite\_type\`: Type of payment requisite. Determines the payment method and processing flow\
> \- \`idempotency\_key\`: Unique string to prevent duplicate payout creation. Use same key for retry attempts\
> \- \`customer\_requisite\`: Customer's payment details (card number, account, phone, etc.) (max 255 chars). For \`mobileMoney\` — beneficiary phone digits only\
> \
> \*\*Optional Fields:\*\*\
> \- \`currency\`: Currency code (defaults to RUB if not specified). Supported: RUB, USD, EUR, KGS, KZT, TJS, UZB, AZN, TRY, GEL, XOF, KES, XAF, VND, CNY, MNT, LAK, IDR, PHP, BRL\
> \- \`customer\_requisite\_card\`: Phone and last 4 digits of card for payout, e.g. "79999999999 / 2442" (max 100 chars)\
> \- \`customer\_name\`: End customer's full name for compliance (max 255 chars)\
> \- \`bank\_code\`: Preferred bank code to filter available requisites (e.g., "Sber", "Tinkoff"). \*\*Required\*\* for \`mobileMoney\` — operator (Orange/Wave/MTN/Moov)\
> \- \`merchant\_order\_id\`: Your internal payout identifier for tracking and reconciliation\
> \- \`payment\_redirect\_url\`: Redirect URL for the payout\
> \- \`reverse\_callback\_url\`: Callback URL for reverse integration\
> \
> \*\*Requisite Types:\*\*\
> \- \`SBP\`: Fast payment system (Russia)\
> \- \`card\`: Bank card payments\
> \- \`accountNumber\`: Bank account transfers\
> \- \`internalTransfer\`: Domestic transfers (non-RUB currencies only)\
> \- \`internalTransferMobile\`: Mobile banking transfers (non-RUB currencies only)\
> \- \`internalTransferAccountNumber\`: Domestic transfers by account number (non-RUB currencies only)\
> \- \`phoneTopUp\`: Mobile phone top-up\
> \- \`QR\`: QR code payments\
> \- \`mobileMoney\`: Mobile Money transfers (requires payer phone in customer\_requisite and operator in bank\_code)\
> \
> \*\*Business Rules:\*\*\
> \- Internal transfer types (internalTransfer/internalTransferMobile/internalTransferAccountNumber) only work with non-RUB currencies\
> \- Bank code preference is applied when multiple requisites are available\
> \- For \`mobileMoney\`, customer\_requisite and bank\_code are required; phone only (no OTP)<br>

```json
{"openapi":"3.1.1","info":{"title":"Panda Pay API","version":"1.0"},"servers":[{"url":"https://api.paymentgateway24.com"}],"security":[{"ApiKey":[]},{"Signature":[]},{"Timestamp":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","name":"X-API-Key","in":"header","description":"Merchant API key"},"Signature":{"type":"apiKey","name":"X-Signature","in":"header","description":"HMAC-SHA256 signature of timestamp + request body (or timestamp only for GET)"},"Timestamp":{"type":"apiKey","name":"X-Timestamp","in":"header","description":"Current Unix timestamp (UTC)"}},"schemas":{"v1.CreatePayoutRequest":{"properties":{"amount":{"type":"string"},"bank_code":{"type":"string"},"currency":{"$ref":"#/components/schemas/currency.Currency"},"customer_name":{"type":"string"},"customer_requisite":{"type":"string"},"customer_requisite_card":{"maxLength":100,"type":"string"},"idempotency_key":{"maxLength":255,"minLength":1,"type":"string"},"merchant_order_id":{"type":"string"},"payment_redirect_url":{"type":"string"},"requisite_type":{"$ref":"#/components/schemas/requisite.Type"},"reverse_callback_url":{"type":"string"}},"required":["amount","customer_requisite","idempotency_key","requisite_type"],"type":"object"},"currency.Currency":{"enum":["USDT","RUB","AZN","KGS","KZT","TJS","UZS","ARS","TRY","GEL","XOF","KES","XAF","VND","CNY","MNT","LAK","IDR","PHP","BRL"],"type":"string"},"requisite.Type":{"enum":["SBP","card","accountNumber","internalTransfer","internalTransferMobile","phoneTopUp","QR","internalTransferAccountNumber","mobileMoney"],"type":"string"},"v1.CreatePayoutResponse":{"properties":{"amount":{"type":"string"},"amount_usdt":{"type":"string"},"bank_code":{"type":"string"},"created_at":{"type":"string"},"currency":{"$ref":"#/components/schemas/currency.Currency"},"customer_name":{"type":"string"},"customer_requisite":{"type":"string"},"customer_requisite_card":{"type":"string"},"exchange_rate":{"type":"string"},"expires_at":{"type":"string"},"frozen_balance":{"type":"string"},"merchant_commission":{"type":"string"},"merchant_id":{"type":"string"},"requisite_type":{"$ref":"#/components/schemas/requisite.Type"},"status":{"$ref":"#/components/schemas/order.Status"},"uuid":{"type":"string"}},"type":"object"},"order.Status":{"enum":["pending","inProgress","inReview","cancellationRequested","traderNotFound","timeout","completed","canceled"],"type":"string"},"models.ErrorResponse":{"properties":{"error":{"type":"string"}},"type":"object"}}},"paths":{"/v1/payouts":{"post":{"description":"Creates a new payout\n\n**Fields Description:**\n\n**Required Fields:**\n- `amount`: Transaction amount as string (e.g., \"1000.50\"). Must be positive with up to 3 decimal places\n- `requisite_type`: Type of payment requisite. Determines the payment method and processing flow\n- `idempotency_key`: Unique string to prevent duplicate payout creation. Use same key for retry attempts\n- `customer_requisite`: Customer's payment details (card number, account, phone, etc.) (max 255 chars). For `mobileMoney` — beneficiary phone digits only\n\n**Optional Fields:**\n- `currency`: Currency code (defaults to RUB if not specified). Supported: RUB, USD, EUR, KGS, KZT, TJS, UZB, AZN, TRY, GEL, XOF, KES, XAF, VND, CNY, MNT, LAK, IDR, PHP, BRL\n- `customer_requisite_card`: Phone and last 4 digits of card for payout, e.g. \"79999999999 / 2442\" (max 100 chars)\n- `customer_name`: End customer's full name for compliance (max 255 chars)\n- `bank_code`: Preferred bank code to filter available requisites (e.g., \"Sber\", \"Tinkoff\"). **Required** for `mobileMoney` — operator (Orange/Wave/MTN/Moov)\n- `merchant_order_id`: Your internal payout identifier for tracking and reconciliation\n- `payment_redirect_url`: Redirect URL for the payout\n- `reverse_callback_url`: Callback URL for reverse integration\n\n**Requisite Types:**\n- `SBP`: Fast payment system (Russia)\n- `card`: Bank card payments\n- `accountNumber`: Bank account transfers\n- `internalTransfer`: Domestic transfers (non-RUB currencies only)\n- `internalTransferMobile`: Mobile banking transfers (non-RUB currencies only)\n- `internalTransferAccountNumber`: Domestic transfers by account number (non-RUB currencies only)\n- `phoneTopUp`: Mobile phone top-up\n- `QR`: QR code payments\n- `mobileMoney`: Mobile Money transfers (requires payer phone in customer_requisite and operator in bank_code)\n\n**Business Rules:**\n- Internal transfer types (internalTransfer/internalTransferMobile/internalTransferAccountNumber) only work with non-RUB currencies\n- Bank code preference is applied when multiple requisites are available\n- For `mobileMoney`, customer_requisite and bank_code are required; phone only (no OTP)\n","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1.CreatePayoutRequest"}}},"description":"Payout details","required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1.CreatePayoutResponse"}}}},"400":{"description":"invalid JSON body, missing required field, invalid requisite_type, invalid amount format, insufficient balance, merchant payout commission not configured, or payout with this idempotency key already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}},"summary":"Create a new payout","tags":["Payouts"],"parameters":[{"schema":{"type":"string","default":"application/json"},"name":"Accept","in":"header","description":"Response format"}]}}}}
```

## Export payouts to CSV

> Exports payout data to CSV format based on provided filters. Supports role-based filtering for traders, merchants, and admins.

```json
{"openapi":"3.1.1","info":{"title":"Panda Pay API","version":"1.0"},"servers":[{"url":"https://api.paymentgateway24.com"}],"security":[{"ApiKey":[]},{"Signature":[]},{"Timestamp":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","name":"X-API-Key","in":"header","description":"Merchant API key"},"Signature":{"type":"apiKey","name":"X-Signature","in":"header","description":"HMAC-SHA256 signature of timestamp + request body (or timestamp only for GET)"},"Timestamp":{"type":"apiKey","name":"X-Timestamp","in":"header","description":"Current Unix timestamp (UTC)"}},"schemas":{"models.ErrorResponse":{"properties":{"error":{"type":"string"}},"type":"object"}}},"paths":{"/v1/payouts/export":{"get":{"description":"Exports payout data to CSV format based on provided filters. Supports role-based filtering for traders, merchants, and admins.","parameters":[{"description":"Payout status filter","in":"query","name":"status","schema":{"type":"string","enum":["pending","in_progress","completed","canceled","cancellation_requested"]}},{"description":"Start date filter (RFC3339 format)","in":"query","name":"from_date","schema":{"type":"string"}},{"description":"End date filter (RFC3339 format)","in":"query","name":"to_date","schema":{"type":"string"}},{"description":"Requisite type filter","in":"query","name":"requisite_type","schema":{"type":"string"}},{"description":"Minimum amount in USDT","in":"query","name":"from_usdt","schema":{"type":"number"}},{"description":"Maximum amount in USDT","in":"query","name":"to_usdt","schema":{"type":"number"}},{"description":"Sort by field","in":"query","name":"sort_by","schema":{"type":"string","enum":["created_at","modified_at"]}},{"description":"Merchant ID (admin only)","in":"query","name":"merchant_id","schema":{"type":"string","format":"uuid"}},{"description":"Trader ID (admin only)","in":"query","name":"trader_id","schema":{"type":"string","format":"uuid"}},{"description":"Provider ID filter (admin only, optional)","in":"query","name":"provider_id","schema":{"type":"string","format":"uuid"}},{"schema":{"type":"string","default":"application/json"},"name":"Accept","in":"header","description":"Response format"}],"responses":{"200":{"description":"CSV file with payout data","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid query params, invalid merchant ID, invalid trader ID, or missing merchant_id/trader_id for admin","content":{"text/csv":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"auth token not found or invalid auth token","content":{"text/csv":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"403":{"description":"role not authorized","content":{"text/csv":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"404":{"description":"No payouts found matching the specified criteria. Please adjust your filters and try again.","content":{"text/csv":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"413":{"description":"The requested export is too large. Please add additional filters to reduce the export size or contact support for assistance with large data exports.","content":{"text/csv":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"text/csv":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}},"summary":"Export payouts to CSV","tags":["Payouts"]}}}}
```

## Get payouts by merchant order ID

> Retrieves payouts associated with a specific merchant order ID.

```json
{"openapi":"3.1.1","info":{"title":"Panda Pay API","version":"1.0"},"servers":[{"url":"https://api.paymentgateway24.com"}],"security":[{"ApiKey":[]},{"Signature":[]},{"Timestamp":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","name":"X-API-Key","in":"header","description":"Merchant API key"},"Signature":{"type":"apiKey","name":"X-Signature","in":"header","description":"HMAC-SHA256 signature of timestamp + request body (or timestamp only for GET)"},"Timestamp":{"type":"apiKey","name":"X-Timestamp","in":"header","description":"Current Unix timestamp (UTC)"}},"schemas":{"v1.PayoutMerchantResponse":{"properties":{"amount":{"type":"string"},"amount_usdt":{"type":"string"},"bank_code":{"type":"string"},"created_at":{"type":"string"},"currency":{"$ref":"#/components/schemas/currency.Currency"},"customer_name":{"type":"string"},"customer_requisite":{"type":"string"},"customer_requisite_card":{"type":"string"},"exchange_rate":{"type":"string"},"expires_at":{"type":"string"},"merchant_commission":{"type":"string"},"merchant_id":{"type":"string"},"merchant_order_id":{"type":"string"},"payment_redirect_url":{"type":"string"},"receipt":{"type":"string"},"receipts":{"items":{"type":"string"},"type":"array"},"requisite_type":{"$ref":"#/components/schemas/requisite.Type"},"reverse_callback_url":{"type":"string"},"status":{"$ref":"#/components/schemas/order.Status"},"sub_merchant_id":{"type":"string"},"uuid":{"type":"string"}},"type":"object"},"currency.Currency":{"enum":["USDT","RUB","AZN","KGS","KZT","TJS","UZS","ARS","TRY","GEL","XOF","KES","XAF","VND","CNY","MNT","LAK","IDR","PHP","BRL"],"type":"string"},"requisite.Type":{"enum":["SBP","card","accountNumber","internalTransfer","internalTransferMobile","phoneTopUp","QR","internalTransferAccountNumber","mobileMoney"],"type":"string"},"order.Status":{"enum":["pending","inProgress","inReview","cancellationRequested","traderNotFound","timeout","completed","canceled"],"type":"string"},"models.ErrorResponse":{"properties":{"error":{"type":"string"}},"type":"object"}}},"paths":{"/v1/payouts/merchant/{id}":{"get":{"description":"Retrieves payouts associated with a specific merchant order ID.","parameters":[{"description":"Merchant Order ID","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"schema":{"type":"string","default":"application/json"},"name":"Accept","in":"header","description":"Response format"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/v1.PayoutMerchantResponse"},"type":"array"}}}},"400":{"description":"invalid id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}},"summary":"Get payouts by merchant order ID","tags":["Payouts"]}}}}
```

## Get payout by ID

> Retrieves a payout by its UUID

```json
{"openapi":"3.1.1","info":{"title":"Panda Pay API","version":"1.0"},"servers":[{"url":"https://api.paymentgateway24.com"}],"security":[{"ApiKey":[]},{"Signature":[]},{"Timestamp":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","name":"X-API-Key","in":"header","description":"Merchant API key"},"Signature":{"type":"apiKey","name":"X-Signature","in":"header","description":"HMAC-SHA256 signature of timestamp + request body (or timestamp only for GET)"},"Timestamp":{"type":"apiKey","name":"X-Timestamp","in":"header","description":"Current Unix timestamp (UTC)"}},"schemas":{"v1.PayoutMerchantResponse":{"properties":{"amount":{"type":"string"},"amount_usdt":{"type":"string"},"bank_code":{"type":"string"},"created_at":{"type":"string"},"currency":{"$ref":"#/components/schemas/currency.Currency"},"customer_name":{"type":"string"},"customer_requisite":{"type":"string"},"customer_requisite_card":{"type":"string"},"exchange_rate":{"type":"string"},"expires_at":{"type":"string"},"merchant_commission":{"type":"string"},"merchant_id":{"type":"string"},"merchant_order_id":{"type":"string"},"payment_redirect_url":{"type":"string"},"receipt":{"type":"string"},"receipts":{"items":{"type":"string"},"type":"array"},"requisite_type":{"$ref":"#/components/schemas/requisite.Type"},"reverse_callback_url":{"type":"string"},"status":{"$ref":"#/components/schemas/order.Status"},"sub_merchant_id":{"type":"string"},"uuid":{"type":"string"}},"type":"object"},"currency.Currency":{"enum":["USDT","RUB","AZN","KGS","KZT","TJS","UZS","ARS","TRY","GEL","XOF","KES","XAF","VND","CNY","MNT","LAK","IDR","PHP","BRL"],"type":"string"},"requisite.Type":{"enum":["SBP","card","accountNumber","internalTransfer","internalTransferMobile","phoneTopUp","QR","internalTransferAccountNumber","mobileMoney"],"type":"string"},"order.Status":{"enum":["pending","inProgress","inReview","cancellationRequested","traderNotFound","timeout","completed","canceled"],"type":"string"},"models.ErrorResponse":{"properties":{"error":{"type":"string"}},"type":"object"}}},"paths":{"/v1/payouts/{id}":{"get":{"description":"Retrieves a payout by its UUID","parameters":[{"description":"Payout UUID","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"schema":{"type":"string","default":"application/json"},"name":"Accept","in":"header","description":"Response format"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1.PayoutMerchantResponse"}}}},"400":{"description":"invalid id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"404":{"description":"order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}},"summary":"Get payout by ID","tags":["Payouts"]}}}}
```

## Cancel payout

> Cancels an active payout. Merchants can cancel 'pending' payouts or request cancellation for 'inProgress' payouts. Admins can cancel both 'pending' and 'inProgress' payouts immediately. Cascade payouts that cannot be cancelled remotely return 400.

```json
{"openapi":"3.1.1","info":{"title":"Panda Pay API","version":"1.0"},"servers":[{"url":"https://api.paymentgateway24.com"}],"security":[{"ApiKey":[]},{"Signature":[]},{"Timestamp":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","name":"X-API-Key","in":"header","description":"Merchant API key"},"Signature":{"type":"apiKey","name":"X-Signature","in":"header","description":"HMAC-SHA256 signature of timestamp + request body (or timestamp only for GET)"},"Timestamp":{"type":"apiKey","name":"X-Timestamp","in":"header","description":"Current Unix timestamp (UTC)"}},"schemas":{"v1.CancelPayoutResponse":{"properties":{"status":{"type":"string"},"uuid":{"type":"string"}},"type":"object"},"models.ErrorResponse":{"properties":{"error":{"type":"string"}},"type":"object"}}},"paths":{"/v1/payouts/{id}/cancel":{"post":{"description":"Cancels an active payout. Merchants can cancel 'pending' payouts or request cancellation for 'inProgress' payouts. Admins can cancel both 'pending' and 'inProgress' payouts immediately. Cascade payouts that cannot be cancelled remotely return 400.","parameters":[{"description":"Payout UUID","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"schema":{"type":"string","default":"application/json"},"name":"Accept","in":"header","description":"Response format"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1.CancelPayoutResponse"}}}},"400":{"description":"invalid id, invalid order status, or cancel is not supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"403":{"description":"role not authorized to cancel payouts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"404":{"description":"order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}},"summary":"Cancel payout","tags":["Payouts"]}}}}
```