Does the recipient need an existing Payoneer account?

Yes. payee_id is the recipient's Payoneer account identifier. If they don't have a Payoneer account yet, you can send them a registration link via the Payoneer API. MockGateway lets you test with mock payee_ids so you don't need real recipient accounts during development.

Can one batch include payouts in different currencies?

Yes. Each payout entry specifies its own currency field. Payoneer handles the multi-currency accounting. Your batch response groups total_amount by currency so you can see the total outflow in each currency at a glance.

What does PAYEE_ACCOUNT_INACTIVE mean?

The recipient has a Payoneer account but it's in an inactive or restricted state — often because they haven't completed identity verification. You'll need to ask the recipient to resolve this on their Payoneer account before the payout can proceed.

How is Payoneer different from Stripe payouts or PayPal mass pay?

Payoneer is designed specifically for cross-border B2B payouts — marketplace sellers, remote contractors, affiliate payouts — especially to recipients in emerging markets where Stripe and PayPal have limited availability. Recipients can withdraw to local bank accounts in their own currency.

Can a batch be partially successful?

Yes, and you should expect this. Each payout in a batch has its own status. A single batch can have some PAID entries and some FAILED entries. Your webhook handler and batch polling logic must handle per-entry status — do not assume the whole batch succeeds or fails atomically.

A batch payout can partially succeed.
Payoneer pays some, fails others,
rolls back nothing.

Payoneer is not a checkout gateway — it's a payout platform. Instead of collecting money from customers, you use it to pay sellers, contractors, and affiliates at scale. A single API call can batch dozens of cross-border transfers across multiple currencies.

Use this template Payoneer docs ↗

Use case

B2B payouts

Currencies

Multi-currency

To start

0 setup

payout_response.json

{

"batch_id": "batch_mock_PaY...",

"status": "PAID",

"payee_id": "payoneer_uid_00481",

"amount": 250.00,

"currency": "USD",

"paid_at": "2024-01-15T09:45:00Z"

}

Payoneer is fundamentally different from most payment gateways on this list. Where Stripe, PayPal, and Razorpay help you collect money from customers, Payoneer helps you send money to recipients — contractors, marketplace sellers, affiliates, or any payee with a Payoneer account. This means there is no checkout flow, no customer redirect, and no card form. The entire flow is server-side.

The Payouts API accepts a payee_id (the recipient's Payoneer account identifier), an amount, and a currency. You can submit individual payouts or batch multiple recipients into a single API call. Batches are processed asynchronously — each payout gets its own status: PENDING while queued, PROCESSING while being sent, PAID when received. A batch can partially succeed — some payouts PAID while others FAILED.

Common failure reasons include PAYEE_ACCOUNT_INACTIVE (recipient hasn't activated their Payoneer account), INSUFFICIENT_BALANCE (your balance is too low), and CURRENCY_NOT_SUPPORTED. You need to handle these per-payout errors in batch responses, not just a top-level success/failure. This mock delivers the full batch payout flow and all status transitions.

Payouts, not collections

Most payment gateways move money toward you. Payoneer moves money away from you. That's not a limitation — it's the whole point. If you're building a marketplace, a gig platform, or an affiliate network, your problem isn't collecting payments: it's distributing them.

Standard gateway (Stripe, PayPal)

Customer

pays $50

money in

You

receive $50

You are the merchant. Customers pay you. Your bank account fills up.

Payoneer

You

send $250

money out

Recipient

contractor / seller

You are the payer. Sellers, contractors, affiliates receive money from you.

Common use cases: marketplace seller payouts, freelance platform contractor payments, affiliate network commissions, content creator royalties.

Mass payout flow

Payoneer processes payouts asynchronously. You submit a batch, receive a batch_id immediately, then track individual statuses as they settle. A batch can span multiple currencies and dozens of recipients.

Batch the payouts

Build a list of recipients (payee_id + amount + currency). Each entry gets a client_reference_id you define — this is how you match webhook events back to your internal records.

Submit the batch

POST the entire array in one request. Payoneer returns a batch_id immediately with status PENDING. Batches can contain payouts in multiple currencies.

Track per-recipient status

Poll GET /payouts/{batch_id} or listen for payout.paid and payout.failed webhooks. Each recipient has its own status — a batch can be partially successful.

Payout statuses

Each entry in a batch has its own lifecycle. Handle all five states.

PENDING

In the queue, not yet sent to the recipient.

PROCESSING

Being transferred — funds are in flight to the recipient's account.

PAID

Recipient received funds. Update your records and mark the payout complete.

FAILED

Payout did not complete. Check error_code in the webhook or batch status response.

CANCELED

Cancelled before processing began. Can be re-submitted as a new payout.

curl -X POST https://mockgateway.dev/api/base/payoneer/init \
  -H "Authorization: Bearer YOUR_MOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payouts": [
      {
        "payee_id": "payoneer_uid_00481",
        "amount": 250.00,
        "currency": "USD",
        "description": "Freelance project — March invoice",
        "client_reference_id": "PAY-REF-20001"
      },
      {
        "payee_id": "payoneer_uid_00927",
        "amount": 1800.00,
        "currency": "EUR",
        "description": "Marketplace seller payout — week 12",
        "client_reference_id": "PAY-REF-20002"
      }
    ]
  }'

Request parameters

Sent to POST /api/base/payoneer/init

Request parameters
Parameter	Type	Required	Description
`amount`	number	required	Transaction amount `e.g. 99.99`
`currency`	string	required	ISO 4217 currency `e.g. USD`
`order_id`	string	required	Your unique order reference `e.g. ORD-12345`
`description`	string	optional	Payment description