Mass Payout with China SAFE
Overview
Cross-border payouts involving China require order reporting consistent with SAFE (State Administration of Foreign Exchange) rules. Payoneer's Mass Payout with China SAFE solution lets you submit mass payouts together with the SAFE-related order information your program must supply, using either a REST API or an SFTP file channel.
Follow the official guide for every page in the flow: eligibility, field definitions, validation rules, file layouts, and error handling.
SAFE reporting
Your platform typically holds trade or service order data that must accompany eligible payouts. Payoneer maps that data into the reporting workflow described in the guide. Exact required properties, formats, and per-program rules are defined in the official documentation—not duplicated here—so your integration stays aligned with the current specification.
Prerequisites
- Program enabled for China SAFE mass payout (confirm with Payoneer).
- Payees registered and eligible for payout (see Payee onboarding).
- Funding sufficient for requested payouts (same principle as Submit mass payout).
- Credentials: OAuth2 application token for the API path; SFTP key/username and paths for the SFTP path (issued per your integration package).
Solution 1: REST API
Use your program access token with Submit Mass Payout (POST /v4/programs/{program_id}/masspayouts). Each payment can include orders_report with merchant/store details and either an SFTP JSON path (orders.type: local_ftp) or you can send order line items later via Update SAFE data (below). See the official guide for validation rules.
Submit mass payout with orders_report (SFTP JSON location)
Point orders.path at the JSON file on Payoneer's SFTP (example URLs below). Include payout_date, group_id, and the merchant / store structure as required for your program.
curl --request POST \
--url https://api.sandbox.payoneer.com/v4/programs/{program_id}/masspayouts \
--header 'Accept: application/json' \
--header 'Authorization: Bearer MXVNd2NTcTBlTi94NkZC…' \
--header 'Content-Type: application/json' \
--data '{
"Payments": [
{
"client_reference_id": "Payment1234",
"payee_id": "ID123",
"amount": "20",
"description": "payment description",
"payout_date": "10-01-2018",
"currency": "USD",
"group_id": "123",
"orders_report": {
"merchant": {
"id": "123456",
"store": {
"name": "Payoneer goods LLC",
"url": "www.payoneer.com",
"type": "ECOMMERCE"
}
},
"orders": {
"type": "local_ftp",
"path": "http://sftp.payoneer.com/xxxxxx.json"
}
}
},
{
"client_reference_id": "Payment1235",
"payee_id": "ID124",
"amount": "20",
"description": "payment description",
"payout_date": "10-01-2018",
"currency": "USD",
"group_id": "123",
"orders_report": {
"merchant": {
"id": "123456",
"store": {
"name": "Payoneer goods LLC",
"url": "www.payoneer.com",
"type": "ECOMMERCE"
}
},
"orders": {
"type": "local_ftp",
"path": "http://sftp.payoneer.com/xxxxxxx.json"
}
}
}
]
}'Update SAFE data API (after mass payout)
Alternatively, call POST /v4/programs/{program_id}/payouts/{client_reference_id}/safe-data after submission to supply orders_report with inline orders.items when orders.type is data (same client_reference_id as the payout).
curl --request POST \
--url https://api.sandbox.payoneer.com/v4/programs/{program_id}/payouts/{client_reference_id}/safe-data \
--header 'Accept: application/json' \
--header 'Authorization: Bearer MXVNd2NTcTBlTi94NkZC…' \
--header 'Content-Type: application/json' \
--data '{
"orders_report": {
"merchant": {
"id": 9472596,
"store": {
"name": "floral",
"url": "https://www.example.com/shop/floral",
"type": "ECOMMERCE"
}
},
"orders": {
"type": "data",
"items": [
{
"order_id": 3237717488,
"order_date": "2024-03-10T01:59:07+00:00",
"commit_date": "2024-03-10T02:01:01+00:00",
"item_name": "High Quality Artificial Plant Office Wedding Home Decoration Gifts",
"item_id": 1597070916,
"quantity": 1,
"sku": 18883461293,
"category": "Craft Supplies & Tools",
"logistics_company": "UPS",
"logistics_number": "1Z12345E02919",
"price": "32.80",
"currency": "USD"
},
{
"order_id": 3232876399,
"order_date": "2024-03-12T00:53:50+00:00",
"commit_date": "2024-03-12T00:53:55+00:00",
"item_name": "DIY Florals Wedding Home Decoration Gifts DIY Bouquets Centerpieces",
"item_id": 475985959,
"quantity": 2,
"sku": 2908998297,
"category": "Craft Supplies & Tools",
"logistics_company": "FedEx",
"logistics_number": "6345634564",
"price": "13.50",
"currency": "USD"
}
]
}
}
}'Request and response schemas: API reference guide and v4-china-safe.
Solution 2: SFTP (batch file)
Alternatively, upload a batch file (for example CSV or XML) that contains payout rows and the SAFE order columns defined in the official guide. Payoneer provisions an SFTP endpoint, credentials, inbound folder, and file naming or scheduling rules as part of your integration package.
Typical flow:
- Build the file according to the layout and encoding in the guide.
- Connect with SFTP using the host, username, and private key (or password) Payoneer provides.
- Upload to the designated inbound directory; processing is asynchronous.
- Monitor processing via status APIs, reports, or webhooks as configured for your program.
Illustrative SFTP session (confirm host, paths, and key path with your integration materials):
sftp -i ~/.ssh/payoneer_sandbox_rsa partner@sftp.sandbox.payoneer.com
sftp> cd /inbound/mass_payout_china_safe
sftp> put ./batch_20250416_01.csv
sftp> byeChoosing API vs SFTP
| Topic | API | SFTP |
|---|---|---|
| Best for | Real-time or on-demand payouts from your backend | Scheduled or large batch uploads from finance/ops pipelines |
| Integration | OAuth2 + HTTPS JSON | SSH key + file drop |
| SAFE data | Must match the official schema; both channels carry the same reporting obligations | |
Status and monitoring
Payout submission is typically asynchronous. Use the status and notification mechanisms in the API reference (for example payout status endpoints or webhooks where enabled).