---
title: "Open a collection"
method: POST
path: "/v1/collections"
tags: ["Partner API"]
---

# Open a collection

`POST /v1/collections`

## Request

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

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.

## Headers

- `Idempotency-Key` string

## Request body

- PartnerCreateCollectionDto
  - `currency` 'USD', required: Currency a contributor deposits in. Only USD is supported today.
  - `partnerReference` string, 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.
  - `payerLabel` string, required: A human-readable label for your own records — never sent to the contributor.
  - `expectedAmount` string: Advisory only — stored with the collection and never used to refuse a deposit. Decimal string, USD major units, up to 2 decimal places.

## Response `201`

The collection was opened.

- PartnerCollectionResponseDto
  - `id` string, required
  - `reference` string, required
  - `status` 'open' | 'received' | 'crediting' | 'credited' | 'refunded' | 'expired' | 'cancelled', 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.
  - `currency` string, required
  - `partnerReference` string, 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.
  - `label` string, 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.
  - `depositInstructions` PartnerCollectionDepositInstructionsDto
    - `beneficiaryName` string, required
    - `bankName` string, required
    - `routingNumber` string, required
    - `accountNumber` string, required
    - `rails` string[], required: Every inbound rail this ONE account accepts.
    - `depositMessage` string: Present ONLY when this collection shares a deposit account with others (the default). We mint this — never composed by you — and your contributor MUST quote it in their transfer for the deposit to be attributed; omitting it risks a significant delay in processing or the funds being returned. Absent when this collection has a dedicated account, which needs no reference from the contributor.
  - `fee` PartnerCollectionFeeDto, required
    - `percentBps` number, required
    - `flatMinor` number, required
    - `capMinor` number, nullable: NULL means uncapped.
    - `currency` string, required
  - `expectedAmount` string
  - `grossAmount` string
  - `feeAmount` string
  - `netAmount` string
  - `createdAt` string, required

## Other responses

- `400`: INVALID_IDEMPOTENCY_KEY, or an invalid body.
- `404`: PARTNER_NOT_FOUND.
- `409`: PARTNER_SUSPENDED.
- `422`: COLLECTION_CURRENCY_UNSUPPORTED or IDEMPOTENCY_KEY_REUSED.
- `503`: PARTNER_COLLECTIONS_DISABLED, COLLECTIONS_WALLET_NOT_PROVISIONED, or COLLECTIONS_RAIL_UNAVAILABLE.

---

[API](https://skmtc.dev/onlink/apis/onlink-partner-api.md) - [All operations](https://skmtc.dev/onlink/apis/onlink-partner-api/llms.txt) - [OpenAPI document](https://skmtc.dev/onlink/apis/onlink-partner-api/revisions/1d1c6a3671f2?raw)