Withdraw funds to a bank account
Overview
This flow lets an accountholder withdraw funds from a Payoneer balance to a bank account registered for withdrawal. You retrieve withdrawal eligibility (including payout methods and bank_id values), balances, then submit POST payments/withdraw, obtain fee and FX details for the user to approve, and commit with PUT using commit_id. If Payoneer requires step-up authentication, commit may return challenge_required.
See the official section and API reference guide for field-level detail.
Implementation steps
a. Get withdrawal to bank eligibility
Call GET /v4/accounts/{account_id}/eligibility/withdraw to retrieve eligibility and payout methods. The response includes bank account entries with type bank_id and an id you use later as the withdrawal destination. See the API reference guide.
Requests to Payoneer's Services API require the user's bearer token in the Authorization header and account_id in the path. These credentials are obtained for the user during the user consent process.
curl -X GET \
https://api.sandbox.payoneer.com/v4/accounts/{account_id}/eligibility/withdraw \
-H "Authorization: Bearer MXVNd2NTcTBlTi94NkZC…" \
-H 'content-type: application/json'Sample Get withdrawal eligibility response:
{
"result": {
"status": 2,
"status_description": "eligible",
"currencies": {
"items": [
{
"currency": "USD",
"monthly_available": 200000,
"monthly_limit": 200000,
"monthly_used": 0,
"payout_methods": {
"items": [
{
"id": "4366181894204646",
"type": "BALANCE",
"display_name": "USD balance",
"bank_accounts": {
"items": [
{
"type": "bank_id",
"id": "4366181894204643",
"display_name": "Bank of America (3333)",
"currency": "USD",
"country": "US",
"min_amount": 300,
"max_amount": 5109.35,
"status": 1
},
{
"type": "bank_id",
"id": "4366181894204970",
"display_name": "中国工商银行 (3233)",
"currency": "CNY",
"country": "CN",
"min_amount": 0.1,
"max_amount": 5109.35,
"status": 1
}
]
}
}
]
}
},
{
"currency": "EUR",
"monthly_available": 185050,
"monthly_limit": 185050,
"monthly_used": 0,
"payout_methods": {
"items": [
{
"id": "4366181894204644",
"type": "BALANCE",
"display_name": "EUR balance",
"bank_accounts": {
"items": [
{
"type": "bank_id",
"id": "4366181894204643",
"display_name": "Bank of America (3333)",
"currency": "USD",
"country": "US",
"min_amount": 0.01,
"max_amount": 239.52,
"status": 1
},
{
"type": "bank_id",
"id": "4366181894204970",
"display_name": "中国工商银行 (3233)",
"currency": "CNY",
"country": "CN",
"min_amount": 0.01,
"max_amount": 239.52,
"status": 1
}
]
}
}
]
}
},
{
"currency": "GBP",
"monthly_available": 162120,
"monthly_limit": 162120,
"monthly_used": 0,
"payout_methods": {
"items": [
{
"id": "4366181894204645",
"type": "BALANCE",
"display_name": "GBP balance",
"bank_accounts": {
"items": [
{
"type": "bank_id",
"id": "4366181894204643",
"display_name": "Bank of America (3333)",
"currency": "USD",
"country": "US",
"min_amount": 0.01,
"max_amount": 0
},
{
"type": "bank_id",
"id": "4366181894204970",
"display_name": "中国工商银行 (3233)",
"currency": "CNY",
"country": "CN",
"min_amount": 0.01,
"max_amount": 0
}
]
}
}
]
}
}
]
}
}
}b. Get balances
Call GET /v4/accounts/{account_id}/balances to retrieve available balances and the corresponding balance IDs for the account.
curl -X GET \
https://api.sandbox.payoneer.com/v4/accounts/{account_id}/balances \
-H "Content-Type: application/json" \
-H "Authorization: Bearer MXVNd2NTcTBlTi94NkZC…"Example response:
{
"result": {
"items": [
{
"id": "4366181865108056",
"type": "BALANCE",
"currency": "GBP",
"status": "2",
"status_description": "Active",
"available_balance": "20.00",
"update_time": "2018-03-30T19:28:17Z"
}
],
"total": 3
}
}On your platform, present the balances held in the user's Payoneer account with an option to Withdraw funds.
c. Submit withdraw request (POST payments/withdraw)
When the user chooses to withdraw, call POST /v4/accounts/{account_id}/balances/{balance_id}/payments/withdraw using the bank_id returned from the eligibility response in to (type: bank_id).
curl -X POST \
https://api.sandbox.payoneer.com/v4/accounts/{account_id}/balances/{balance_id}/payments/withdraw \
-H 'content-type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer MXVNd2NTcTBlTi94NkZC…' \
-d '{
"client_reference_id": "withdraw12345",
"amount": 30.00,
"description": "some description of transaction",
"to": {
"type": "bank_id",
"id": "4366181894204341"
}
}'API response (example):
{
"result": {
"commit_id": "5a45c76b-687f-46e8-a3f6-1b1d9f6ca406",
"expires_at": "2020-01-01T09:44:26.4528872Z",
"type": "withdraw",
"client_reference_id": "withdraw12345",
"request_details": {
"url": "/accounts/2982743/balances/4366181893586952/payments/withdraw",
"body": {
"client_reference_id": "withdraw12345",
"amount": 30.0,
"description": "some description of transaction",
"target_amount": false,
"to": {
"type": "bank_id",
"id": "4366181894204341"
}
}
},
"from": {
"type": "balance",
"id": "4366181893586952"
},
"to": {
"type": "bank_id",
"id": "4366181894204341"
},
"fees": [
{
"type": "transfer_fee",
"amount": 3.0,
"currency": "USD",
"is_estimated": true
}
],
"fx": {
"quote": "5315227",
"rate": 27.9651851852,
"source_currency": "USD",
"target_currency": "THB",
"is_estimated": true
},
"amounts": {
"charged": {
"amount": 30.0,
"currency": "USD"
},
"target": {
"amount": 755.06,
"currency": "THB",
"is_estimated": true
}
}
}
}d. User confirmation
Users must confirm the withdrawal from a Payoneer balance. Present the transaction details and fees returned from the withdrawal request to the customer and request approval.
e. Commit the withdrawal
After the user reviews and confirms the fees and charges, a commit call is required to confirm the withdrawal to Payoneer.
curl -X PUT \
https://api.sandbox.payoneer.com/v4/accounts/{account_id}/payments/{commit_id} \
-H "Authorization: Bearer MXVNd2NTcTBlTi94NkZC…" \
-H 'content-type: application/json'Challenge required (403 Forbidden)
If the user must pass a challenge, the commit request may return 403 Forbidden with error set to challenge_required. Example body:
{
"error": "challenge_required",
"error_description": "Challenge authentication required. Please see 'challenge' in response for more details.",
"error_details": {
"code": 1803
},
"challenge": {
"type": "mfa",
"expires_at": "2022-03-16T20:12:41.323Z",
"session_id": "2d91b45a5cf440..0e4c42dafbc3737",
"url": "https://auth.payoneer.com/#?t=2d91b45a5cf440..0e4c42dafbc3737&v=a"
}
}
url, then retry commit after authentication.Straight success response (commit)
When the commit request completes without a pending challenge, the response can look like the following (example). status_description may be in_progress while Payoneer processes the withdrawal:
{
"result": {
"payment_id": "1661566656",
"status": 1,
"status_description": "in_progress",
"last_status": "2025-05-15T14:29:37.4946346Z",
"created_at": "2025-05-15T14:29:37.4946346Z",
"type": "withdraw",
"client_reference_id": "test122fs424",
"request_details": {
"url": "/accounts/3059338/balances/4366181894252923/payments/withdraw",
"body": {
"client_reference_id": "test122fs424",
"amount": 12.25,
"target_amount": false,
"description": "some description of transaction",
"to": {
"type": "bank_id",
"id": "4366181894252915"
}
}
},
"from": {
"type": "balance",
"id": "4366181894252923"
},
"to": {
"type": "bank_id",
"id": "4366181894252915"
},
"fx": {
"quote": "7240964",
"rate": 7.2081632653,
"source_currency": "USD",
"target_currency": "CNY",
"is_estimated": true
},
"amounts": {
"charged": {
"amount": 12.25,
"currency": "USD"
},
"target": {
"amount": 88.3,
"currency": "CNY",
"is_estimated": true
}
}
}
}