> ## 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 Payment Links

> This endpoint allows you to generate a secure payment link for receiving payments from your customers.

The Payment Links API allows you to accept payments from customers using a payment link URL. The payment link URL takes your shopper to an HUB2 hosted secure checkout page where they can make the payment with their preferred payment method.

## Request

<ParamField body="purchaseReference" type="string" required>
  Reference of the Purchase on your system (e.g., `EM_TEST_1006`)
</ParamField>

<ParamField body="description" type="string" optional>
  The additional description text that appears under the title in the payment checkout page. (e.g., `Text displayed for the description`)
</ParamField>

<ParamField body="amount" type="number" required>
  The payment amount (e.g., `500`).
  Minimum amount for payment links is 500 XOF.
</ParamField>

<ParamField body="currency" type="string" required>
  The payment currency. (e.g., `XOF`)
</ParamField>

<ParamField body="country" type="string" required>
  Country where the customers should pay (e.g., `CI`)
</ParamField>

<ParamField body="type" type="string" required>
  Specifies whether the payment link can be used once or multiple times. Default value is "single\_use" for the current version of the API. (e.g., `CI`)
</ParamField>

<ParamField body="customerPhoneNumber" type="number" optional>
  The number of the customer associated with the purchaseReference. (e.g., `0707070707`)
</ParamField>

<ParamField body="expirationDate" type="string" optional>
  Expiration date of the payment links (ISO 8601 format). Default value is 15mins (e.g., `2025-11-01T00:00:00.000Z`)
</ParamField>

## Response

<ResponseField name="id" type="number">
  The unique Payment Links ID
</ResponseField>

<ResponseField name="URL" type="string">
  The unique Payment Links URL
</ResponseField>

<ResponseField name="status" type="string">
  The current status of the Payment Links. Possible values: `active`, `completed`, `closed`, `expired`
</ResponseField>

<ResponseField name="purchaseReference" type="string">
  Reference of the Purchase associated with the payment links
</ResponseField>

<ResponseField name="amount" type="number">
  The payment  amount
</ResponseField>

<ResponseField name="currency" type="string">
  The currency of the payment  (e.g., `XOF`, `XAF`)
</ResponseField>

<ResponseField name="maximumPayments" type="number">
  Maximum payments allowed for a payment links.
</ResponseField>

<ResponseField name="maximumAttempts" type="number">
  Maximum payments attempts allowed for a payment links.
</ResponseField>

<ResponseField name="createdAt" type="string">
  The date and time when the payment links was created
</ResponseField>

<ResponseField name="updatedAt" type="string">
  The date and time when the payment links was last updated
</ResponseField>

<ResponseField name="expirationDate" type="string">
  The date and time when the payment links will expire
</ResponseField>

<ResponseField name="operators" type="object">
  The list of payment methods allowed for the payment link created
</ResponseField>

<ResponseField name="successUrl" type="string">
  The URL to which the user is redirected upon a successful payment
</ResponseField>

<ResponseField name="failureUrl" type="string">
  The URL to which the user is redirected if the payment fails
</ResponseField>

<ResponseField name="customerPhoneNumber" type="string">
  The customer PhoneNumber set for the payment.
</ResponseField>

<RequestExample>
  ```bash Payment Links Request theme={null}
  curl --location 'https://api.hub2.io/payment-links' \
  --header 'ApiKey: [REDACTED]' \
  --header 'MerchantId: [REDACTED]' \
  --header 'Environment: live' \
  --header 'Content-Type: application/json' \
  --data '{
      "purchaseReference": "EM_TEST_0016",
      "description":"Payment Links are the fastest way to start accepting payments from your customers",
      "amount": 100,
      "currency": "XOF",
      "type":"single_use",
      "expirationDate": "2025-10-27T18:30:00",
      "paymentMethods": [
          "mobile_money"
      ],
      "country": "CI",
      "providers": [
          "Orange",
          "Moov",
          "MTN"
      ]
      
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
      "id": "pl_PX0YZsb3iFg23vX7hWbcC",
      "url": "https://pay.preprod.hub2.io/pl_PX0YZsb3iFg23vX7hWbcC",
      "status": "active",
      "purchaseReference": "EM_TEST_0016",
      "amount": 100,
      "currency": "XOF",
      "maximumPayments": 1,
      "maximumAttempts": 3,
      "createdAt": "2025-10-27T09:17:52.927Z",
      "updatedAt": "2025-10-27T09:17:52.927Z",
      "expirationDate": "2025-10-27T18:30:00.000Z",
      "operators": {
          "mobile_money": [
              "Orange",
              "MTN",
              "Moov"
          ]
      },
      "merchantId": "16",
      "description": "Payment Links are the fastest way to start accepting payments from your customers. Simply input your currency and the amount you would like to charge your customer and a link will be generated. Links can be personalised.271025-09.13",
      "successUrl": "https://hub2.io",
      "failureUrl": "https://hub2.io",
      "customerPhoneNumber": null,
      "type": "single_use"
  }
  ```
</ResponseExample>