Submit mass payout

Overview

Once each payee is registered, they are eligible to receive payouts. Payoneer processes payments on request using funds you have deposited in advance. With the Mass Payout system, you can initiate up to 500 payouts in a single API call.

Before you start

Register your payees first — only registered payees can receive payouts. Then deposit sufficient funds with Payoneer to cover your requests; if there aren't enough funds, the payouts won't be processed.

Ways to submit a mass payout

There are two ways to submit a mass payout — pick the one that fits your workflow, or combine them. Both process each transfer asynchronously, so track status with the status APIs or webhooks in your program documentation.

Option 1 — Submit via API (automated)

Call the Submit Mass Payout endpoint with a JSON body — typically a Payments array where each item includes payee_id, amount, currency, a short description, and a client_reference_id. Best for on-demand, fully automated payouts.

Example (sandbox):

curl -X POST \
https://api.sandbox.payoneer.com/v4/programs/{program_id}/masspayouts \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer MXVNd2NTcTBlTi94NkZC…' \
-d '{
    "Payments": [
        {
            "client_reference_id": "test32452341",
            "payee_id": "33576892",
            "description": "Test_1256g1",
            "currency": "USD",
            "amount": "20.20"
        },
        {
            "client_reference_id": "test32452342",
            "payee_id": "3357689",
            "description": "Test_1256g2",
            "currency": "USD",
            "amount": "30.00"
        }
    ]
}'

(API reference guide)

Option 2 — Upload via the Admin Console (manual)

Use Mass Payments under the Payments area of the Payoneer Admin Console to upload a CSV, Excel, or XML file of payment instructions to your payees.

Admin Console: Mass Payments — upload a payment file (supported formats include CSV, XLS, XLSX, XML).

Use both together

You can use both the Submit Mass Payout API (automated) and Mass Payments file upload (manual) in the same operations. For example, use the API for on-demand payouts and the Mass Payments flow for a scheduled run such as a monthly bonus.