Partner API

Open a collection

Mints a reference and returns the USD deposit instructions a contributor pays to. expectedAmount is advisory — stored with the collection and never used to refuse anything.

post/v1/collections

Request

Base URL
https://sandbox.onlink.africa
Auth
API key in header X-OnLink-Key

Headers

Idempotency-Keystring

Retrying a create with the same key returns the same collection. A different body with the same key is refused IDEMPOTENCY_KEY_REUSED (422). The key is compared with the collection as it stands now: if the collection was edited since, a retry of the original create is refused IDEMPOTENCY_KEY_REUSED. 8 to 64 characters from A-Z, a-z, 0-9, _ and -; anything else is 400 INVALID_IDEMPOTENCY_KEY.

Request body

currency'USD' required

Currency a contributor deposits in. Only USD is supported today.

partnerReferencestring required

Your own reference for this collection (e.g. a community or campaign id). Stored for your audit trail; it is never used to look anything up — use the reference OnLink mints and returns for that.

payerLabelstring required

A human-readable label for your own records — never sent to the contributor.

expectedAmountstring

Advisory only — stored with the collection and never used to refuse a deposit. Decimal string, USD major units, up to 2 decimal places.

Example request

{
  "currency": "USD",
  "partnerReference": "campaign-2026-09",
  "payerLabel": "September community appeal",
  "expectedAmount": "100.00"
}

Response

The collection was opened.

idstring required

referencestring required

Where the collection is in its lifecycle. open: the deposit instructions are live and no deposit has arrived. received: a deposit has arrived and been matched to this collection; your fee is applied and the net amount is known. crediting: the deposit has been received and the net amount is being paid into your account; it becomes credited when the payout settles, or returns to received if the payout did not go through, and is then retried. credited: the net amount has been paid into your account (collection.received is sent at this point). refunded: the deposit was returned to the sender. expired: we closed the collection before any deposit arrived. Do not hand its deposit instructions out again: a deposit sent to them afterwards is not attributed to this collection. cancelled: the collection was cancelled before any deposit arrived. Do not hand its deposit instructions out again: a deposit sent to them afterwards is not attributed to this collection.

currencystring required

partnerReferencestring nullable required

Your own reference for this collection: the partnerReference you sent when you opened it, or the latest value if the collection was edited since (an open collection can be edited from the OnLink web app), or null for a collection opened before it was stored. Echoed back for your own matching; OnLink never uses it to look anything up.

labelstring nullable required

Your own label for this collection: the payerLabel you sent when you opened it, or the latest value if the collection was edited since (an open collection can be edited from the OnLink web app), or null for a collection opened before it was stored. For your own records; never sent to the contributor.

expectedAmountstring

grossAmountstring

feeAmountstring

netAmountstring

createdAtstring required

Example response

{
  "id": "a1b2c3d4-0000-4000-8000-000000000001",
  "reference": "DEMO-7K3Q2M",
  "status": "open",
  "currency": "USD",
  "partnerReference": "campaign-2026-09",
  "label": "September community appeal",
  "depositInstructions": {
    "beneficiaryName": "Sandbox Business",
    "bankName": "Bank of Nowhere",
    "routingNumber": "000000000",
    "accountNumber": "00000000123456",
    "rails": [
      "ach_push",
      "fednow",
      "wire"
    ],
    "depositMessage": "SBX0DEPOSITMESSAGE"
  },
  "fee": {
    "percentBps": 100,
    "flatMinor": 50,
    "capMinor": 2000,
    "currency": "USD"
  },
  "expectedAmount": "100.00",
  "grossAmount": "100.00",
  "feeAmount": "1.50",
  "netAmount": "98.50",
  "createdAt": "2026-09-22T17:38:46.915Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.