---
title: "Create Subscription Link"
method: POST
path: "/subscription-links"
tags: ["Subscription Links"]
---

# Create Subscription Link

`POST /subscription-links`

## Request

- The document declares no server URL.
- Auth: none declared. Required headers: `ApiKey`, `MerchantId`, `Environment`

Create a new card-on-file subscription enrollment link

## Headers

- `ApiKey` string, required
- `MerchantId` string, required
- `Environment` 'live' | 'sandbox', required

## Request body

- CreateSubscriptionLinkDto
  - `amount` number, required: Recurring debit amount charged on each occurrence.
  - `currency` string, required: Three-letter ISO 4217 currency code
  - `purchaseReference` string, required: Unique reference for this subscription
  - `frequency` 'weekly' | 'monthly', required: Recurring debit frequency.
  - `startDate` string, required: ISO-8601 date of the first recurring debit.
  - `country` string, required: Two-letter ISO 3166-1 alpha-2 country code where the enrollment will be processed
  - `description` string: Description of the subscription link
  - `expirationDate` string: Expiration date for the enrollment link (ISO 8601 format)
  - `successUrl` string: URL to redirect to after successful enrollment
  - `failureUrl` string: URL to redirect to after failed enrollment

## Response `201`

Subscription link created successfully

- PaymentLinkDto
  - `id` string, required: Unique identifier for the payment link
  - `url` string, required: URL for the payment link
  - `status` 'active' | 'expired' | 'closed' | 'completed', required: Current status of the payment link
  - `purchaseReference` string, required: Merchant reference for the payment
  - `amount` object, nullable, required: Amount intended to be charged in the smallest currency unit. Null when openAmount is true.
  - `openAmount` boolean: When true, the payer decides the amount at payment time.
  - `minAmount` number: Minimum amount the payer can enter (only when openAmount is true).
  - `maxAmount` number: Maximum amount the payer can enter (only when openAmount is true).
  - `currency` string, required: Three-letter ISO 4217 currency code
  - `maximumPayments` number: Maximum successful payments allowed (omitted when unlimited multi_use)
  - `currentSuccessCount` number, required: Number of successful payments recorded for this link
  - `maximumAttempts` number, required: Maximum number of failed payments allowed per user
  - `createdAt` string, required: Creation date in ISO 8601 format
  - `updatedAt` string, required: Last update date in ISO 8601 format
  - `expirationDate` string, required: Expiration date in ISO 8601 format
  - `customerPhoneNumber` string, required: Restricted MSISDN
  - `type` 'single_use' | 'multi_use' | 'bill_payment', required: Type of the payment link
  - `providers` string[]: Mobile money providers the link offers. A provider listed at creation that is not enabled in the country for a method the link offers, or that the routing check refused for the merchant, is missing here. Absent on a card-only link.
  - `customerFields` CustomerFieldDto[]: Custom form fields defined on this payment link. Absent when the link has no customer fields.
    - `fieldName` string, required: Field identifier in snake_case
    - `fieldLabel` string, required: Human-readable label shown to the payer
    - `fieldPlaceholder` string: Optional input placeholder text
    - `fieldType` 'text' | 'integer' | 'decimal' | 'email' | 'date', required: Expected value type for validation and input rendering
    - `isRequired` boolean, required: Whether the payer must fill this field before proceeding

## Other responses

- `400`: Bad Request
- `401`: Wrong credentials
- `403`: Forbidden
- `409`: Invalid request
- `429`: ThrottlerException: Too Many Requests
- `500`: Internal error
- `503`: Service unavailable

## Changes

- **2026-11-03** `f6d3f87df5e0`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/hub2/apis/hub2-service-api/changes/subscription-links/post.md)

---

[API](https://skmtc.dev/hub2/apis/hub2-service-api.md) - [All operations](https://skmtc.dev/hub2/apis/hub2-service-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hub2/apis/hub2-service-api/revisions/f6d3f87df5e0?raw)