Create payout

POST

/payouts/

Last modified:2025-12-02 10:06:51

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

🟢200Success

application/json

Default Response

Body

🟠400400

🟠401401

🟠403403

🟠404404

🟠405405

🟠409409

🟠410410

🟠422422

🟠429429

🔴500500

🔴501501

🔴503503

🔴504504

🔴505505

Request Example

Shell

JavaScript

Java

Swift

cURL

example1example2example3

curl --location --request POST '/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-02 10:06:51

List wallet transactions

Get payout status