Payout Integration Guide
UniPayment provides a flexible Payout API that allows merchants to programmatically send funds to external beneficiaries (bank accounts, crypto wallets) or internal UniPayment accounts.
This guide explains the complete integration flow, including account setup, beneficiary creation, payment method configuration, and payout execution.
Overview
To successfully create a payout, you will need:
from_account_id — The source wallet account ID (retrieved from Get Accounts)
payment_method_id — The beneficiary’s payout method ID (retrieved from Create Payment Method)
The high-level payout process:
Retrieve your wallet accounts
Create a Beneficiary
Create a Payment Method for that beneficiary
Create a Payment (Payout)
Step 1 — Get Accounts
Retrieve available wallet accounts and select the account you want to send funds from.
✅ Before creating a payout:
Ensure
asset_typematches the payout currencyEnsure sufficient
availablebalance
Step 2 — Create Beneficiary
Create a beneficiary (recipient). The beneficiary can be an individual or a corporate entity.
The response will return a beneficiary_id.
You will use this ID to create a payment method.
Step 3 — Create Payment Method
Create a payout method for the beneficiary.
Supported transfer methods:
BANKCRYPTOINTERNAL
Step 4 — Create Payment (Payout)
Use the from_account_id together with either payment_method_id or to_account_id depending on the transfer type.
Transfer Method Requirements
When creating a payment, the required destination parameter depends on the transfer_method:
Transfer Method | Required Parameter | Description |
|
| Required. Must reference a BANK payment method created for a beneficiary. |
|
| Required. Must reference a CRYPTO payment method created for a beneficiary. |
|
| Required. Must reference another UniPayment internal account. |
⚠ You must provide either payment_method_id OR to_account_id, depending on the transfer type.
Internal Transfer Rules & Limitations
Internal transfers are not universally allowed between all accounts.
There are specific rules based on:
Account type (DEFAULT / SETTLEMENT / BANK / etc.)
Asset type (USD, EUR, USDT, BTC, etc.)
Regulatory and compliance restrictions
Platform configuration
Not all accounts support internal transfers with each other.
Important
If the API returns an error indicating the transfer cannot be processed, it means:
The asset type is not eligible for internal transfer between those accounts, OR
The account types are not permitted to transfer to each other, OR
The transfer configuration is not supported by the system.
In such cases, the internal transfer is not allowed by platform rules.
Payment Status Lifecycle
After creation, the payout moves through the following statuses:
Status | Description |
| Payment created and funds reserved |
| Payment confirmed |
| Approved and sent to banking/blockchain network |
| Successfully completed |
| Processing failed |
| Manually canceled |
Confirm or Cancel Payment (If Required)
Some workflows require explicit confirmation.
Confirm Payment
Cancel Payment
Webhook (IPN) Integration
To receive real-time updates, configure a webhook endpoint.
UniPayment will send status change notifications when:
Payment is confirmed
Payment is approved
Payment is completed
Payment fails
Recommended best practices:
Verify webhook signatures
Implement idempotent processing
Store and reconcile payment status locally