Making payments to recipient bank accounts

Overview

This flow sends funds from a selected Payoneer balance to a recipient bank account that is already registered for the user (or your program). You initiate the payment with the same payments/send pattern as other outbound sends, surface fees for confirmation, then commit with PUT using the returned commit_id. If Payoneer requires step-up authentication, the commit step may return challenge_required until the user completes MFA.

Prerequisite: eligibility

Before integrating, call the eligibility endpoint to confirm the user may send payments to bank accounts and to obtain the minimum and maximum amounts permitted for each balance.

Call GET /v4/accounts/{account_id}/eligibility/pay_to_bank_account with the user's bearer token in the Authorization header and account_id in the path (both obtained during the user consent process). See the API reference guide for the full request and response for your program.

curl -X GET \
https://api.sandbox.payoneer.com/v4/accounts/{account_id}/eligibility/pay_to_bank_account \
-H "Authorization: Bearer MXVNd2NTcTBlTi94NkZC…" \
-H 'content-type: application/json'

Sample eligibility response:

{
  "result": {
    "status": 2,
    "status_description": "eligible",
    "currencies": {
      "items": [
        {
          "currency": "EUR",
          "monthly_available": 9211.1668,
          "monthly_limit": 9328,
          "monthly_used": 116.8332,
          "payout_methods": {
            "items": [
              {
                "id": "4366181923745837",
                "type": "BALANCE",
                "display_name": "EUR balance",
                "bank_accounts": {
                  "items": [
                    {
                      "type": "bank_id",
                      "id": "4366181924256924",
                      "display_name": "Cathay United Bank (4523)",
                      "currency": "THB",
                      "country": "TH",
                      "min_amount": 45,
                      "max_amount": 2500,
                      "status": 1,
                      "bank_account_holder_name": "Jon Doe"
                    }
                  ]
                }
              }
            ]
          }
        },
        {
          "currency": "GBP",
          "monthly_available": 7906.2185875,
          "monthly_limit": 8006.5,
          "monthly_used": 100.2814125,
          "payout_methods": {
            "items": [
              {
                "id": "4366181923745838",
                "type": "BALANCE",
                "display_name": "GBP balance",
                "bank_accounts": {
                  "items": [
                    {
                      "type": "bank_id",
                      "id": "4366181924256924",
                      "display_name": "Cathay United Bank (4523)",
                      "currency": "THB",
                      "country": "TH",
                      "min_amount": 35,
                      "max_amount": 2500,
                      "status": 1,
                      "bank_account_holder_name": "Jon Doe"
                    }
                  ]
                }
              }
            ]
          }
        },
        {
          "currency": "USD",
          "monthly_available": 9874.75,
          "monthly_limit": 10000,
          "monthly_used": 125.25,
          "payout_methods": {
            "items": [
              {
                "id": "4366181923745839",
                "type": "BALANCE",
                "display_name": "USD balance",
                "bank_accounts": {
                  "items": [
                    {
                      "type": "bank_id",
                      "id": "4366181924256924",
                      "display_name": "Cathay United Bank (4523)",
                      "currency": "THB",
                      "country": "TH",
                      "min_amount": 5,
                      "max_amount": 1000,
                      "status": 1,
                      "bank_account_holder_name": "Jon Doe"
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  }
}

Confirm status_description is eligible and validate the amount against the per-currency min_amount and max_amount before sending.

Implementation steps

a. Present balances and select balance

On your platform, show the balances in the user's Payoneer account and let the user choose which balance funds the bank payout.

Example dashboard with currency balance cards
Example: surfacing per-currency balances so the user can pick which balance funds the payment.

b. Send payment (POST payments/send)

Call POST /v4/accounts/{account_id}/balances/{balance_id}/payments/send with the destination bank account in the to object. The id is the Payoneer identifier for the saved bank account (created via your onboarding or bank-account APIs as documented). Confirm field names and any required compliance fields in the API reference. Example (sandbox):

curl -X POST \
https://api.sandbox.payoneer.com/v4/accounts/{account_id}/balances/{balance_id}/payments/send \
-H 'content-type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer MXVNd2NTcTBlTi94NkZC…' \
-d '{
    "client_reference_id":"bankpay-88421",
    "amount": 350.00,
    "description":"Supplier invoice — bank transfer",
    "to":{
        "type":"bank_account",
        "id":"4366181893586952"
    }
}'

The API reference describes this operation under the pay-to-bank-account flow (for example pay_to_bank_account in request metadata).

API response (send)

Example response body after a successful send request (includes commit_id for the next step):

{
  "result": {
    "commit_id": "ec361a50-271a-7ae8-7453-be933a357d4a",
    "expires_at": "2021-01-20T07:57:55.7459944Z",
    "type": "send",
    "client_reference_id": "bankpay-88421",
    "request_details": {
      "url": "/accounts/2982743/balances/4366181893586952/payments/send",
      "body": {
        "client_reference_id": "bankpay-88421",
        "amount": 350,
        "description": "Supplier invoice — bank transfer",
        "to": {
          "type": "bank_account",
          "id": "4366181893586952"
        }
      }
    },
    "from": {
      "type": "balance",
      "id": "4366181893586952"
    },
    "to": {
      "type": "bank_account",
      "id": "4366181893586952"
    },
    "amounts": {
      "charged": {
        "amount": 350,
        "currency": "USD"
      },
      "target": {
        "amount": 350,
        "currency": "USD"
      }
    }
  }
}

Users must confirm agreement to charging their Payoneer balance. Present the transaction details and fees returned from the payments/send response and ask the customer to confirm before you commit.

Make a Payment confirmation with recipient and payment details
Example: confirmation screen before the user confirms charges and fees.

d. Commit the payment

After the user reviews and confirms fees and charges, call PUT to commit the payment 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 (e.g. MFA), 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": "2026-01-14T15:14:59.544Z",
        "challenge_reference": "1e786e90701f4d90b6fbd69a64cea43f",
        "session_id": "e57e9b2e-c3fb-487f-aa79-d9cd43a34cfa",
        "url": "https://auth.payoneer.com/#?t=e57e9b2e-c3fb-487f-aa79-d9cd43a34cfa&challenge_reference=1e786e90701f4d90b6fbd69a64cea43f&v=a"
    }
}
Sequence diagram for MFA challenge between user, platform, and Payoneer
High-level flow: redirect the user to the challenge url, then retry commit after authentication.

Straight success response (commit)

When the commit succeeds without a pending challenge, the response can look like the following (example):

{
    "result": {
        "payment_id": "1665404354",
        "status": 1,
        "status_description": "in_progress",
        "last_status": "2025-10-13T13:37:26.15Z",
        "created_at": "2025-10-13T13:37:26.0741182Z",
        "type": "send",
        "client_reference_id": "bankpay-88421",
        "request_details": {
            "url": "/accounts/9087002/balances/4366181923439479/payments/pay_to_bank_account",
            "body": {
                "client_reference_id": "bankpay-88421",
                "amount": 350,
                "description": "Supplier invoice — bank transfer",
                "to": {
                    "type": "bank_account",
                    "id": "4366181923439479"
                }
            }
        },
        "from": {
            "type": "balance",
            "id": "4366181923439479"
        },
        "to": {
            "type": "bank_account",
            "id": "4366181923439479"
        },
        "amounts": {
            "charged": {
                "amount": 350,
                "currency": "USD"
            },
            "target": {
                "amount": 350,
                "currency": "USD"
            }
        }
    }
}