Refunds

Refund a settled collection back to the payer. You identify the collection by its provider_event_id, request the refund, and Swappr returns the funds to the original payer. Your wallet is debited the full original amount when the refund settles.

Available for GBP and EUR collections.

How a refund works

A refund is the reverse of a collection: the money you collected goes back to whoever paid it. You do not supply the payer’s bank details, Swappr already knows where the collection came from and returns it to that source.

Two things are worth designing around:

• You reference the collection, not a payer. The only identifier you send is provider_event_id, the value delivered as providerEventId on the wallet_funded webhook you received when the collection credited your wallet. Store that id when you receive the webhook and you have everything you need to refund later.
• One refund per collection. A collection can be refunded once. A second attempt returns 409, so a retry after a dropped response tells you the refund already exists rather than making a new one.

Before you refund

• Enable the capability on your key. The API key must carry the refunds capability, enable Refunds on the key under API keys. A key without it gets 403 forbidden_refund_create. This is a property of the key itself, so it keeps working regardless of later changes to the team member who created it.
• The collection must belong to you. A provider_event_id for a collection in another account, or in the other environment, returns the same 404 as one that does not exist.
• Idempotency-Key is required. Send a unique value per logical refund. Because only one refund is possible per collection, a repeat of the same refund returns 409 refund_already_exists.

curl -X POST 'https://api.swappr.me/api/v1/refunds' \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_event_id": "evt_abc123",
    "reason": "Duplicate payment",
    "reference": "RFND-4021"
  }'

import { randomUUID } from 'crypto';
 
async function refundCollection(providerEventId: string) {
  const res = await fetch('https://api.swappr.me/api/v1/refunds', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SWAPPR_API_KEY}`,
      'Idempotency-Key': randomUUID(),
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      provider_event_id: providerEventId,   // from the wallet_funded webhook
      reason: 'Duplicate payment',
      reference: 'RFND-4021',
    }),
  });
  return res.json();
}

import os, uuid, requests
 
def refund_collection(provider_event_id: str):
    res = requests.post(
        'https://api.swappr.me/api/v1/refunds',
        headers={
            'Authorization': f"Bearer {os.environ['SWAPPR_API_KEY']}",
            'Idempotency-Key': str(uuid.uuid4()),
        },
        json={
            'provider_event_id': provider_event_id,  # from the wallet_funded webhook
            'reason': 'Duplicate payment',
            'reference': 'RFND-4021',
        },
    )
    res.raise_for_status()
    return res.json()

{
  "object": "refund",
  "id": "clx9r3q0000xyz789ghi012",
  "status": "processing",
  "provider_event_id": "evt_abc123",
  "amount_minor": "150000",
  "currency": "GBP",
  "reference": "RFND-4021",
  "reason": "Duplicate payment",
  "created_at": "2026-08-14T10:15:00.000Z",
  "updated_at": "2026-08-14T10:15:00.000Z"
}

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

{
  "object": "refund",
  "id": "clx9r3q0000xyz789ghi012",
  "status": "successful",
  "provider_event_id": "evt_abc123",
  "amount_minor": "150000",
  "currency": "GBP",
  "reference": "RFND-4021",
  "reason": "Duplicate payment",
  "created_at": "2026-08-14T10:15:00.000Z",
  "updated_at": "2026-08-14T10:47:00.000Z"
}