--- title: "Create Payment Link" method: POST path: "/payment-links/v1" tags: ["Payment Links"] --- # Create Payment Link `POST /payment-links/v1` Creates a payment link that can be shared with customers to collect payments. The link remains ACTIVE until it expires, reaches its usage limit, or is explicitly disabled. ## Request body - CreatePaymentLinkRequest — Configuration for a new payment link. Provide payment_details at minimum. Use max_usages or expires_at to limit availability. - `name` string, nullable — A label for your own reference. Not shown to payers. Useful for distinguishing links in list views. - `max_usages` integer, nullable — The maximum number of successful payments this link will accept. Once reached, the link transitions to USED status and will reject further payment attempts. Defaults to 1000 if omitted. - `expires_at` string, date-time, nullable — The date and time at which this link will automatically expire, in ISO 8601 format. After this time the link transitions to EXPIRED status. Omit to create a link with no expiry. - `redirect_url` string, nullable — The URL your customer is redirected to after completing or cancelling a payment. Must be an absolute URL. You can use query parameters to carry context (e.g., an order ID) back to your application. Optional - if omitted, the payer will see a confirmation screen on completion instead of being redirected. - `customer_id` string, uuid, nullable — Associates this link with a specific customer in your system. If provided, all payments will be associated with that customer. - `payment_details` PaymentDetailsRequest, required — The payment parameters that apply to every transaction made through this link. Fixed at creation time and cannot be changed afterwards. - `destination_id` string, uuid, nullable — The ID of the bank account that will receive the funds. If omitted, the payment is routed to your application's default destination account. - `reference` string, required — A reference string that appears on the bank statement for both sender and recipient. - `currency` string, required — The ISO 3 letter currency code - `amount` number, double, required — The exact amount to charge, in the currency specified by the currency field. Must be greater than zero. - `payment_purpose` 'FIS' | 'TCS' | 'MWP' | 'OAT' | 'IFS' | 'RNT' | 'LNC' | 'PIN' | 'GDS' — A category code that relates to the type of services or goods that corresponds to the underlying purpose of the payment. The code must conform to the payment purpose code list. **Supported values:** - `FIS` – Financial services - `TCS` – Telecommunication services - `MWP` – Mobile wallet card payments - `OAT` – Own account transfer - `IFS` – Information services - `RNT` – Rent payments - `LNC` – Loan charges - `PIN` – Personal investments - `GDS` – Goods bought or sold - `identifiers` IdentifierRequest[], nullable — Additional fields to collect from each payer before they can complete the payment. - `type` 'EMAIL' | 'MOBILE_PHONE' | 'TEXT', required — The type of information to collect from the payer. Controls input validation and formatting in the payment UI. - EMAIL: Collects an email address. Input is validated against standard email format. - MOBILE_PHONE: Collects a mobile phone number. Input is validated as a valid phone number. - TEXT: Collects a free-form text value. Use the limit field to constrain length. - `display_label` string, nullable — A label shown to the payer for this field. For example, "Your email address". - `required` boolean, nullable — When true, the payer must fill in this field before they can complete the payment. When false or omitted, the field is presented but optional. - `limit` integer, nullable — The maximum number of characters the payer can enter for this field. ## Response `201` Payment link created successfully - PaymentLinkResponse — The full state of a payment link, including its shareable URL, current status, usage counts, and configuration. - `id` string, uuid, required — The unique ID of this payment link. Use this to retrieve, update, or reference the link in other API calls. - `link` string, uri, required — The URL to share with your customer. Directing a customer to this URL begins the payment flow. Anyone with this URL can initiate a payment. - `status` 'ACTIVE' | 'EXPIRED' | 'USED' | 'DISABLED', required — The lifecycle state of a payment link. - ACTIVE: The link is live and will accept payments. This is the initial state after creation. - EXPIRED: The link's `expires_at` time has passed. It can no longer accept payments and cannot be reactivated. - USED: The link has reached its `max_usages` limit. All permitted payments have been collected. Cannot be reactivated. - DISABLED: The link was manually disabled via the update endpoint. It can be re-enabled by setting status to `ACTIVE`. - `current_usages` integer, required — The number of successful payments completed through this link. Increments each time a payer completes a payment. Compare with `max_usages` to understand remaining capacity. - `name` string, nullable — The label you provided when creating the link, if any. For display purposes only. - `max_usages` integer, nullable — The maximum number of payments this link will accept before transitioning to USED status. Null indicates no limit. - `expires_at` string, date-time, nullable — The expiry date and time for this link in ISO 8601 format. After this time the link cannot be used. Null means the link does not expire automatically. - `redirect_url` string, uri, required — The URL your customer is redirected to after completing or cancelling a payment. - `customer_id` string, uuid, nullable — The ID of the customer associated with this link, if any. Payments through this link will be attributed to this customer. - `payment_details` PaymentDetailsResponse, required — The payment parameters attached to this link. These values are fixed for the lifetime of the link. - `destination_id` string, uuid, nullable — Identifier of the destination account for the payment - `reference` string, required — A reference string that appears on the bank statement for both sender and recipient. - `currency` string, required — The ISO 3 letter currency code - `amount` number, double, required — The amount charged through this link, in the specified currency. - `payment_purpose` 'FIS' | 'TCS' | 'MWP' | 'OAT' | 'IFS' | 'RNT' | 'LNC' | 'PIN' | 'GDS' — A category code that relates to the type of services or goods that corresponds to the underlying purpose of the payment. The code must conform to the payment purpose code list. **Supported values:** - `FIS` – Financial services - `TCS` – Telecommunication services - `MWP` – Mobile wallet card payments - `OAT` – Own account transfer - `IFS` – Information services - `RNT` – Rent payments - `LNC` – Loan charges - `PIN` – Personal investments - `GDS` – Goods bought or sold - `identifiers` IdentifierResponse[], nullable — The list of additional fields configured to be collected from each payer. Null or empty means no extra information is collected. - `type` 'EMAIL' | 'MOBILE_PHONE' | 'TEXT', required — The type of information to collect from the payer. Controls input validation and formatting in the payment UI. - EMAIL: Collects an email address. Input is validated against standard email format. - MOBILE_PHONE: Collects a mobile phone number. Input is validated as a valid phone number. - TEXT: Collects a free-form text value. Use the limit field to constrain length. - `display_label` string, nullable — The label shown to the payer for this field, if a custom one was set. - `required` boolean, nullable — Whether the payer must fill in this field before completing the payment. - `limit` integer, nullable — The maximum number of characters allowed for this field's value. --- [API](https://skmtc.net/leantech/apis/auth.md) · [All operations](https://skmtc.net/leantech/apis/auth/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/leantech/auth/versions/c2e46d54d886/schema)