Card Payout API

API Endpoint

Live APIProduction environment

POSThttps://api.thepayment.company/api/v1/live/payout

Test APISandbox environment

POSThttps://api.thepayment.company/api/v1/test/payout

Request Fields

Parameter	Type	Description	Required
`wallet_id`	String	User wallet ID	Yes
`first_name`	String	Cardholder first name	Yes
`last_name`	String	Cardholder last name	Yes
`email`	String	Customer email address	Yes
`address`	String	Billing street address	Yes
`country`	String	Country code in ISO 3166-1 alpha-3 format	Yes
`city`	String	Cardholder city	Yes
`state`	String	Cardholder state or region	Yes
`zip`	String	ZIP or postal code	Yes
`ip_address`	String	Customer IP address	Yes
`phone_number`	String	Cardholder phone number	Yes
`amount`	Number	Payout amount in the smallest currency unit	Yes
`currency`	String	Currency code in ISO 4217 format	Yes
`card_number`	String	Credit or debit card number	Yes
`card_expiry_month`	String	Card expiry month in `MM` format	Yes
`card_expiry_year`	String	Card expiry year in `YYYY` format	Yes
`webhook_url`	String	URL used for server-to-server webhook updates	NO
`order_id`	String	Merchant-side unique order reference	NO
`terminal_id`	String	Unique connector terminal ID, useful when choosing a primary or fallback connector	NO

Payload

Send the request payload as JSON. The sample structure is shown below:

{
"wallet_id": "WAL7825818519632620",
"first_name": "James",
"last_name": "Dean",
"email": "james@gmail.com",
"address": "64 Hertingfordbury Rd",
"country": "US",
"city": "Newport",
"state": "US",
"zip": "TF10 8DF",
"ip_address": "127.0.0.1",
"phone_number": "7654233212",
"amount": 100,
"currency": "USD",
"card_number": "4111111111111111",
"card_expiry_month": "12",
"card_expiry_year": "2027",
"webhook_url": "https://thepayment.company/webhook",
"order_id": "12524AGSDF34DS"
}

For sandbox payout testing, use the successful and failed card numbers listed in Testing Cards under the Payout Test Cards section.

Sample Responses

{
"status": "SUCCESS",
"message": "Transaction processed successfully!.",
"data": {
  "amount": 100,
  "currency": "USD",
  "order_id": null,
  "transaction_id": "TPC0186280974141637",
  "customer": {
    "first_name": "James",
    "last_name": "Dean",
    "email": "james@gmail.com"
  }
}
}

If additional verification is required:

{
"status": "PENDING",
"message": "Additional verification required",
"redirect_url": "https://api.thepayment.company/api/v1/test/payout/verification/TPC0186280974141637",
"data": {}
}

Handling Redirect URLs

In some cases, the API response may include a redirect_url field. This happens when additional information or verification is required to complete the payout transaction. When this field is present, your application should redirect the user to that URL so the required data can be provided.

This is uncommon and usually occurs when the payment processor requires additional verification for specific transactions or regions.

Integration Notes

Encrypted payment APIs must use AES-256-CBC before transmitting sensitive fields. Authentication, headers, encryption steps, and sample implementations for Node.js, PHP, Python, and Java are documented in Integration Examples.