White Label Payouts

Overview

White Label Payouts lets you pay payees under your own brand once their details are known to your platform. There are two ways to submit payments:

  • One Step Payments — submit a single payment together with the beneficiary's full details (identification and bank account) in one API call.
  • Batch mass payouts — submit up to 500 payout instructions in one request to the masspayouts endpoint.

Both report status back through webhook callbacks. Before submitting, query the Banking registration fields endpoint to validate bank details per country, currency, and account type. See the getting started guide for full request schemas, authentication, and the Callback Notifications section.

One Step Payments API

Payoneer's One Step Payments API allows you to submit payment instructions together with full beneficiary details in a single API call. Beneficiary data includes:

  • Customer identification required for Payoneer's KYC process, and
  • Bank account details required to transfer funds to the beneficiary's bank.

Onboarding flow schematic

The diagram below illustrates the onboarding flow for beneficiaries submitted through the Single Step Payments API (design asset: Asset 3@4x).

Onboarding flow for beneficiaries via Single Step Payments API.

Banking registration fields

Rules for validating and submitting banking information in payout instructions typically vary by country, currency, and bank account type / transfer method. To reduce failed payments, query the Banking registration fields endpoint (registration fields for payee bank details) first to obtain the correct attribute formats for validation and submission before you send payout instructions. See the API reference for this endpoint and related fields.

Payout instruction for submitting a batch of payments

Data and money flows for submitting multiple payments via the Single Step Payment API to the masspayouts endpoint are summarized below. The schematic illustrates treatment for handling various exception scenarios. API calls and webhooks are numbered in the diagram according to their presentation in the Payouts REST API Guide (design asset: Asset 4@4x).

  1. Funds transfer: The client transfers funding for the payout to Payoneer's bank account before submitting the payout instruction.
  2. Credit notification: An Account Funded webhook confirms that funds were received.
  3. Prepare the batch: Optionally call the registration-fields endpoint to query the appropriate format for submitting bank details for each payout in the batch per country, currency, and account type.
  4. Batch payout instruction: Send up to 500 payout instructions in one request to POST /v4/programs/{program_id}/masspayouts (see example below).

Payment instructions are held for deferred validation and processing. The platform sends webhooks so your integration is notified of payment status and of validation issues. See the Callback Notifications / Webhook notifications section of the getting started guide.

Interfaces for supporting batch payout instructions

Schematic: Client, Payoneer, and Payee — funding, format query, mass payout submission, validation (including KYC/SAFE), resubmission, cancellation, and reporting.

White Label Payouts — batch interfaces (data, money, API, webhooks) per Payouts REST API Guide numbering.

Example: Submit Mass Payout

Example (sandbox). Request body: a Payments array; each item includes client_reference_id, payee_id, amount, description, and payout_method_details (payee, payout method, and optional orders_report for China SAFE).

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 @masspayouts-body.json

Put the JSON below in masspayouts-body.json

{
  "Payments": [
    {
      "client_reference_id": "test943490909009",
      "payee_id": "testgary6666889",
      "amount": "20",
      "description": "payment description",
      "payout_method_details": {
        "client_session_id": "session1",
        "payee": {
          "type": "company",
          "contact": {
            "first_name": "John",
            "last_name": "doe",
            "email": "test123456@mailinator.com",
            "date_of_birth": "1980-01-01",
            "mobile": "2123123123",
            "mobile_country": "US",
            "phone": "2123123123",
            "phone_country": "US",
            "nationality": "US"
          },
          "company": {
            "legal_type": "LLC",
            "name": "ABC",
            "url": "http://www.abc.com",
            "incorporated_state": "NY",
            "incorporated_country": "US"
          },
          "address": {
            "address_line_1": "address_line_1",
            "address_line_2": "address_line_2",
            "city": "city",
            "state": "NY",
            "country": "US",
            "zip_code": "10001"
          }
        },
        "payout_method": {
          "bank_account_type": "company",
          "currency": "USD",
          "country": "US",
          "details": {
            "bank_name": "Bank of America",
            "account_name": "GaryTest",
            "account_number": "827078555",
            "account_type": "C",
            "routing_number": "122105155"
          }
        }
      }
    },
    {
      "client_reference_id": "Payment1235",
      "payee_id": "ID124",
      "amount": "21",
      "description": "payment description",
      "payout_date": "10-01-2018",
      "currency": "USD",
      "group_id": "123",
      "payout_method_details": {
        "client_session_id": "session2",
        "payee": { },
        "payout_method": { },
        "orders_report": { }
      }
    }
  ]
}

Replace the empty payee, payout_method, and orders_report objects in the second payment with the structures required for your program; for China SAFE order data, see Mass Payout with China SAFE.

Validation, webhooks, resubmit, cancel, reporting

Payoneer performs data validation on the request. When errors occur, the API response lists the specific client_reference_id values that failed.

For each payout instruction in the batch, Payoneer sends separate webhooks to the client, referencing the unique client_reference_id for that payout. Subscribe to the cancel payment webhook (and related callbacks) to receive notification of failed payouts — see Webhook notifications in the getting started guide.

  • Payout submitted / settled: Confirmation that the payout processed and funds transferred to payees (success path).
  • Payout cancelled: Rejected payout instruction — cancelled and funds returned (failure path).

Parse webhook payloads to determine why a payment failed and apply the right treatment: correct the instruction, or submit missing KYC or SAFE data per Payoneer. Append corrected payout instructions to a fresh batch and submit again via masspayouts.

You can optionally submit a request to cancel a specific payment by referencing the payment ID (see Cancel Payouts in the API guide). Reporting interfaces let you query payees and payouts on the Payoneer platform (status APIs).

Webhook payout flowchart

End-to-end flow from register-payee format through batch registration, automated acceptance, optional KYC review, and webhook notifications.

White Label Payouts — batch registration, decision, and webhook outcomes.

Outcomes and webhooks

  • Yes — Payment Loaded webhook. The payment is loaded successfully; your integration receives the corresponding webhook.
  • No — Cancel Payment webhook. The payment is cancelled; a cancel webhook is sent.
  • Soft No Go — KYC webhook (71). Triggers manual review. After Approve: success may route back to Payment Loaded webhook; No leads to Decline webhook, which may align with cancellation handling.
  • Provider exception: If the provider cannot process the payout, the flow may move between loaded and cancelled states as shown in the diagram.