Skip to main content
POST
A payment link is a URL that takes your customer to a secure checkout page hosted by HUB2, where they pay with one of the payment methods and providers you allow.

​
Headers

​
string
required
Your API key.
​
string
required
Your merchant ID.
​
string
required
The environment to use: sandbox or live.

​
Request

​
string
required
Your reference for the purchase (e.g., ORDER-12345). For a multi_use link, it identifies the collection.
​
string
required
The currency, as a three-letter ISO 4217 code (e.g., XOF).
​
string
required
The country where the customer pays, as a two-letter ISO 3166-1 alpha-2 code (e.g., CI).
​
string[]
required
The payment methods offered on the checkout page. Must not be empty and must include mobile_money or credit_card. A link that offers neither is rejected with 400 and the code payment_method_not_supported. Possible values: mobile_money, credit_card, bank_transfer.
​
string[]
The providers offered on the checkout page (e.g., ["orange", "mtn"]). Required unless paymentMethods contains only credit_card. For a card-only link, omit it: an empty array is rejected with 400, and card payments use the card provider configured for your account. Maximum 20 providers. Each provider must be enabled in country; names are case-insensitive. A provider that does not support any of the requested paymentMethods is ignored. If no requested provider supports any of the requested paymentMethods, the request fails with 400.
​
integer
The amount to charge, in the smallest currency unit (e.g., 1000). Required unless openAmount is true, in which case it must be omitted. Minimum 500 for XOF and XAF.
​
boolean
default:"false"
When true, the customer enters the amount on the checkout page.
​
integer
The minimum amount the customer can enter. Only relevant when openAmount is true. Minimum 500 for XOF and XAF.
​
integer
The maximum amount the customer can enter. Only relevant when openAmount is true. Must be greater than minAmount.
​
string
default:"single_use"
How many times the link can be paid. Possible values: single_use (one successful payment), multi_use (several successful payments, until maximumPayments or the expiration date is reached).
​
integer
The maximum number of successful payments for a multi_use link. Minimum 1. Omit it for an unlimited number of payments. Ignored for single_use links.
​
string
The expiration date of the link, in ISO 8601 format (e.g., 2026-10-15T14:30:00.000Z). Optional. Defaults to 15 minutes after creation. A date that is not in the future is silently replaced by this default, without an error.
​
string
The HTTPS URL the customer is redirected to after a successful payment.
​
string
The HTTPS URL the customer is redirected to after a failed payment.
​
string
The phone number of the customer. When set, only this phone number can pay the link.
​
string
A description displayed on the checkout page.
​
object[]
Up to 5 custom form fields the customer fills in before choosing a payment method. They cannot be changed after creation.

​
Response

HTTP status: 201 Created
​
string
The ID of the payment link (e.g., pl_z1urYtVFgEebtcj8fxp4v).
​
string
The URL of the checkout page to share with your customer.
​
string
The status of the payment link. Possible values: active, completed, closed, expired.
​
string
The type of the payment link. Possible values: single_use, multi_use, bill_payment.
​
string
Your reference for the purchase.
​
number | null
The amount to charge, in the smallest currency unit. null when openAmount is true.
​
string
The currency, as an ISO 4217 code.
​
boolean
Whether the customer enters the amount.
​
number
The minimum amount the customer can enter. Only when openAmount is true.
​
number
The maximum amount the customer can enter. Only when openAmount is true.
​
number
The maximum number of successful payments. Absent for an unlimited multi_use link.
​
number
The number of successful payments recorded on the link.
​
number
The maximum number of failed payments on a single_use link (currently 3). When it is reached, the link is closed.
​
string | null
The only phone number allowed to pay the link, if one was set.
​
object[]
The custom form fields of the link. Absent when the link has none.
​
string
The expiration date of the link, in ISO 8601 format.
​
string
The creation date of the link, in ISO 8601 format.
​
string
The date of the last update of the link, in ISO 8601 format.

​
Errors