Payout V2 Integration Guide

Prerequisites 📋

Recommended Integration Flow ⚙️

1. Obtain an access token.
2. Query the supported payee options.
3. Create a payee and save the payeeId.
4. Upload payout materials or source-of-funds proof and save the fileId.
5. Query available payout balances and save the balanceId.
6. Call POST /open-api/v2/payout/create.
7. If PARTY_FIELDS_REQUIRED is returned, retry with the same callId and the collected partyFields.
8. If PAYOUT_CREATED is returned, save the payoutTrxId and idNo.
9. Track the final status through the payout detail endpoint or webhooks.

Shared V1 Endpoints (Pre-Payout Preparation) 🔍

Query Payee Options

GET /open-api/v1/payout/payee-options

Call the Get payee options endpoint to retrieve the supported bank countries and currencies.

Create Payee

POST /open-api/v1/payout/payee

Call the Create payee endpoint to register the target account. After a successful creation, save the returned payeeId.

The dgp-entity-id header is optional for this endpoint. Pass it when the payee should be attached to a specific entity.

Routing parameter rules: ACH / WIRE require bankCode and accountNumber; SWIFT requires bicSwift, and providing both bankAddress and payeeAddress is recommended.

{
  "currency": "USD",
  "country": "US",
  "firstName": "John",
  "lastName": "Doe",
  "accountNumber": "31139750168449",
  "bankName": "JP Morgan Chase NA",
  "bankCode": "028000024",
  "bicSwift": "CHASUS33",
  "payeeAddress": {
    "line1": "123 Business Rd",
    "postCode": "10001",
    "city": "New York",
    "state": "NY",
    "country": "US"
  },
  "bankAddress": {
    "line1": "270 Park Avenue",
    "postCode": "10017",
    "city": "New York",
    "state": "NY",
    "country": "US"
  },
  "label": "Supplier Q3"
}

Upload Payout Materials and Source-of-Funds Proof

POST /open-api/v1/file/upload (multipart/form-data)

Call the Upload File endpoint to upload the materials. After a successful upload, save the returned fileId.

The dgp-entity-id header is optional for this endpoint.

Response example:

{
  "data": {
    "fileId": "example_file_uuid"
  }
}

Payout proof file IDs are passed in paymentMaterial; for individual accounts, source-of-funds proof file IDs are passed in sourceOfFundsMaterial and uploaded with fileUseType=source_of_funds.

Query Available Payout Balances

GET /open-api/v1/payout/accounts

Call the Query payout accounts endpoint. The dgp-entity-id header is required.

Create Payout Endpoint 🔗

Create Payout (V2)

POST /open-api/v2/payout/create

Only one of paymentAmount and payeeAmount can be provided. The payment currency and payee currency may differ; the system automatically obtains a quote for cross-currency payouts.

Payout Product Codes channelCode 📦

Cost Borne 🧾

Source of Funds for Individual Accounts 💰

Individual accounts must provide both sourceOfFunds and sourceOfFundsMaterial; business accounts may provide them optionally.

Response Handling 🚀

Scenario A: Party Fields Required

When data.status = PARTY_FIELDS_REQUIRED, the payout order has not been created, no funds have been debited, and the callId has not been consumed. Render the form based on the returned fields[], collect the missing values, and retry with the same callId.

{
  "code": 0,
  "data": {
    "status": "PARTY_FIELDS_REQUIRED",
    "fields": [
      {
        "key": "receiver_mobile",
        "label": "Payee mobile",
        "type": "text",
        "required": true,
        "order": 1
      },
      {
        "key": "sender_beneficiary_relationship",
        "label": "Relationship to payee",
        "type": "select",
        "required": true,
        "order": 2,
        "options": [
          { "label": "Family", "value": "01" },
          { "label": "Friend", "value": "02" }
        ]
      }
    ]
  }
}

Scenario B: Payout Created

{
  "code": 0,
  "data": {
    "status": "PAYOUT_CREATED",
    "payoutTrxId": "example_payout_trx_id",
    "idNo": "PO202610130001",
    "quoteId": "example_fx_quote_id",
    "fee": 15.00,
    "feeCurrency": "USD"
  }
}

Query and Async Notifications 🔔

The dgp-entity-id header is required when querying payout details. For fiat VA payout events, refer to VA Transaction Events. For crypto wallet payout events, refer to Crypto Wallet Transaction Events.

Webhooks use HMAC signature verification. Delivery retry intervals are 0s, 10s, 30s, 60s, 2min, 5min, and 10min, up to 7 attempts. The receiver must return 2xx within 30 seconds, and processing must be idempotent.

For crypto wallet payouts, the webhook data.id is the crypto transaction ID, which differs from payoutTrxId. Use callId or payout/detail for reconciliation.

Idempotency and Concurrency 🛡️

Integration Examples 🧪

Create Payout (Pave / offline)

{
  "callId": "merchant-payout-demo-001",
  "payeeId": "<payee-uuid>",
  "receiveType": "SWIFT",
  "channelCode": "va_012_01",
  "balanceId": "<va_group-or-cw-balance-uuid>",
  "paymentAmount": 100,
  "paymentCurrency": "USD",
  "payeeCurrency": "USD",
  "purpose": "13",
  "paymentMaterial": ["<attachment-uuid>"],
  "costBorne": "OUR",
  "reason": "invoice 12345"
}

Create Payout (QPay; party fields may be provided after the first response)

{
  "callId": "merchant-payout-demo-002",
  "payeeId": "<payee-uuid>",
  "receiveType": "SWIFT",
  "channelCode": "va_015_01",
  "balanceId": "<balance-uuid>",
  "payeeAmount": 100,
  "paymentCurrency": "USD",
  "payeeCurrency": "USD",
  "purpose": "13",
  "paymentMaterial": ["<attachment-uuid>"],
  "partyFields": {
    "receiver_bank_address": "1 Example Street, City"
  }
}

receiveType 📱

Integration Notes 🧭

• Complete end-to-end integration testing in the sandbox environment first.
• Save payoutTrxId; CW orders cannot use vaTrxId to query details.
• Use both webhooks and payout/detail as a double check for the final status.
• Pass amounts with the correct decimal precision for the currency.
• Upload materials first to obtain fileId, then pass them to the create payout endpoint.
• Mask and redact secrets, tokens, and account information in logs.
• Follow the per-endpoint dgp-entity-id requirements: it is required for Create Payout, Query Accounts, and Query Payout Detail; optional for Create/Update Payee and File Upload.
• If a channel combination or product code cannot be determined, compare it with the Web payout route or contact the account manager.

Core Constraints and Rules 🛡️