ReloadCard
/Docs

Cards API

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

Create a card

POST /api/v1/cards

Request

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"
  }'

Response 201

{
  "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.

Request

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"
  }'

Response 200

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

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.

Supports idempotency keys — include an Idempotency-Key header with a unique value (e.g., your order ID or a UUID) to safely retry without double-debiting. Cached responses expire after 24 hours.

Request

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"
  }'

Response 200

{
  "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 to prevent duplicate credits.

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

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

Response

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

Disable a card

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

Permanently disables a card. This cannot be undone.

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). The card must be active and unclaimed.

Request

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" }'

Response 200

{
  "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