Capital advance — Create debt & repayment

Overview

Capital advance uses the same end-to-end integration as business funding — prequalification, offers, consent, load funds, program withdrawal, and the same webhooks and data-sharing patterns. The only material difference in how you model repayment is that you use the Create Debt API to initiate collection (a debt that Payoneer then retires from inflows) instead of the Collect debt path described for standard business funding.

Same flow as business funding

For everything before the repayment model (and for load funds, webhooks, and withdrawal from program), your integration matches business funding. In particular:

• Anonymous data / offers pipeline, consented data access, and offer acceptance, as in Integration process for offers on the business funding guide.
• Money in via Money loading (drawdown) and monitoring payout-related webhooks where your program uses them.
• Withdrawal from program balance via your payout flow (for example submit mass payout) as in the business funding guide.

Where the product diverges is how you start and track repayment — use Create Debt and the webhooks below instead of the Collect debt flow in the business funding doc.

4. Repayment model (create debt)

To start collection, the vendor calls the Create Debt API. It creates a debt request and drives fund collection from the user. Confirm operation names, fields, and webhooks in the API reference for your program version.

Vendor initiates create debt request

The vendor platform calls the Create Debt API. The request should include, at minimum:

• Fund ID — linked to the original funding.
• Debt amount.
• Transaction reference / description for reconciliation on your side.

API — Create debt

Start collection by creating the debt. POST /p2/v4/lending/debts. See the Create debt reference. Request:

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

Request body (create-debt.json):

{
  "client_reference_id": "1f19759d-03dc-4b41-b966-b95c7b3929ff",
  "fund_id": "854bdda5-e62d-47d1-a04f-3f40c8919f40",
  "principal_amount": 1000,
  "interest_amount": 50,
  "collection_percentage": 10.5,
  "currency": "USD"
}

Response:

{
  "result": {
    "principal_debt_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "interest_debt_id": "7fa85f64-5717-4562-b3fc-2c963f66afa7"
  }
}

Debt is created in Payoneer

Payoneer creates a debt record for the user. Listen to the Create debt status webhook (or the status events your program publishes) for updates. The debt represents the obligation to repay the specified amount.

Funds are collected

Payoneer applies collection when there are incoming payments to the user's balance: the debt is reduced from those inflows per program rules. Handle partial, pending, and completed states in your back office using webhook payloads and your own ledgers.

Vendor platform records repayment

Your platform should:

• Record the repayment event in your system.
• Link it to the original funding and the Payoneer fund / debt identifiers.
• Track status (e.g. pending, completed, failed) for support and reporting.

Vendor platform responsibilities

• Ensure the Fund ID matches the original funding transaction.
• Send accurate amount and reference details in Create Debt.
• Handle API responses, including successful creation, pending or partial collection, and failure cases (for example insufficient balance).
• Maintain internal reconciliation between funding, debt, and repayment records.

Alternative collection (external collect debt)

If repayment is collected outside Payoneer, report it with the External Collect Debt API so Payoneer's records and your program stay aligned. See the API reference for the exact endpoint, body, and idempotency rules.