Last updated · May 9, 20266 min read

Cards API

Create, activate, debit, credit, and manage gift cards.

Create a card

POST /api/v1/cards — creates a new card in unactivated state. Use activate next to set the initial balance.

Body parameters

currencyrequired
string
ISO-4217 currency code, e.g. USD, NZD, GBP.
cardTyperequired
string
One of digital, physical.
ownerEmail
string
Optional consumer email; if omitted, the card is unclaimed until POST /cards/:uuid/claim.

Example request

bash

curl -X POST https://merchant.reloadcard.app/api/v1/cards \
  -H "Authorization: Bearer rc_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "cardType": "digital",
    "ownerEmail": "customer@example.com"
  }'

Example response (201)

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "unactivated",
  "balance_cents": 0,
  "currency": "USD",
  "card_type": "digital",
  "created_at": "2026-04-05T10:30:00Z"
}

Activate a card

POST /api/v1/cards/:uuid/activate — sets the initial balance and activates the card. For Shopify merchants, this also creates a Shopify gift card.

Body parameters

amountCentsrequired
integer
Initial balance in minor units, e.g. 5000 for $50.00.
currencyrequired
string
ISO-4217 currency. Must match the card's currency.
consumerEmail
string
Optional. If supplied, claims the card to this consumer.

Example request

bash

curl -X POST https://merchant.reloadcard.app/api/v1/cards/a1b2c3d4/activate \
  -H "Authorization: Bearer rc_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 5000,
    "currency": "USD",
    "consumerEmail": "customer@example.com"
  }'

Debit a card (POS redemption)

POST /api/v1/cards/:uuid/debit — removes balance from a card. Use this when a consumer pays with their gift card at your checkout.

Body parameters

amountCentsrequired
integer
Amount to debit in minor units.
note
string
Free-text note that appears on the consumer's transaction history.
referenceId
string
Your internal reference, e.g. order ID. Stored for reconciliation.

Example request

bash

curl -X POST https://merchant.reloadcard.app/api/v1/cards/a1b2c3d4/debit \
  -H "Authorization: Bearer rc_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1234" \
  -d '{
    "amountCents": 1500,
    "note": "Order #1234",
    "referenceId": "order-1234"
  }'

Example response (200)

json

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "previousBalanceCents": 5000,
  "newBalanceCents": 3500,
  "currency": "USD"
}

Errors

400 — Insufficient balance (response includes balanceCents)
400 — Card not active
404 — Card not found or not yours

Credit a card (add balance)

POST /api/v1/cards/:uuid/credit — adds balance to an active card. Supports idempotency keys via the Idempotency-Key header.

bash

curl -X POST https://merchant.reloadcard.app/api/v1/cards/a1b2c3d4/credit \
  -H "Authorization: Bearer rc_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: loyalty-reward-2026-04-08" \
  -d '{ "amountCents": 2000, "note": "Loyalty reward" }'

Check balance

GET /api/v1/cards/:uuid/balance

bash

curl https://merchant.reloadcard.app/api/v1/cards/a1b2c3d4/balance \
  -H "Authorization: Bearer rc_live_your_key"

Example response

json

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "active",
  "balanceCents": 3500,
  "currency": "USD"
}

Get card details

GET /api/v1/cards/:uuid — returns the card, its current balance, and recent transactions.

bash

curl https://merchant.reloadcard.app/api/v1/cards/a1b2c3d4 \
  -H "Authorization: Bearer rc_live_your_key"

List cards

GET /api/v1/cards — returns a paginated list of cards.

bash

curl "https://merchant.reloadcard.app/api/v1/cards?limit=50&cursor=..." \
  -H "Authorization: Bearer rc_live_your_key"

Disable a card

POST /api/v1/cards/:uuid/disable

bash

curl -X POST https://merchant.reloadcard.app/api/v1/cards/a1b2c3d4/disable \
  -H "Authorization: Bearer rc_live_your_key"

Claim a pre-loaded card

POST /api/v1/cards/:uuid/claim — assigns a pre-loaded card to a consumer by email. Use this for cards that were activated with a balance but have no owner yet (e.g. pre-loaded denomination cards sold at POS).

Body parameters

emailrequired
string
Consumer's email address. The consumer is invited via magic link.

bash

curl -X POST https://merchant.reloadcard.app/api/v1/cards/a1b2c3d4/claim \
  -H "Authorization: Bearer rc_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "email": "customer@example.com" }'

Example response

json

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "customer@example.com",
  "balanceCents": 5000,
  "expiresOn": "2029-04-08"
}

Errors

400 — Card is not active
409 — Card already claimed by another consumer
404 — Card not found or not yours