rafiqPay
Developers
API Reference · Payments

Saved Cards (Payment Methods)

Cards customers saved with your business at checkout, with their consent. Charge one without the customer present. The card number and the token used to charge it are never returned.

The payment_method object

Represents a payment_method entity in the rafiqPay system.

FieldType & FlagsDescription
id
string
Payment method ID (pm_...).
type
enum
card.
status
enum
active | removed. A removed card can never be charged again.
brand
stringNullable
Card brand, for example Visa or Mastercard.
last4
stringNullable
Last four digits of the card.
expiry
stringNullable
MM/YY.
customerEmail
string
The email of the customer who saved it.
customerId
stringNullable
The customer record, when there is one.
consentedAt
string
When the customer agreed to save the card (ISO 8601).
createdAt
string
When the card was saved (ISO 8601).
Example payment_method JSON
payment_method example payload
{
  "id": "pm_01J9KANZU3",
  "object": "payment_method",
  "type": "card",
  "status": "active",
  "brand": "Visa",
  "last4": "4081",
  "expiry": "09/28",
  "customerEmail": "amina@kanzu.ng",
  "customerId": "cus_amina_01",
  "consentedAt": "2026-11-07T10:15:00.000Z",
  "createdAt": "2026-11-07T10:15:04.000Z"
}

Endpoints & Operations

GET/v1/payment-methodsIn plan 035

List saved cards

Lists active saved cards, newest first (up to 100).

Request Parameters
ParameterTypeRequirementDescription
customerEmailstringOptionalOnly cards saved by this email.
customerIdstringOptionalOnly cards of this customer.
modeenumOptionallive | test. Defaults to live.
Request Example
GET /v1/payment-methods
cURL · v1
curl -X GET "https://api.rafiqpay.net/v1/payment-methods" \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a"
Response (200 OK)
Response payload
{
  "object": "list",
  "data": [
    {
      "id": "pm_01J9KANZU3",
      "type": "card",
      "brand": "Visa",
      "last4": "4081"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
GET/v1/payment-methods/:idIn plan 035

Retrieve a saved card

Retrieves one saved card.

Request Example
GET /v1/payment-methods/:id
cURL · v1
curl -X GET "https://api.rafiqpay.net/v1/payment-methods/:id" \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a"
Response (200 OK)
Response payload
{
  "id": "pm_01J9KANZU3",
  "object": "payment_method",
  "type": "card",
  "status": "active",
  "brand": "Visa",
  "last4": "4081",
  "expiry": "09/28"
}
POST/v1/payment-methods/:id/chargesIn plan 035

Charge a saved card

Charges the card without the customer present. A declined card is a failed charge. A pending charge is checked again by rafiqPay, and charge.succeeded is sent when it settles. The usual fee applies.

Request Parameters
ParameterTypeRequirementDescription
amountstringRequiredDecimal Naira amount, at least "100.00".
descriptionstringOptionalWhat the charge is for (up to 140 characters).
orderReferencestringOptionalYour own order number (up to 120 characters).
Request Example
POST /v1/payment-methods/:id/charges
cURL · v1
curl -X POST "https://api.rafiqpay.net/v1/payment-methods/:id/charges" \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a" \
  -H "Idempotency-Key: idem_charge-payment-method_01" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "15000.00",
  "description": "Arabic Intensive, November",
  "orderReference": "KANZU-1107"
}'
Response (200 OK)
Response payload
{
  "status": "succeeded",
  "failureReason": null,
  "charge": {
    "id": "pay_01J9KANZU915",
    "object": "charge",
    "reference": "RP-C70412883A1F2",
    "status": "succeeded",
    "method": "card",
    "currency": "NGN",
    "amount": "15000.00",
    "fee": "225.00",
    "net": "14775.00"
  }
}
DELETE/v1/payment-methods/:idIn plan 035

Remove a saved card

Removes the card for good. It can never be charged again. A subscription using it goes back to emailed invoices.

Request Example
DELETE /v1/payment-methods/:id
cURL · v1
curl -X DELETE "https://api.rafiqpay.net/v1/payment-methods/:id" \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a"
Response (200 OK)
Response payload
{
  "id": "pm_01J9KANZU3",
  "object": "payment_method",
  "status": "removed"
}

Related Webhook Events

These events are dispatched to your webhook endpoints when actions occur on this resource:

payment_method.savedpayment_method.removedcharge.succeeded