API Reference · Platform

Test Helpers

Test-mode-only routes to simulate payments and bank transfers in. The card, delivery and clock helpers are proposed. In test mode, a saved-card charge or mandate debit for an amount ending in 99 kobo is declined, and the mandate code is 123456.

The test_helper object

Represents a test_helper entity in the rafiqPay system.

Field	Type & Flags	Description
simulated	boolean	Always true in test mode.

Example test_helper JSON

test_helper example payload

{
  "simulated": true,
  "mode": "test"
}

Endpoints & Operations

POST/v1/public/checkout/sessions/:id/bank-transfer/simulateIn plan 035

Simulate a checkout bank transfer

Test mode only. Pretends the customer sent money to the one-time account the checkout opened. Leave out amount to send the right amount; pass a different amount to test a held transfer.

Request Example

POST /v1/public/checkout/sessions/:id/bank-transfer/simulate

cURL · v1

curl -X POST "https://api.rafiqpay.net/v1/public/checkout/sessions/:id/bank-transfer/simulate" \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a" \
  -H "Idempotency-Key: idem_sim-checkout-transfer_01" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "30000.00"
}'

Response (200 OK)

Response payload

{
  "status": "open",
  "chargeStatus": "pending",
  "bankTransfer": null,
  "unmatchedTransfers": [
    {
      "reason": "mismatch",
      "amount": "30000.00",
      "status": "held"
    }
  ]
}

POST/v1/customers/:id/virtual-accounts/simulateIn plan 035

Simulate a transfer to a customer account

Test mode only. Pretends the customer sent money to their test permanent account. It is credited as a charge.

Request Example

POST /v1/customers/:id/virtual-accounts/simulate

cURL · v1

curl -X POST "https://api.rafiqpay.net/v1/customers/:id/virtual-accounts/simulate" \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a" \
  -H "Idempotency-Key: idem_sim-customer-account-transfer_01" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "35000.00"
}'

Response (200 OK)

Response payload

{
  "outcome": "credited"
}

POST/v1/test-helpers/card-authorizationsProposed

Simulate a card purchase

Simulates a POS or web card authorization (including blocked-category testing).

Request Example

POST /v1/test-helpers/card-authorizations

cURL · v1

curl -X POST "https://api.rafiqpay.net/v1/test-helpers/card-authorizations" \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a" \
  -H "Idempotency-Key: idem_sim-card-auth_01" \
  -H "Content-Type: application/json" \
  -d '{
  "cardId": "crd_01",
  "amount": "12000.00",
  "mcc": "5812",
  "merchantName": "Bukka Hut Lekki"
}'

Response (200 OK)

Response payload

{
  "id": "cau_test_01",
  "status": "approved"
}

POST/v1/test-helpers/cards/:id/deliverProposed

Mark a physical card delivered

Marks a physical test card as delivered by courier.

Request Example

POST /v1/test-helpers/cards/:id/deliver

cURL · v1

curl -X POST "https://api.rafiqpay.net/v1/test-helpers/cards/:id/deliver" \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a" \
  -H "Idempotency-Key: idem_sim-card-deliver_01"

Response (200 OK)

Response payload

{
  "id": "crd_01",
  "deliveryStatus": "delivered"
}

POST/v1/test-helpers/clock/advanceProposed

Advance billing time

Advances the test clock to trigger subscription renewals, dunning retries, or 24-hour policy holds.

Request Example

POST /v1/test-helpers/clock/advance

cURL · v1

curl -X POST "https://api.rafiqpay.net/v1/test-helpers/clock/advance" \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a" \
  -H "Idempotency-Key: idem_sim-clock-advance_01" \
  -H "Content-Type: application/json" \
  -d '{
  "advanceByHours": 24
}'

Response (200 OK)

Response payload

{
  "currentTime": "2026-10-21T16:00:00Z"
}