---
title: "Create Payment Link"
method: POST
path: "/payment-links"
tags: ["Payment Links"]
---

# Create Payment Link

`POST /payment-links`

## Request

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

Create a new payment link

## Headers

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

## Request body

- CreatePaymentLinkDto
  - `openAmount` boolean: When true, the payer decides the amount at payment time. amount must be omitted when this is true.
  - `amount` number: Amount intended to be charged in the smallest currency unit. Required when openAmount is false or omitted.
  - `minAmount` number: Minimum amount the payer can enter (only relevant when openAmount is true).
  - `maxAmount` number: Maximum amount the payer can enter (only relevant when openAmount is true).
  - `currency` string, required: Three-letter ISO 4217 currency code
  - `purchaseReference` string, required: Merchant reference for the payment (collection ID for multi_use links)
  - `type` 'single_use' | 'multi_use' | 'bill_payment': Defaults to single_use when omitted. multi_use allows multiple successful payments until optional maximumPayments or expiration.
  - `maximumPayments` number: Maximum successful payments for multi_use links. Omit for unlimited. Ignored for single_use (always one success).
  - `providers` string[]: List of supported providers. Required unless paymentMethods is credit_card only: card always uses the merchant's configured card provider, never one listed here. Omit the field on a card-only link: an empty array is rejected with 400. Each name is at most 64 characters. A provider unknown in the country is rejected with 400; a known provider that is not enabled there for a method the link offers, or that the routing check refuses for the merchant, is left out of the link and missing from the response's providers; when none is left for mobile_money, the request is rejected with 400 wrong_provider. When the providers cannot be checked (the routing check does not answer, or is temporarily unavailable), the request is rejected with 503 provider_check_unavailable: retry later.
  - `paymentMethods` string[], required: Payment method. credit_card is rejected with 400 credit_card_provider_not_configured, credit_card_fees_not_supported or credit_card_provider_unavailable when the merchant cannot take card payments; mobile_money is rejected with 400 wrong_provider when none of the providers offers it in the country; a link offering neither mobile_money nor credit_card is rejected with 400 payment_method_not_supported.
  - `country` string, required: Two-letter ISO 3166-1 alpha-2 country code
  - `expirationDate` string: Expiration date for the payment link (default: 15 minutes from creation)
  - `successUrl` string: URL to redirect to after successful payment
  - `failureUrl` string: URL to redirect to after failed payment
  - `customerPhoneNumber` string: Customer phone number for the payment (optional)
  - `description` string: Description for the payment (optional)
  - `customerFields` CustomerFieldDto[]: Custom form fields shown to payer before payment method selection (max 5). Immutable after creation.
    - `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

## Response `201`

Payment 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/payment-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)