​
Overview

Users can save Paystack-tokenised cards to their account. A saved card can then be used as a funding source when creating or funding an escrow, or topping up the wallet directly. Cards are stored as Paystack authorization_code tokens — the raw card number is never stored on the platform.

​
Adding a card

Cards are added after a successful Paystack charge initialisation. Your client initiates a charge via the Paystack SDK, and on success Paystack returns an authorization object. Pass that to this endpoint: 
POST /card-add
Authorization: Bearer <token>

{
  "authorization_code": "AUTH_abc123",
  "last4": "4081",
  "brand": "visa",
  "exp_month": "12",
  "exp_year": "2027",
  "bank": "Access Bank",
  "signature": "SIG_xyz789"
}
signature is used for deduplication — if a card with the same signature already exists for this user, the existing record is returned without creating a duplicate.

​
Listing saved cards

GET /card-list
Authorization: Bearer <token>

{
  "success": true,
  "status": 200,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "last4": "4081",
      "brand": "visa",
      "exp_month": "12",
      "exp_year": "2027",
      "bank": "Access Bank",
      "is_default": true
    }
  ]
}
authorization_code and signature are never returned in list responses.

​
Setting a default card

The default card is pre-selected in your UI when a user funds an escrow or tops up without specifying a card: 
PATCH /card-set-default
Authorization: Bearer <token>

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
Only one card can be default at a time. Setting a new default automatically clears the previous one.

​
Deleting a card

DELETE /card-delete?id=<uuid>
Authorization: Bearer <token>
The Paystack token is deactivated and the record is removed. If the deleted card was the default, no card becomes default automatically — the user must set a new one.

​
Using a card to fund an escrow

Pass card_id when funding: 
POST /escrow-fund
Authorization: Bearer <token>

{
  "escrow_id": "<id>",
  "funding_source": "card",
  "card_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
If funding_source is wallet, the card_id field is ignored.