> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hub2.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Subscription Link

> Create a new card-on-file subscription enrollment link



## OpenAPI

````yaml post /subscription-links
openapi: 3.0.0
info:
  title: Hub2 Service · Api
  description: |-
    This is the Hub2 api reference |
          Please check https://docs.hub2.io/ for the full documentation |
          Rate limits of endpoints are here : https://docs.hub2.io/en/details/limits.html.
  version: 2.185.0
  contact:
    name: Hub2
    url: https://www.hub2.io/
    email: contact@hub2.io
servers: []
security: []
tags:
  - name: Payments
    description: >-
      Best known as the PAY-IN API, it provides endpoints for merchants to
      perform Hub2 PAY-IN transactions.
  - name: Transfers
    description: >-
      Best known as the PAY-OUT API, it provides endpoints for merchants to
      perform Hub2 PAY-OUT transactions.
  - name: IRT
    description: International Remittance Transfers
  - name: Balance
    description: ''
  - name: Webhooks
    description: ''
  - name: Provisioning
    description: ''
  - name: Payment on Terminal
    description: ''
  - name: Receipt
    description: ''
  - name: Sms
    description: ''
  - name: Data
    description: ''
  - name: Compliance
    description: ''
  - name: Recipient
    description: ''
  - name: Delegation
    description: ''
  - name: Deposits
    description: ''
  - name: Payment Links
    description: ''
  - name: Subscription Links
    description: ''
  - name: Submerchants
    description: ''
  - name: Bill Payments
    description: ''
  - name: Subscriptions
    description: ''
  - name: Subscription Intents
    description: >-
      Enrolls a customer in card-on-file recurring debits and tracks how each
      enrollment ended.
  - name: Instant Payment
    description: >-
      Instant payment (PI SPI, BCEAO) resources, such as the aliases naming your
      accounts in the national directory.
paths:
  /subscription-links:
    post:
      tags:
        - Subscription Links
      summary: Create Subscription Link
      description: Create a new card-on-file subscription enrollment link
      operationId: SubscriptionLinkController_createSubscriptionLink
      parameters:
        - name: ApiKey
          in: header
          description: >-
            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.
          required: true
          schema:
            type: string
        - name: MerchantId
          in: header
          description: >-
            Your merchant ID. This information is available in our dashboard. If
            you don't have access to it, please reach the Support team.
          required: true
          schema:
            type: string
        - name: Environment
          in: header
          description: >-
            Allow you to choose between the sandbox mode to perform some tests
            or the live mode for real world transactions.
          required: true
          schema:
            type: string
            enum:
              - live
              - sandbox
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionLinkDto'
      responses:
        '201':
          description: Subscription link created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentLinkDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiBadRequestErrorAlias'
        '401':
          description: Wrong credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiUnauthorizedErrorAlias'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiForbiddenRequestErrorAlias'
        '409':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiInvalidRequestErrorAlias'
        '429':
          description: 'ThrottlerException: Too Many Requests'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiTooManyRequestErrorAlias'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiInternalErrorAlias'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiUpstreamErrorAlias'
components:
  schemas:
    CreateSubscriptionLinkDto:
      type: object
      properties:
        amount:
          type: number
          description: Recurring debit amount charged on each occurrence.
          example: 5000
          minimum: 1
        currency:
          type: string
          description: Three-letter ISO 4217 currency code
          example: XOF
        purchaseReference:
          type: string
          description: Unique reference for this subscription
          example: SUB_2024_001
          maxLength: 100
        frequency:
          type: string
          description: Recurring debit frequency.
          enum:
            - weekly
            - monthly
          example: monthly
        startDate:
          type: string
          description: ISO-8601 date of the first recurring debit.
          example: '2026-08-01'
        country:
          type: string
          description: >-
            Two-letter ISO 3166-1 alpha-2 country code where the enrollment will
            be processed
          example: CI
        description:
          type: string
          description: Description of the subscription link
          maxLength: 300
        expirationDate:
          type: string
          description: Expiration date for the enrollment link (ISO 8601 format)
          example: '2026-12-31T23:59:59.000Z'
        successUrl:
          type: string
          description: URL to redirect to after successful enrollment
          example: https://merchant.com/success
        failureUrl:
          type: string
          description: URL to redirect to after failed enrollment
          example: https://merchant.com/failure
      required:
        - amount
        - currency
        - purchaseReference
        - frequency
        - startDate
        - country
    PaymentLinkDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the payment link
          example: pl_z1urYtVFgEebtcj8fxp4v
        url:
          type: string
          description: URL for the payment link
          example: https://pay.hub2.com/pl_z1urYtVFgEebtcj8fxp4v
        status:
          type: string
          description: Current status of the payment link
          enum:
            - active
            - expired
            - closed
            - completed
          example: active
        purchaseReference:
          type: string
          description: Merchant reference for the payment
          example: ORDER-12345
        amount:
          type: object
          description: >-
            Amount intended to be charged in the smallest currency unit. Null
            when openAmount is true.
          example: 1000
          nullable: true
        openAmount:
          type: boolean
          description: When true, the payer decides the amount at payment time.
          example: false
        minAmount:
          type: number
          description: Minimum amount the payer can enter (only when openAmount is true).
          example: 500
        maxAmount:
          type: number
          description: Maximum amount the payer can enter (only when openAmount is true).
          example: 100000
        currency:
          type: string
          description: Three-letter ISO 4217 currency code
          example: XOF
        maximumPayments:
          type: number
          description: >-
            Maximum successful payments allowed (omitted when unlimited
            multi_use)
          example: 50
        currentSuccessCount:
          type: number
          description: Number of successful payments recorded for this link
          example: 0
        maximumAttempts:
          type: number
          description: Maximum number of failed payments allowed per user
          example: 3
        createdAt:
          type: string
          description: Creation date in ISO 8601 format
          example: '2024-01-15T12:00:00.000Z'
        updatedAt:
          type: string
          description: Last update date in ISO 8601 format
          example: '2024-01-15T12:30:00.000Z'
        expirationDate:
          type: string
          description: Expiration date in ISO 8601 format
          example: '2024-01-15T14:30:00.000Z'
        customerPhoneNumber:
          type: string
          description: Restricted MSISDN
          example: '123456789'
        type:
          type: string
          description: Type of the payment link
          enum:
            - single_use
            - multi_use
            - bill_payment
          example: single_use
        customerFields:
          description: >-
            Custom form fields defined on this payment link. Absent when the
            link has no customer fields.
          type: array
          items:
            $ref: '#/components/schemas/CustomerFieldDto'
      required:
        - id
        - url
        - status
        - purchaseReference
        - amount
        - currency
        - currentSuccessCount
        - maximumAttempts
        - createdAt
        - updatedAt
        - expirationDate
        - customerPhoneNumber
        - type
    ApiBadRequestErrorAlias:
      type: object
      properties:
        status:
          type: number
          description: HTTP error code.
          example: 400
        error:
          description: HTTP error description.
          allOf:
            - $ref: '#/components/schemas/InternalApiBadRequestError'
      required:
        - status
        - error
    ApiUnauthorizedErrorAlias:
      type: object
      properties:
        status:
          type: number
          description: HTTP error code.
          example: 401
        error:
          description: HTTP error description.
          allOf:
            - $ref: '#/components/schemas/InternalApiUnauthorizedError'
      required:
        - status
        - error
    ApiForbiddenRequestErrorAlias:
      type: object
      properties:
        status:
          type: number
          description: status
          enum:
            - 403
          example: 403
        error:
          description: Error object
          allOf:
            - $ref: '#/components/schemas/ForbiddenErrorObject'
      required:
        - status
        - error
    ApiInvalidRequestErrorAlias:
      type: object
      properties:
        httpStatus:
          type: number
          description: Http status
          enum:
            - 409
          example: 409
        type:
          type: string
          description: Error type
          example: invalid_request
        code:
          type: string
          description: Error code
          enum:
            - unsupported_action
          example: unsupported_action
        message:
          type: string
          description: Error message
          example: This action is not supported
      required:
        - httpStatus
        - type
        - code
        - message
    ApiTooManyRequestErrorAlias:
      type: object
      properties:
        status:
          type: number
          description: status
          enum:
            - 429
          example: 429
        error:
          type: string
          description: Error
          example: 'ThrottlerException: Too Many Requests'
      required:
        - status
        - error
    ApiInternalErrorAlias:
      type: object
      properties:
        type:
          type: string
          description: The type of this error.
          example: internal_error
        code:
          type: string
          description: The error code for this error.
          example:
            - internal_error
            - wrong_credentials
            - not_granted
            - live_mode_not_granted
        message:
          type: string
          description: The error message describing what happens to throw this error.
          example: An error occurred on our system. Please try again later.
      required:
        - type
        - code
        - message
    ApiUpstreamErrorAlias:
      type: object
      properties:
        status:
          type: number
          description: HTTP status.
          enum:
            - 502
            - 503
          example: 503
        code:
          type: string
          description: >-
            The error code. 503: `instant_payment_alias_rail_unavailable`,
            `merchant_group_unavailable` (the merchant group of the caller could
            not be verified, so money movement is refused). 502:
            `instant_payment_alias_not_recorded`,
            `instant_payment_alias_deletion_not_recorded`,
            `instant_payment_alias_divergence`.
          example: merchant_group_unavailable
        message:
          type: string
          description: What went wrong, and whether the call is safe to retry.
          example: >-
            Your merchant group could not be verified. Please retry in a few
            moments.
        request_id:
          type: string
          description: >-
            Identifier of the request, to quote when contacting the Support
            team.
      required:
        - status
        - code
        - message
        - request_id
    CustomerFieldDto:
      type: object
      properties:
        fieldName:
          type: string
          description: Field identifier in snake_case
          example: national_id
        fieldLabel:
          type: string
          description: Human-readable label shown to the payer
          example: National ID
          maxLength: 100
        fieldPlaceholder:
          type: string
          description: Optional input placeholder text
          maxLength: 200
        fieldType:
          type: string
          enum:
            - text
            - integer
            - decimal
            - email
            - date
          description: Expected value type for validation and input rendering
        isRequired:
          type: boolean
          description: Whether the payer must fill this field before proceeding
      required:
        - fieldName
        - fieldLabel
        - fieldType
        - isRequired
    InternalApiBadRequestError:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP error code.
          example: 400
        message:
          description: >-
            Detailed error message or array of messages to describe what's
            wrong.
          example:
            - destination.provider must be a string
          type: array
          items:
            type: string
        error:
          type: string
          description: The error message
          example: Bad Request
      required:
        - statusCode
        - message
        - error
    InternalApiUnauthorizedError:
      type: object
      properties:
        type:
          type: string
          description: The type of this error.
          example: authorization_error
        code:
          type: string
          description: The internal error code describing what happened.
          enum:
            - bad_payment_intent_token
            - wrong_credentials
          example: wrong_credentials
        message:
          type: string
          description: Detailed error message which describe what happened.
          example: L'ID marchand et/ou la clé d'API sont incorrects.
      required:
        - type
        - code
        - message
    ForbiddenErrorObject:
      type: object
      properties:
        statusCode:
          type: number
          description: Http status
          enum:
            - 403
          example: 403
        message:
          type: string
          description: Detailed error message
          example: Forbidden
        error:
          type: string
          description: Error name
      required:
        - statusCode
        - message
        - error

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.