Sign in

v1

latestOpenAPI 3.0.12026-07-225791279.7 KB
Subscriptions

Create Subscription

This endpoint creates a new subscription for a customer, enrolls the customer's card, and initiates the first payment where applicable.

Important Notes

  • cardDetails is mandatory when creating a subscription.
  • If no trial period is configured, the first charge is attempted immediately after the card is enrolled.
  • If a trial period is configured, the subscription is created with a status of TRIALING. The card is enrolled immediately, but the first charge is deferred until the trial period ends.
  • When additional customer authentication is required, the subscription is created with a status of REQUIRES_ACTION, and the response includes the 3D Secure challenge details.
  • Creating another active subscription using the same customerEmail returns a 409 Conflict response.
  • Before the first successful payment, the subscription remains in the INCOMPLETE state.
  • The card service determines the charge mode (DIRECT_CHARGE, TOKENIZATION, or AGREEMENT_BASED) during card enrollment and returns it in the response. The subscription service stores this value for future recurring billing.
post/subscription/api/v1/subscriptions

Request body

customerEmailstring email required

The customer's email address. Used to identify the customer's subscription. An email address can only have one active subscription per plan.

planCodestring required

The unique plan code generated when the subscription plan was created. If omitted, a plan is automatically created from the request.

Example request

{
  "customerEmail": "johndoe@gmail.com",
  "planCode": "PLN_906FE4B",
  "cardDetails": {
    "cardNumber": "554656xxxxxx742",
    "expiryMonth": "01",
    "expiryYear": "02",
    "securityCode": "123",
    "cardHolderName": "John Doe",
    "present": true
  }
}

Response

Subscription Created

successboolean

Indicates if the request was successful.

messagestring

Descriptive message regarding the subscription creation status.

Example response

{
  "success": true,
  "message": "Subscription created",
  "data": {
    "subscription": {
      "id": 20,
      "customerId": "null",
      "customerEmail": "johndoe@gmail.com",
      "status": "ACTIVE",
      "currentPeriodStart": "2026-07-08T19:35:52.348327",
      "currentPeriodEnd": "2026-08-08T19:35:55.569925",
      "nextChargeDate": "2026-08-08T19:35:55.569925",
      "connectionMode": "Live",
      "enrollmentReference": "SUBREF_BFE417ABF6FF49A985",
      "enrollmentTxnReference": "SUB_ENROLL_20_1783539352354",
      "chargeMode": "DIRECT_CHARGE",
      "createdAt": "2026-07-08T19:35:52.34833",
      "updatedAt": "2026-07-08T19:35:55.573662",
      "enrollConfirmed": true
    },
    "chargeResult": {
      "charged": true,
      "status": "SUCCESS",
      "amount": 100,
      "currency": "NGN",
      "transactionReference": "SUB_ENROLL_20_1783539352354",
      "authCode": "581032",
      "chargeMode": "DIRECT_CHARGE",
      "message": "Approved"
    }
  }
}