Business funding — Getting started

Integration guide: prequalification (SFTP & webhooks), consent, offer acceptance, load / collect debt, and program withdrawal.

Overview

Business funding lets partners offer eligible account holders pre-qualified capital through Payoneer. The diagram below is the end-to-end flow: initiation, offer discovery, pre-qualification, consent and data access, review and accept funds, and load or repay, ending with a balance update on the Payoneer side.

High-level process: consented data access, partner APIs, and webhooks between Payoneer, your platform, and the account holder.

Preparation and setup

Before you start the integration, ensure the following is in place:

  1. API credentials — secure the API key and secret from the Payoneer Integration team.
  2. Sandbox access — set up a sandbox environment for testing.
  3. Consent framework — design a user consent flow that meets Payoneer's compliance standards.

Integration process for offers

Covers the SFTP-based prequalification loop, then customer engagement on your site, and finally fund activation. Work through Parts A–C and the numbered steps in order.

Part A — Prequalification & offer calculation

Step 1: Daily model run & anonymous data file delivery (Payoneer → partner via SFTP)

Payoneer runs a daily model and produces anonymous customer data files. Files are placed on Payoneer's SFTP server in:

incoming/<Country ISO2 Code>/<file name>

Example path:

incoming/HK/Integration_Run_0b1cb257-f90d-4e25-ae91-e4413f9d0ecc.json

Anonymous data file specification

  • Format: NDJSON (newline-delimited JSON); each line is one customer record.

Example (to US partners):

{
  "client_reference_id": "<GUID>",
  "country_iso2": "US",
  "account_create_date_epoch": 1679876543,
  "current_relevant_balance_usd": 4.0, //valid for US partners
  "volume_summaries": [
    {
      "marketplace": "Amazon",
      "currency": "USD",
      "period_in_months": 6,
      "average_monthly_amount": 12000.50,
      "transaction_minimum_amount": 100.00,
      "transaction_maximum_amount": 8000.00,
      "transactions_count": 124
    }
  ]
}

Example (to HK partners):

{
  "client_reference_id": "<GUID>",
  "country_iso2": "HK",
  "account_create_date_epoch": 1679876543,
  "volume_summaries": [
    {
      "marketplace": "Amazon",
      "currency": "USD",
      "period_in_months": 6,
      "average_monthly_amount": 12000.50,
      "transaction_minimum_amount": 100.00,
      "transaction_maximum_amount": 8000.00,
      "transactions_count": 124
    }
  ]
}

Step 2: Webhook notification (Payoneer → partner)

When a new anonymous data file is available on SFTP, Payoneer sends a webhook event.

Event: Partnerships Anonymous Data File Uploaded

Payload fields

FileId
Unique file identifier
Country
ISO-2 country code
SftpDownloadPath
Full SFTP path to download the file
SchemaVersion
Schema version for the file format
Timestamp
UTC send time

Partners use this notification to download the file and generate offers.

Step 3: Partner generates offers & uploads offer files (partner → SFTP)

  1. Download the file.
  2. Process the data and build offers for each account holder line.
  3. Upload offer files to: outgoing/<partner id>/<file name.json>
outgoing/123456/Partner_Offer_a61a72e0-27c4-4375-a11e-db42252a436a.json

Offer file specification (partner → Payoneer)

  • Format: NDJSON; each line is one customer record.
  • Include client_reference_id (must match the anonymous data file) and an offer_calculations array of offers for that customer.

Sample structure (one line):

{
  "client_reference_id": "<GUID>",
  "offer_calculations": [
    {
      "offer_id": "<GUID>",
      "fund_type": 1,
      "currency": "USD",
      "offer_amount": 15000,
      "duration_in_days": 180,
      "interest_rate_range": {
        "min": 1.25,
        "max": 2.10
      },
      "line_of_credit_details": {
        "withdraw_period_in_days": 30
      }
    }
  ]
}

Step 4: Partner notifies Payoneer (File notify API)

After the offer file is uploaded to SFTP, call the File notify API so Payoneer can process it. Use an OAuth 2.0 application token. The request body includes client_reference_id (a tracking GUID for this notify call) and file_name (the exact filename on SFTP, not the full path).

curl --request POST \
  --url https://api.sandbox.payoneer.com/p2/v4/lending/offers/file-notify \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer 123' \
  --header 'Content-Type: application/json' \
  --data @file-notify.json

Request body (file-notify.json):

{
  "client_reference_id": "3f8c2c45-9b1e-4a3c-94e9-7f3f0f2b1a67",
  "file_name": "3f8c2c45-9b1e-4a3c-94e9-7f3f0f2b1a68.json"
}

Response:

{
  "result": "Notification received. File validation and processing will occur asynchronously."
}

Processing is asynchronous: Payoneer reads the file from SFTP, parses each NDJSON line, matches client_reference_id to anonymous account references, and stores offers for eligible account holders.

Step 5: Payoneer processes the offers (Payoneer)

Payoneer validates the uploaded file. When processing succeeds, offers are stored and shown in MyAccount for eligible customers.

Part B — Customer engagement & offer acceptance

Step 6: Customer interested in offer (Payoneer → vendor platform)

If a Payoneer customer expresses interest in an offer, Payoneer redirects them to the vendor platform with an authorization code and an offer ID.

Example consent flow shown to the account holder (partner name is supplied by the program).

Step 7: Vendor platform offer page & token generation (vendor platform)

The vendor platform presents the offer landing page to the customer. After consent, it generates an access token and retrieves customer-related data from Payoneer APIs, for example:

Use that data to calculate offer eligibility and present final terms in your product.

Step 8: Customer accepts the offer (vendor platform → Payoneer)

When the customer agrees, call Create fund (POST /p2/v4/lending/funds) with offer_id, end_date, currency, amount, and initial_status. Payoneer returns a fund_id in the response for your platform to use in later steps.

Example partner UI for reviewing a proposed offer before acceptance and Create fund.

API — Create fund

Create the fund when the customer accepts an offer. POST /p2/v4/lending/funds. See the API reference. Request:

curl --request POST \
  --url https://api.sandbox.payoneer.com/p2/v4/lending/funds \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer 123' \
  --header 'Content-Type: application/json' \
  --data @create-fund.json

Request body (create-fund.json):

{
  "offer_id": "e59d3dbf-ed36-4a79-b34d-927be362c045",
  "end_date": "2025-03-25T10:59:11.78Z",
  "amount": "10000.00",
  "currency": "USD",
  "initial_status": "10"
}

Response:

{
  "result": {
    "fund_id": "13cdd195-084f-4a61-bc67-fc8f493de5e4",
    "payee_id": "8a762c56-e5d7-41cc-9add-c6c0efc5fd13"
  }
}

Part C — Offer activation & credit status update

Step 9: Update fund details (vendor platform → Payoneer)

Call Update fund details (PUT /p2/v4/lending/funds) with fund_id and status. For example, set 20 (Active) when the credit line is ready for drawdown. Other values include 10 Pending Activation, 99 Cancelled, and 100 Completed.

API — Update fund details

Activate the fund (or change its state). PUT /p2/v4/lending/funds. See the API reference. Request:

curl --request PUT \
  --url https://api.sandbox.payoneer.com/p2/v4/lending/funds \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer 123' \
  --header 'Content-Type: application/json' \
  --data @update-fund.json

Request body (update-fund.json):

{
  "fund_id": "568f68b1-a969-42b4-a166-5fd170a2714a",
  "end_date": "2025-05-25T10:59:11.78Z",
  "amount": "10000",
  "status": "20"
}

Response:

{
  "result": "The fund has been updated successfully"
}

Money loading (drawdown)

After the user accepts the offer, use the Load funds (or program-equivalent) API to move funds to the user's Payoneer balance. Payoneer may send a Client Reference ID and transaction details to your platform so you can log a drawdown in your back office.

Subscribe to payout-related webhooks to know when the load has completed:

  • Request received — payout request was received by Payoneer.
  • Account / card loaded — funds are available on the Payoneer account or card.

You can show a drawdown form or summary in your app as data arrives.

Example drawdown UI: facility summary and “New drawdown” entry.

API — Load funds (drawdown)

Move funds from the facility to the user's Payoneer balance. POST /p2/v4/lending/money-movement/load. See the API reference. Request:

curl --request POST \
  --url https://api.sandbox.payoneer.com/p2/v4/lending/money-movement/load \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer 123' \
  --header 'Content-Type: application/json' \
  --data @load.json

Request body (load.json):

{
  "fund_id": "e59d3dbf-ed36-4a79-b34d-927be362c045",
  "client_reference_id": "65d17b05-c47a-494d-a360-d7b5943dd3ad",
  "transaction_amount": "10000.00",
  "currency": "USD"
}

Response:

{
  "result": "The load transaction has been successfully initiated."
}

Repayment model (collect debt)

To collect repayment, call the Collect debt API with the fund ID and the transaction you want to collect. The partner platform should record a repayment event. For collections that occur outside Payoneer, you may also use the External collect debt path when your program allows it—confirm the exact name and path in the API reference.

Example repayment form tied to a drawdown and payee/destination details.

Monitoring charge status

Subscribe to:

  • Charge success — the debit to the user's balance succeeded.
  • Charge failure — the collection attempt failed (includes failure context where provided).
Example status UI: drawdowns, outstanding, and state (e.g. settled).

API — Collect debt

Collect a repayment (principal and interest) from the user. POST /p2/v4/lending/money-movement/collect. See the API reference. Request:

curl --request POST \
  --url https://api.sandbox.payoneer.com/p2/v4/lending/money-movement/collect \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer 123' \
  --header 'Content-Type: application/json' \
  --data @collect.json

Request body (collect.json):

{
  "fund_id": "c3f895fb-a240-47c1-9816-68006bea6374",
  "client_reference_id": "c3f895fb-a240-47c1-9816-68006bea6372",
  "principal_amount": "100",
  "interest_amount": "1",
  "currency": "USD"
}

Response:

{
  "result": "Collect debt transaction has been successfully initiated."
}

API — External collect debt

Record a repayment collected outside Payoneer. POST /p2/v4/lending/money-movement/external-collect. See the API reference. Request:

curl --request POST \
  --url https://api.sandbox.payoneer.com/p2/v4/lending/money-movement/external-collect \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer 123' \
  --header 'Content-Type: application/json' \
  --data @external-collect.json

Request body (external-collect.json):

{
  "client_reference_id": "c3f895fb-a240-47c1-9816-68006bea6370",
  "fund_id": "c3f895fb-a240-47c1-9816-68006bea63741",
  "principal_collected_amount": "100",
  "interest_collected_amount": "5",
  "currency": "USD",
  "collection_date": "2025-07-03T10:59:11.78Z"
}

Response:

{
  "result": "The external collection was documented successfully."
}

Withdraw funds from program

When funds are loaded and any repayments are recorded as your program requires, you can move money out of the program balance. Typically this uses Payoneer's payout stack to pay your own payees in bulk: settlements to partners, internal allocations, or other operational payees you configure.

  1. Initiate payout — call Submit mass payout with one or more payees and amounts. The program balance is debited on successful submission (subject to funding checks).
  2. Payout processing — each item gets a trackable client or payment reference for reconciliation.
  3. Monitor status — poll Get payout status (or use webhooks where available) for pending, completed, or failed items.

API — Submit mass payout

Pay one or more program payees. POST /v4/programs/{program_id}/masspayouts. See the API reference. Request:

curl --request POST \
  --url https://api.sandbox.payoneer.com/v4/programs/{program_id}/masspayouts \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer 123' \
  --header 'Content-Type: application/json' \
  --data @masspayouts.json

Request body (masspayouts.json):

{
  "Payments": [
    {
      "client_reference_id": "string",
      "payee_id": "string",
      "description": "string",
      "currency": "str",
      "amount": 0,
      "payout_date": "2019-08-24T14:15:22Z",
      "group_id": "string"
    }
  ]
}

Response:

{
  "result": "Payments Created"
}

API — Get payout status

Poll the status of a submitted payout. GET /v4/programs/{program_id}/payouts/{client_reference_id}/status. See the API reference. Request:

curl --request GET \
  --url https://api.sandbox.payoneer.com/v4/programs/{program_id}/payouts/{client_reference_id}/status \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer 123'

Response:

{
  "result": {
    "payout_date": "2021-03-17T10:47:00-04:00",
    "amount": 5.10,
    "currency": "USD",
    "status": "{{payout_status}}",
    "target_amount": 4.20,
    "target_currency": "EUR",
    "payee_id": "Test41234s1324",
    "payout_id": "1636595702",
    "scheduled_payout_date": "2021-04-30T00:00:00-04:00",
    "load_date": "2021-03-17T14:09:39.54-04:00" // present if status is Transferred
  }
}