Billing services

Overview

Payoneer can optionally handle the billing process for your customers. Each customer must consent and opt in to bill via Payoneer. This is only available for customers who have their own active Payoneer account.

Opt-in to billing services

Opting in involves the following steps:

1. Customer starts opt-in on your platform

On your platform, the customer enters a request to opt in to Payoneer billing (for example from a menu entry such as "Request a payment" leading to an intro screen and Get started).

2. Call payment_request/optin

Use payment_request/optin to request opt-in for this customer and determine if they are eligible. Confirm the exact path, body, and auth scopes in the API reference. Example (sandbox):

curl -X POST \
https://api.sandbox.payoneer.com/v4/accounts/{account_id}/payment_request/optin \
-H 'content-type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer MXVNd2NTcTBlTi94NkZC…' \
-d '{
    "client_reference_id": "optin-2025-0416",
    "accept_terms": true,
    "notification_url": "https://partner.example.com/webhooks/payo/billing"
}'

3. Display opt-in status on your platform

On your platform, display the status returned by the API. Persist it on the customer record (for example: not started, in progress, opted-in completed, not eligible). Map the API values to your UI (for example NOT_STARTED, IN_PROCESS, NOT_ELIGIBLE, COMPLETED — see the API reference for the canonical list).

4. Payoneer emails the customer for more information

Payoneer will email the customer to request additional information (for example business details and documents). The customer completes steps in Payoneer (sign in, provide information, submit documents).

5. Payoneer notifies you when information is complete

Payoneer will notify your platform when the customer information is complete (for example via webhook or polling — see the API reference).

Eligibility: Core countries and volume threshold

• Core countries: Billing Services works automatically from countries Payoneer considers "Core". A list of such countries can be provided by Payoneer if needed.
• Non-Core countries: If the user is not from a Core country, they must have reached the threshold of $5,000 in volume through their account before eligible for the service.

Payment requests

Customers who have completed opt-in for Payoneer billing may request a payment by the following steps:

1. On your platform, the customer enters a request to set up a payment request.
2. Use Create Payment Request to create a payment link so payment information can be entered. The link can open in a new browser tab within your application.
3. The customer submits the form to request the payment.

Payer information can be pre-populated by sending the fields in the API body. This is available for customers who complete the opt-in process. The service is available once the user has completed opt-in.

Request flow (UI)

Create Payment Request (API)

POST the Create Payment Request to obtain the payment link and any identifiers returned by your program (see API reference). Example (sandbox):

curl -X POST \
https://api.sandbox.payoneer.com/v4/accounts/{account_id}/payment-requests \
-H 'content-type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer MXVNd2NTcTBlTi94NkZC…' \
-d '{
    "client_reference_id": "inv-77821",
    "amount": 199.99,
    "currency": "USD",
    "description": "Marketplace order #4412",
    "due_date": "2025-04-30",
    "payer": {
        "name": "Jane Doe",
        "email": "jane@example.com",
        "phone": "+1-555-0100"
    }
}'

The response typically includes a URL to open the payment link and track status.

{
  "result": {
    "payment_request_id": "pr_7f3c2a1b9e",
    "client_reference_id": "inv-77821",
    "status": "pending",
    "opa_url": "https://payoneer.com/opa/...",
    "created_at": "2025-04-16T12:00:00.000Z"
  }
}