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

example1example2example3

{
    "payout_amount": "250.00",
    "payout_purpose": "Salary payment for November 2024",
    "external_reference": "PAY-2024-001234",
    "customer_id": "CUST-5a8f9c2e-b3d4-4a1f-9e7c-8d6f5a4b3c2d"
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

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"
}'

Responses

🟢200OK

application/json

Default Response

Body

Examples

example1example2

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

🟠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

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

Get payout status