v1

latestOpenAPI 3.0.12026-07-225791279.7 KB

Subscription Charge

Create Custom Charge

This endpoint processes an off-cycle or custom charge for an active subscription.

Notes:

By default, countsAsCycle is false.

When countsAsCycle is false, the subscription's billing cycle remains unchanged.

Set countsAsCycle to true if the custom charge should be treated as a scheduled billing cycle.

post/subscription/api/v1/subscriptions/{id}/charge-custom

Path parameters

idstring required

The Plan ID.

Request body

amountnumber double required

The amount to be charged.

currencystring required

The 3-letter ISO currency code.

descriptionstring required

A brief description or reason for the one-off charge.

idempotencyKeystring

A Unique identifier used to prevent duplicate charge requests.

countsAsCycleboolean

Indicates whether this charge should count as a normal subscription billing cycle. Defaults to false.

Example request

{
  "amount": 1500,
  "currency": "NGN",
  "description": "Additional Storage",
  "idempotencyKey": "OFFCYCLE-001"
}

Response

Funding Successful

successboolean

Indicates if the request was successful.

messagestring

Descriptive message regarding the charge operation.

Example response

{
  "success": true,
  "message": "Custom charge completed",
  "data": {
    "status": "SUCCESS",
    "transactionReference": "OFFCYCLE_1782788822736",
    "amount": 1500,
    "currency": "NGN",
    "chargeMode": "DIRECT_CHARGE",
    "message": "Charge completed successfully.",
    "three_ds_url": "https://3ds.gateway.com/acs/...",
    "three_ds_html": "<form ...></form>"
  }
}