Skip to main content
POST
/
payouts
Create Payout
curl --request POST \
  --url https://access.utgl.io/v1/payouts \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "source": {
    "firstName": "<string>",
    "surname": "<string>",
    "nationality": "Hong Kong",
    "address": "<string>",
    "idType": "national-id",
    "idNumber": "<string>",
    "dateOfBirth": "1999-09-09",
    "mobileNumber": "+85212345678"
  },
  "destination": {
    "accountNumber": 6225888888888888,
    "firstName": "DAWEN",
    "firstNameCN": "大文",
    "surname": "CHEN",
    "surnameCN": "陈",
    "address": "上海市黄浦区南京东路333号202室"
  },
  "quoteId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "purpose": "self-use",
  "sourceOfFunds": "income",
  "accountId": "6a3176fe-7715-4fe0-a548-034912d7f800",
  "method": "BANK_SWIFT",
  "remarks": "<string>",
  "idempotencyKey": "xeev1she5eegh9daiviethahchoo1muW",
  "xid": "<string>",
  "xmetadata": {
    "key1": "value1",
    "key2": [
      "value2.1",
      "value2.2"
    ]
  }
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "xid": "<string>",
  "xmetadata": {
    "key1": "value1",
    "key2": [
      "value2.1",
      "value2.2"
    ]
  },
  "created": "2023-11-07T05:31:56Z",
  "method": "BANK_SWIFT",
  "destination": {
    "type": "BANK_ACCOUNT",
    "accountNumber": 123456,
    "routingNumber": 1234,
    "country": "US",
    "bankName": "Bank of America",
    "bankAddress": "123 Main St, New York, NY 10001, USA",
    "swiftCode": "BOFAUS3N",
    "accountHolderName": "John Doe",
    "accountHolderAddress": "456 Park Ave, New York, NY 10022, USA"
  },
  "accountId": "6a3176fe-7715-4fe0-a548-034912d7f800",
  "sourceCurrency": "<string>",
  "sourceAmount": 123,
  "destinationCurrency": "RMB",
  "destinationAmount": 123,
  "rate": 123,
  "updated": "2023-11-07T05:31:56Z",
  "status": "requested",
  "subStatus": "ORDER_UNDER_AML_REVIEW",
  "cancellationReason": "<string>"
}

Authorizations

​
Authorization
string
header
required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Body

application/json
​
source
object
required

Required for UNIONPAY and ALIPAY methods only

​
destination
UnionPay Card Account · object
required

Payout destination

​
quoteId
string<uuid>
required

Quote ID

​
purpose
enum<string>
required

The purpose of the payout. Possible values are

  • self-use
  • household
  • personal-savings
  • family-living-expenses
Available options:
self-use,
buy-goods,
spending,
household,
payroll,
personal-savings,
family-living-expenses,
company-expense
​
sourceOfFunds
enum<string>
required

The fund source of this payout

  • income
  • household
  • friends-loan
  • company-fund
  • personal-investment
  • personal-savings
  • wages
Available options:
income,
household,
friends-loan,
company-fund,
personal-investment,
personal-savings,
wages
​
accountId
string<uuid>
required

Account id to payout from

Example:

"6a3176fe-7715-4fe0-a548-034912d7f800"

​
method
enum<string>
Available options:
BANK_SWIFT,
UNIONPAY,
ALIPAY,
BANK_TRANSFER
​
remarks
string

The remarks of the payout

​
idempotencyKey
string<string>

Unique idempotency key for ensuring exactly-once execution of mutating requests.

Example:

"xeev1she5eegh9daiviethahchoo1muW"

​
xid
string

External identifier, unique across all resources created under this account.

​
xmetadata
object

External metadata

Example:
{
  "key1": "value1",
  "key2": ["value2.1", "value2.2"]
}

Response

Payout Requested

​
id
string<uuid>

ID of resource

​
xid
string

External identifier, unique across all resources created under this account.

​
xmetadata
object

External metadata

Example:
{
  "key1": "value1",
  "key2": ["value2.1", "value2.2"]
}
​
created
string<date-time>
​
method
enum<string>

Payout method

Available options:
BANK_SWIFT,
UNIONPAY
​
destination
Bank Account (SWIFT) · object
​
accountId
string<uuid>

Account id to fund the payout from

Example:

"6a3176fe-7715-4fe0-a548-034912d7f800"

​
sourceCurrency
string

Currency to send

​
sourceAmount
number

Amount to send

​
destinationCurrency
string

Receive currency

Example:

"RMB"

​
destinationAmount
number

Receive amount

​
rate
number

Exchange rate

​
updated
string<date-time>
​
status
enum<string>

Overall status of the payout:

  • requested: Payout has been requested but not yet processing
  • processing: Payout is being processed (may include AML review)
  • completed: Payout has been successfully completed
  • failed: Payout failed to process
  • cancelled: Payout was cancelled
Available options:
requested,
processing,
completed,
failed,
cancelled
​
subStatus
string | null

Detailed sub-status providing additional context about the payout state.

Important Sub-Statuses:

  • ORDER_UNDER_AML_REVIEW: The payout is under Anti-Money Laundering (AML) compliance review. When in this state:
    • The payout cannot be cancelled by users or API calls
    • The transaction is held pending manual compliance review
    • Status will remain processing until review is complete
    • After review, it will move to completed or cancelled by the payment gateway

Other sub-statuses may exist for different processing stages.

Example:

"ORDER_UNDER_AML_REVIEW"

​
cancellationReason
string

Reason for cancellation (only present when status is cancelled)