Collections

Collect money from your payers over open banking. You open a collection, Swappr returns a checkout_url, and your payer completes the payment inside their own bank. When it settles, the amount is credited to your wallet in that currency.

Available in GBP and EUR.

How it differs from a virtual account

A virtual account is a standing bank account you hand out once, and anything paid into it is yours because the account number identifies you. A collection is the opposite shape: it is opened per payment, for a specific amount, and it is Swappr’s record of that collection — not the account the money lands in — that routes the funds to your wallet.

Two things follow from that, and both are worth designing around:

• The checkout_url is the deliverable. Creating a collection does not move money; it produces a link. Surface it however suits you — redirect the payer, put it in an invoice, render it behind a button.
• The destination wallet is fixed when the collection is opened. It is not re-derived at settlement, so the funds land where you expected even if your account configuration changes while the payer is paying.

Before you collect

• Enable the capability on your key. The API key must carry the collections capability — enable Create collections on the key under API keys. A key without it gets 403 forbidden_collection_create. This is a property of the key itself, so it keeps working regardless of later changes to the team member who created it.
• You need a wallet in that currency. Collections credit an existing GBP or EUR wallet. If you hold no wallet in the currency, the request is rejected — there is no separate enrolment step beyond having the wallet.
• Idempotency-Key is required. A retry with the same key returns the same collection and the same checkout_url. That matters more here than elsewhere: a payer may already be part-way through paying, and a second checkout would leave one of them stranded.
• There is a minimum amount. A collection must be worth more than it costs to collect — see Minimum amount.

# Collect £1,500.00 (150000 minor) from a payer
curl -X POST 'https://api.swappr.me/api/v1/collections' \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_minor": "150000",
    "currency": "GBP",
    "redirect_url": "https://merchant.example/collections/return",
    "narration": "Invoice 4021",
    "reference": "INV-4021"
  }'

import { randomUUID } from 'crypto';
 
async function openCollection() {
  const res = await fetch('https://api.swappr.me/api/v1/collections', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SWAPPR_API_KEY}`,
      'Idempotency-Key': randomUUID(),
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount_minor: '150000',           // £1,500.00
      currency: 'GBP',
      redirect_url: 'https://merchant.example/collections/return',
      narration: 'Invoice 4021',
      reference: 'INV-4021',
    }),
  });
  const collection = await res.json();
  // Send your payer here.
  return collection.checkout_url;
}

import os, uuid, requests
 
def open_collection():
    res = requests.post(
        'https://api.swappr.me/api/v1/collections',
        headers={
            'Authorization': f"Bearer {os.environ['SWAPPR_API_KEY']}",
            'Idempotency-Key': str(uuid.uuid4()),
        },
        json={
            'amount_minor': '150000',   # £1,500.00
            'currency': 'GBP',
            'redirect_url': 'https://merchant.example/collections/return',
            'narration': 'Invoice 4021',
            'reference': 'INV-4021',
        },
    )
    res.raise_for_status()
    # Send your payer here.
    return res.json()['checkout_url']

{
  "object": "collection",
  "id": "clx8k2p0000abc123def456",
  "reference": "INV-4021",
  "amount_minor": "150000",
  "settled_amount_minor": null,
  "currency": "GBP",
  "status": "awaiting_user",
  "checkout_url": "https://checkout.example/c/01KZ4M8N2P",
  "expires_at": "2026-07-29T15:25:00.000Z",
  "settled_at": null,
  "settlement_rail": null,
  "failure_code": null,
  "failure_message": null,
  "env": "live",
  "metadata": null,
  "created_at": "2026-07-29T15:00:00.000Z"
}

Lifecycle

A collection moves through these states. Only settled means money reached you.

Knowing when it settles

You do not need to poll. A settled collection credits your wallet and fires the standard wallet_funded webhook, which is the same event a virtual-account credit produces — so if you already handle wallet funding, settlement is already wired.

settled_amount_minor is the authoritative figure for what arrived, and it can differ from amount_minor. Reconcile on the settled amount, not the requested one.

Minimum amount

Collecting money costs money, and that cost does not scale to zero. A collection small enough that the cost swallows it can complete successfully while leaving nothing to credit — so Swappr refuses to open one, rather than letting your payer pay for a transfer that delivers nothing.

If the amount is too small you get 422 amount_below_minimum, and the error tells you both figures:

{
  "error": {
    "type": "invalid_request_error",
    "code": "amount_below_minimum",
    "message": "amount_minor 100 is not greater than the provider cost 500 for a GBP collection, so the collection could settle without the funds ever arriving. The minimum accepted amount_minor is 501.",
    "field": "amount_minor",
    "detail": {
      "provider_cost_minor": "500",
      "minimum_amount_minor": "501"
    }
  }
}

Read detail.minimum_amount_minor rather than deriving it — the cost is not always a flat figure, so the minimum is not always “cost plus one”.

curl 'https://api.swappr.me/api/v1/collections/clx8k2p0000abc123def456' \
  -H "Authorization: Bearer sk_live_..."

curl 'https://api.swappr.me/api/v1/collections?status=settled&currency=GBP&limit=20' \
  -H "Authorization: Bearer sk_live_..."

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "collection",
      "id": "clx8k2p0000abc123def456",
      "reference": "INV-4021",
      "amount_minor": "150000",
      "settled_amount_minor": "150000",
      "currency": "GBP",
      "status": "settled",
      "checkout_url": "https://checkout.example/c/01KZ4M8N2P",
      "expires_at": "2026-07-29T15:25:00.000Z",
      "settled_at": "2026-07-29T15:11:42.000Z",
      "settlement_rail": "bacs",
      "failure_code": null,
      "failure_message": null,
      "env": "live",
      "metadata": null,
      "created_at": "2026-07-29T15:00:00.000Z"
    }
  ]
}

Sandbox

A sandbox (sk_test_…) key opens sandbox collections against your sandbox wallets; a live key opens live ones. The two are entirely separate — a sandbox key can neither see nor create a live collection, and Idempotency-Key values are namespaced per environment.