Payee onboarding

Overview

The Create Registration Link API on-boards new payees onto the Payoneer platform so they can receive payouts. You pass a unique payee ID from your system; Payoneer stores it and uses it to identify the recipient when payout instructions are submitted.

Typically you call this from your payee on-boarding flows where payees choose how they get paid. The API returns a URL you use to send the payee to Payoneer to complete registration.

When a payee opens that link, your integration should call the Registration API and redirect the payee to Payoneer using the unique URL from the API response. Payoneer associates the payee with your payee_id.

See the API reference guide for request and response fields.

Request

Example (sandbox):

curl -X POST \
https://api.sandbox.payoneer.com/v4/programs/{program_id}/payees/registration-link \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer MXVNd2NTcTBlTi94NkZC…' \
-d '{
    "payee_id": "ClientPayeeID"
}'

Response

The API returns a URL you redirect the payee to. Example:

https://payouts.sandbox.payoneer.com/partners/lp.aspx?token=PayoneerToken

Pre-populating payee data

The Create Registration Link API can include payee profile data so Payoneer can pre-fill registration screens (first name, last name, date of birth, address, and more). Certain fields can be locked using the lock_type parameter where your program supports it.

Example request body with contact and address (matches the registration step illustrated below):

{
    "payee_id": "test3453453",
    "redirect_url": "https://www.testpartner.com",
    "payee": {
        "contact": {
            "last_name": "McSchmidt",
            "first_name": "Josh",
            "email": "JMchmidt@test.com"
        },
        "address": {
            "address_line_1": "123 Main St.",
            "address_line_2": "",
            "city": "New Delhi",
            "state": "",
            "zip_code": "110001",
            "country": "IN"
        }
    }
}
Pre-population: request body fields map to the payee registration UI (for example first name, last name, and country).

Enabling users to connect existing Payoneer accounts

If the payee already has a Payoneer account, set already_have_an_account to true when creating the registration link so the API returns a URL for connecting that payee to your program for payouts (instead of full sign-up).

Example request body (minimal):

{
    "payee_id": "ClientPayeeID",
    "already_have_an_account": true
}
Example: existing-account flow — payee signs in on Payoneer to connect their account.

Get notified about payee status

Payees must be Active (registered and approved) on Payoneer's platform before receiving payments. Payoneer provides API calls and webhooks so you can determine payee status in real time.

Method 1: Account status notification via webhook (recommended)

Mass Payout programs can use Payoneer's webhooks to receive immediate notifications about payee status. Webhooks deliver real-time updates for events such as payee registration, approval, decline, and payment status.

Webhooks are sent from Payoneer to a URL you configure when an event occurs (for example, payee approval). When a payee is approved, Payoneer calls your endpoint so you can update your system.

Example callback URL pattern:

https://www.Client.com/Approved/PayeeID={{apuid}}

The webhook consumer URL is configured in the Settings tab of the Payoneer Admin Console. Review available webhook events and payloads in the Payoneer Payout Integration Guide for your program.

Method 2: Account status query via API

Call Get Payee Status to read a payee's status (see API reference guide).

Example (sandbox):

curl -X GET \
https://api.sandbox.payoneer.com/v4/programs/{program_id}/payees/{ClientPayeeID}/status \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer MXVNd2NTcTBlTi94NkZC…'