Create payout

POST

https://api.staging.vrtx.sa/payouts/

Last modified:2025-12-03 10:51:05

Processes a Merchant-to-Peer payout from a business payout account to an individual's vrtx wallet.

Required headers:

idempotency-key: Unique key to guarantee idempotent payout execution

Request body must include payoutAmount (positive numeric string, up to 2 decimals) and exactly one receiver identifier (customerId, walletAccountNumber, or mobileNumber).

Successful responses return transactionId, payoutId, status, and createdAt metadata to track processing.

Error responses align with payout business rules including limit validations, balance checks, and account states.

Request

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢200OK

application/json

Default Response

Body

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

🟠404Not Found

🟠405Method Not Allowed

🟠409Conflict

🟠410Gone

🟠422Unprocessable Entity

🟠429Too Many Requests

🔴500Internal Server Error

🔴501Not Implemented

🔴503Service Unavailable

🔴504Gateway Timeout

🔴505HTTP Version Not Supported

Request Example

Shell

JavaScript

Java

Swift

cURL

example1example2example3

curl --location --request POST 'https://api.staging.vrtx.sa/payouts/' \
--header 'idempotency-key;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "payout_amount": "250.00",
    "payout_purpose": "Salary payment for November 2024",
    "external_reference": "PAY-2024-001234",
    "customer_id": "CUST-5a8f9c2e-b3d4-4a1f-9e7c-8d6f5a4b3c2d"
}'

Response Example

200 - example1

{
    "transaction_id": "TXN-2024-11-19-A1B2C3D4",
    "payout_id": "7c5a3d04-3c0e-4fd4-9c5d-4b4f5d6f98b2",
    "status": "PENDING",
    "created_at": "2024-11-19T10:30:00.000Z"
}

Modified at 2025-12-03 10:51:05

Payouts

Get payout status