Open a collection

Collections are a separate product from the sell/buy USDT rails covered elsewhere in these guides — see Products and scopes for which credential you need. A collection is one thing: a reference plus a dedicated USD deposit account, opened for one purpose you choose — a single contribution, or many contributions from one community over time.

sequenceDiagram
    autonumber
    accTitle: Opening a collection and reading it back
    accDescr: You create a collection, naming its currency and your own reference. OnLink mints a reference and opens a dedicated USD deposit account, returning both plus the fee terms. You hand the deposit instructions to your contributor. Later you read the collection by id, or list your collections filtered by reference, status and date.
    participant You
    participant OnLink
    participant Contributor

    You->>OnLink: POST /v1/collections (currency, partnerReference, payerLabel)
    OnLink->>OnLink: mint a reference, open a dedicated deposit account
    OnLink-->>You: 201 id, reference, depositInstructions, fee
    You->>Contributor: hand over the deposit instructions
    You->>OnLink: GET /v1/collections/:id (any time)
    OnLink-->>You: the collection, refreshed

1. Create the collection

POST /v1/collections takes the currency, your own reference for the collection, and a label for your own records:

Response — 201 Created:

{
  "id": "a1b2c3d4-0000-4000-8000-000000000001",
  "reference": "DEMO-7K3Q2M",
  "status": "open",
  "currency": "USD",
  "depositInstructions": {
    "beneficiaryName": "Onlink Technology, Inc.",
    "bankName": "Bank Name",
    "routingNumber": "000000000",
    "accountNumber": "0000000000",
    "rails": ["ach_push", "fednow", "wire"],
    "depositMessage": "BRGBFRC25ZJZ4RAVXEZK"
  },
  "fee": {
    "percentBps": 175,
    "flatMinor": 30,
    "capMinor": null,
    "currency": "USD"
  },
  "createdAt": "2026-09-22T17:38:46.915Z"
}

reference is minted for you — an unambiguous code (no 0, 1, I, L or O, which are the characters people misread off a screen or a bank statement). depositInstructions is a complete set of US deposit details — a beneficiary name, a bank, a routing number and an account number. We never compose any of these fields ourselves; what you see here is exactly what your contributor should be given, unedited.

depositMessage — quote it, or expect delays

Most collections share ONE deposit account across many references, each distinguished by depositMessage — a code we mint (never chosen by you or your contributor). Your contributor must include it in their transfer (a wire memo, an ACH description) for the deposit to be attributed to this collection. A deposit that arrives without it matches no collection, so it is not credited and does not appear on this collection at any status — it has to be reconciled by hand, or returned to your contributor.

A small number of collections instead get a dedicated account number with no depositMessage at all — in that case the field is simply absent, and any deposit into that account is already unambiguous. Branch on whether the field is present; never assume one shape or the other.

2. Read the fee terms up front

fee on the create response is your own pricing terms — a percentage, a flat amount, and an optional cap — shown before any money has moved. capMinor: null means uncapped. These are TERMS, not a computed amount: nothing has been deposited yet, so there is nothing to compute a real fee against. Once a deposit is attributed to this collection, the actual gross, fee and net appear on a read of the same collection (see below).

3. Read a collection back at any time

GET /v1/collections/:id returns the same shape, refreshed — including the gross, fee and net once a deposit has been attributed:

{
  "id": "a1b2c3d4-0000-4000-8000-000000000001",
  "reference": "DEMO-7K3Q2M",
  "status": "received",
  "currency": "USD",
  "fee": {
    "percentBps": 175,
    "flatMinor": 30,
    "capMinor": null,
    "currency": "USD"
  },
  "grossAmount": "100.00",
  "feeAmount": "1.18",
  "netAmount": "98.82",
  "createdAt": "2026-09-22T17:38:46.915Z"
}

GET /v1/collections?reference=&status=&from=&to= lists your own collections, newest first, filtered by any combination of your own reference, a status, and a creation-time window. Every filter is optional and every result is scoped to your own partner account — a collection you did not open never appears, whatever you search for.

Statuses you will see

What you will never see here

A collection never shows you a token, a chain, or an exchange rate — only a reference, a gross, a fee, a net, and a USD credit. What happens between a deposit landing and your USD balance moving is entirely ours to run.

Errors worth handling

Every code on this route is catalogued in Errors — Collections. The two worth knowing before you build: