Create Subscription Link

Create a new card-on-file subscription enrollment link

POST /subscription-links

Create Subscription Link

cURL

curl --request POST \
  --url https://api.example.com/subscription-links \
  --header 'ApiKey: <apikey>' \
  --header 'Content-Type: application/json' \
  --header 'Environment: <environment>' \
  --header 'MerchantId: <merchantid>' \
  --data '
{
  "amount": 5000,
  "currency": "XOF",
  "purchaseReference": "SUB_2024_001",
  "frequency": "monthly",
  "startDate": "2026-08-01",
  "country": "CI",
  "description": "<string>",
  "expirationDate": "2026-12-31T23:59:59.000Z",
  "successUrl": "https://merchant.com/success",
  "failureUrl": "https://merchant.com/failure"
}
'

201

{
  "id": "pl_z1urYtVFgEebtcj8fxp4v",
  "url": "https://pay.hub2.com/pl_z1urYtVFgEebtcj8fxp4v",
  "status": "active",
  "purchaseReference": "ORDER-12345",
  "amount": 1000,
  "currency": "XOF",
  "currentSuccessCount": 0,
  "maximumAttempts": 3,
  "createdAt": "2024-01-15T12:00:00.000Z",
  "updatedAt": "2024-01-15T12:30:00.000Z",
  "expirationDate": "2024-01-15T14:30:00.000Z",
  "customerPhoneNumber": "123456789",
  "type": "single_use",
  "openAmount": false,
  "minAmount": 500,
  "maxAmount": 100000,
  "maximumPayments": 50,
  "customerFields": [
    {
      "fieldName": "national_id",
      "fieldLabel": "National ID",
      "fieldType": "text",
      "isRequired": true,
      "fieldPlaceholder": "<string>"
    }
  ]
}

Headers

ApiKey · string · required

Your api key. To create a key, please get into our dashboard. If you don't have access to it, please reach the Support team.

MerchantId · string · required

Your merchant ID. This information is available in our dashboard. If you don't have access to it, please reach the Support team.

Environment · enum<string> · required

Allow you to choose between the sandbox mode to perform some tests or the live mode for real world transactions.

Available options: live, sandbox

Body

application/json

amount · number · required

Recurring debit amount charged on each occurrence.

Required range: x >= 1

Example:

5000

currency · string · required

Three-letter ISO 4217 currency code

Example:

"XOF"

purchaseReference · string · required

Unique reference for this subscription

Maximum string length: 100

Example:

"SUB_2024_001"

frequency · enum<string> · required

Recurring debit frequency.

Available options: weekly, monthly

Example:

"monthly"

startDate · string · required

ISO-8601 date of the first recurring debit.

Example:

"2026-08-01"

country · string · required

Two-letter ISO 3166-1 alpha-2 country code where the enrollment will be processed

Example:

"CI"

description · string

Description of the subscription link

Maximum string length: 300

expirationDate · string

Expiration date for the enrollment link (ISO 8601 format)

Example:

"2026-12-31T23:59:59.000Z"

successUrl · string

URL to redirect to after successful enrollment

Example:

"https://merchant.com/success"

failureUrl · string

URL to redirect to after failed enrollment

Example:

"https://merchant.com/failure"

Response

201

application/json

Subscription link created successfully

id · string · required

Unique identifier for the payment link

Example:

"pl_z1urYtVFgEebtcj8fxp4v"

url · string · required

URL for the payment link

Example:

"https://pay.hub2.com/pl_z1urYtVFgEebtcj8fxp4v"

status · enum<string> · required

Current status of the payment link

Available options: active, expired, closed, completed

Example:

"active"

purchaseReference · string · required

Merchant reference for the payment

Example:

"ORDER-12345"

amount · object | null · required

Amount intended to be charged in the smallest currency unit. Null when openAmount is true.

Example:

1000

currency · string · required

Three-letter ISO 4217 currency code

Example:

"XOF"

currentSuccessCount · number · required

Number of successful payments recorded for this link

Example:

0

maximumAttempts · number · required

Maximum number of failed payments allowed per user

Example:

3

createdAt · string · required

Creation date in ISO 8601 format

Example:

"2024-01-15T12:00:00.000Z"

updatedAt · string · required

Last update date in ISO 8601 format

Example:

"2024-01-15T12:30:00.000Z"

expirationDate · string · required

Expiration date in ISO 8601 format

Example:

"2024-01-15T14:30:00.000Z"

customerPhoneNumber · string · required

Restricted MSISDN

Example:

"123456789"

type · enum<string> · required

Type of the payment link

Available options: single_use, multi_use, bill_payment

Example:

"single_use"

openAmount · boolean

When true, the payer decides the amount at payment time.

Example:

false

minAmount · number

Minimum amount the payer can enter (only when openAmount is true).

Example:

500

maxAmount · number

Maximum amount the payer can enter (only when openAmount is true).

Example:

100000

maximumPayments · number

Maximum successful payments allowed (omitted when unlimited multi_use)

Example:

50

customerFields · object[]

Custom form fields defined on this payment link. Absent when the link has no customer fields.

Show child attributes