API Reference · Billing

Subscriptions

Recurring customer subscriptions on flat or per-seat plans, with zero-penalty dunning.

The subscription object

Represents a subscription entity in the rafiqPay system.

Field	Type & Flags	Description
id	string	Subscription ID (sub_...).
customerId	string	Customer ID.
status	enum	trialing \| active \| past_due \| paused \| canceled.
collectionMethod	enum	send_invoice \| card \| mandate. How each period’s invoice is collected.
paymentMethodId	stringNullable	The saved card charged each period (card).
mandateId	stringNullable	The mandate debited each period (mandate).

Example subscription JSON

subscription example payload

{
  "id": "sub_01",
  "customerId": "cus_amina_01",
  "priceId": "price_kanzu_pro",
  "status": "active",
  "collectionMethod": "card",
  "paymentMethodId": "pm_01J9KANZU3",
  "mandateId": null
}

Endpoints & Operations

POST/v1/billing/subscriptionsIn plan 035

Create a subscription

Starts a new subscription. Each period the invoice is made, then collected by collectionMethod. If a card or mandate charge fails, or there is no card yet, the invoice is emailed instead. The card or mandate must be this customer’s (the same email) and in the same mode.

Request Parameters

Parameter	Type	Requirement	Description
collectionMethod	enum	Optional	send_invoice (default) \| card \| mandate.
paymentMethodId	string	Optional	For card: the saved card (pm_...) to charge. Leave it out to ask the customer to save one when they pay the first invoice.
mandateId	string	Optional	For mandate: required. An active mandate (mnd_...) of this customer.

Request Example

POST /v1/billing/subscriptions

cURL · v1

curl -X POST "https://api.rafiqpay.net/v1/billing/subscriptions" \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a" \
  -H "Idempotency-Key: idem_create-subscription_01" \
  -H "Content-Type: application/json" \
  -d '{
  "customerId": "cus_amina_01",
  "customerEmail": "amina@kanzu.ng",
  "planId": "plan_kanzu_pro",
  "collectionMethod": "mandate",
  "mandateId": "mnd_01J9KANZU"
}'

Response (200 OK)

Response payload

{
  "id": "sub_01",
  "status": "active",
  "collectionMethod": "mandate",
  "mandateId": "mnd_01J9KANZU"
}

GET/v1/subscriptions/:idProposed

Retrieve a subscription

Retrieves a subscription.

Request Example

GET /v1/subscriptions/:id

cURL · v1

curl -X GET "https://api.rafiqpay.net/v1/subscriptions/:id" \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a"

Response (200 OK)

Response payload

{
  "id": "sub_01",
  "status": "active"
}

PATCH/v1/subscriptions/:idProposed

Change price or seats

Updates plan or seat quantity.

Request Example

PATCH /v1/subscriptions/:id

cURL · v1

curl -X PATCH "https://api.rafiqpay.net/v1/subscriptions/:id" \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a" \
  -H "Content-Type: application/json" \
  -d '{
  "quantity": 12
}'

Response (200 OK)

Response payload

{
  "id": "sub_01",
  "quantity": 12
}

GET/v1/subscriptionsProposed

List subscriptions

Lists subscriptions.

Request Example

GET /v1/subscriptions

cURL · v1

curl -X GET "https://api.rafiqpay.net/v1/subscriptions" \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a"

Response (200 OK)

Response payload

{
  "object": "list",
  "data": [],
  "hasMore": false,
  "nextCursor": null
}

POST/v1/subscriptions/:id/pauseProposed

Pause a subscription

Pauses billing collection.

Request Example

POST /v1/subscriptions/:id/pause

cURL · v1

curl -X POST "https://api.rafiqpay.net/v1/subscriptions/:id/pause" \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a" \
  -H "Idempotency-Key: idem_pause-subscription_01"

Response (200 OK)

Response payload

{
  "id": "sub_01",
  "status": "paused"
}

POST/v1/subscriptions/:id/resumeProposed

Resume a subscription

Resumes a paused subscription.

Request Example

POST /v1/subscriptions/:id/resume

cURL · v1

curl -X POST "https://api.rafiqpay.net/v1/subscriptions/:id/resume" \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a" \
  -H "Idempotency-Key: idem_resume-subscription_01"

Response (200 OK)

Response payload

{
  "id": "sub_01",
  "status": "active"
}

POST/v1/subscriptions/:id/cancelProposed

Cancel a subscription

Cancels a subscription.

Request Example

POST /v1/subscriptions/:id/cancel

cURL · v1

curl -X POST "https://api.rafiqpay.net/v1/subscriptions/:id/cancel" \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a" \
  -H "Idempotency-Key: idem_cancel-subscription_01"

Response (200 OK)

Response payload

{
  "id": "sub_01",
  "status": "canceled"
}

POST/v1/subscriptions/:id/retryProposed

Retry a past-due renewal now

Immediately retries collection on a past_due subscription.

Request Example

POST /v1/subscriptions/:id/retry

cURL · v1

curl -X POST "https://api.rafiqpay.net/v1/subscriptions/:id/retry" \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a" \
  -H "Idempotency-Key: idem_retry-subscription_01"

Response (200 OK)

Response payload

{
  "id": "sub_01",
  "status": "active"
}

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

subscription.created subscription.renewed subscription.trial_ending subscription.past_due subscription.paused subscription.resumed subscription.canceled

Subscriptions

The subscription object

Endpoints & Operations

Create a subscription

Retrieve a subscription

Change price or seats

List subscriptions

Pause a subscription

Resume a subscription

Cancel a subscription

Retry a past-due renewal now

Related Webhook Events