Skip to main content
POST
/
payment
/
payout
curl -X POST "https://api.orsunpay.com/v1/payment/payout" \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "USD",
    "paymentMethod": "bank_transfer_001",
    "merchantId": "mr_clyv2goxb0000z8b8j5y6fl1j",
    "orderId": "payout_123",
    "buyerId": "customer_123",
    "successUrl": "https://example.com/success",
    "failureUrl": "https://example.com/failure",
    "returnUrl": "https://example.com/return",
    "callbackUrl": "https://example.com/callback",
    "customer": {
      "email": "[email protected]",
      "firstName": "John",
      "lastName": "Doe"
    }
  }'

{
  "status": true,
  "transaction": {
    "id": "tx_payout_001",
    "orderId": "payout_123",
    "status": "PROCESSING",
    "action": "PAYOUT",
    "amount": 5000,
    "currency": "USD",
    "createdAt": "2023-12-25T10:00:00.000Z"
  }
}

​
Overview

The withdrawal endpoint creates a new transaction for withdrawing funds to customers. It supports multiple payout methods including bank transfers, e-wallets, and cryptocurrencies. 
curl -X POST "https://api.orsunpay.com/v1/payment/payout" \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "USD",
    "paymentMethod": "bank_transfer_001",
    "merchantId": "mr_clyv2goxb0000z8b8j5y6fl1j",
    "orderId": "payout_123",
    "buyerId": "customer_123",
    "successUrl": "https://example.com/success",
    "failureUrl": "https://example.com/failure",
    "returnUrl": "https://example.com/return",
    "callbackUrl": "https://example.com/callback",
    "customer": {
      "email": "[email protected]",
      "firstName": "John",
      "lastName": "Doe"
    }
  }'

{
  "status": true,
  "transaction": {
    "id": "tx_payout_001",
    "orderId": "payout_123",
    "status": "PROCESSING",
    "action": "PAYOUT",
    "amount": 5000,
    "currency": "USD",
    "createdAt": "2023-12-25T10:00:00.000Z"
  }
}

​
Withdrawal Flow

  1. Verify Balance - Ensure customer has sufficient funds
  2. Create Withdrawal - Call this endpoint to initiate a payout
  3. Additional Verification - Some methods may require additional customer verification
  4. Processing - Withdrawal is processed by the payment provider
  5. Completion - Funds are transferred to customer’s account
  6. Webhook Notification - Receive status updates via webhook

​
Processing Times

MethodTypical Processing Time
Bank Transfer1-3 business days
E-walletsMinutes to hours
Cryptocurrency10-60 minutes
International Wire3-5 business days
Withdrawal processing times may vary based on the payment provider, destination country, and verification requirements.

​
Common Use Cases

​
Standard Bank Withdrawal

Most common withdrawal method with standard processing times and KYC requirements.

​
Cryptocurrency Payout

Fast withdrawals for crypto-enabled customers with wallet address verification.

​
E-wallet Transfer

Quick transfers to digital wallets like PayPal, Skrill, or Neteller.

​
Important Considerations

​
KYC Requirements

  • Customer identity verification may be required
  • Higher amounts typically require additional documentation
  • Some jurisdictions have specific compliance requirements

​
Daily Limits

  • Withdrawal limits may apply per customer
  • Limits can be increased with enhanced verification
  • Business accounts may have higher limits

​
Anti-Money Laundering (AML)

  • Large transactions may require additional screening
  • Suspicious activity may trigger manual review
  • Source of funds verification may be required
Always implement webhook handling for accurate withdrawal status tracking, as processing times can vary significantly.
Ensure your webhook endpoint can handle duplicate notifications and implement proper idempotency checks for withdrawal processing.

Authorizations

​
x-api-key
string
header
required

API key for merchant authorization

Body

application/json

Withdrawal transaction details

​
amount
integer
required

Withdrawal amount in cents

Required range: x >= 1
Example:

5000

​
currency
string
required

Three-letter currency code (ISO 4217)

Example:

"USD"

​
paymentMethod
string
required

Payout method identifier

Example:

"bank_transfer_001"

​
merchantId
string
required

Merchant account identifier

Example:

"mr_clyv2goxb0000z8b8j5y6fl1j"

​
orderId
string
required

Unique withdrawal identifier in your system

Example:

"payout_123"

​
buyerId
string
required

Customer identifier in your system

Example:

"customer_123"

​
successUrl
string<uri>
required

URL to redirect customer after successful withdrawal initiation

Example:

"https://example.com/success"

​
failureUrl
string<uri>
required

URL to redirect customer after failed withdrawal

Example:

"https://example.com/failure"

​
returnUrl
string<uri>
required

URL to redirect customer when returning to your site

Example:

"https://example.com/return"

​
callbackUrl
string<uri>
required

Webhook URL for withdrawal status notifications

Example:

"https://example.com/callback"

​
customer
object
required
​
locale
string

Language/locale in BCP 47 format

Example:

"en-US"

​
paymentMethodInput
object

Additional payout method specific parameters

​
metadata
object

Additional metadata for the withdrawal

Response

Withdrawal transaction successfully created

​
status
boolean
required

Indicates if the request was successful

Example:

true

​
url
string<uri>

Redirect URL for payment completion (if required)

Example:

"https://payment-provider.com/pay/abc123"

​
transaction
object
​
error
string

Error message if the request failed

Example:

"Payment method not available"