Skip to main content
GET
/
payment-links
List Payment Links
curl --request GET \
  --url https://api.example.com/payment-links \
  --header 'ApiKey: <apikey>' \
  --header 'Environment: <environment>' \
  --header 'MerchantId: <merchantid>'
[
  {
    "id": "pl_z1urYtVFgEebtcj8fxp4v",
    "url": "https://pay.hub2.com/pl_z1urYtVFgEebtcj8fxp4v",
    "status": "active",
    "purchaseReference": "ORDER-12345",
    "amount": 1000,
    "currency": "XOF",
    "currentSuccessCount": 0,
    "maximumAttempts": 3,
    "createdAt": "2024-01-15T12:00:00.000Z",
    "updatedAt": "2024-01-15T12:30:00.000Z",
    "expirationDate": "2024-01-15T14:30:00.000Z",
    "customerPhoneNumber": "123456789",
    "type": "single_use",
    "paymentAttempts": [
      {
        "id": "pay_QW2d6JnqiatcH8KhK0mD1",
        "intentId": "pi_z1urYtVFgEebtcj8fxp4v",
        "createdAt": "2020-10-15T12:09:49.355Z",
        "updatedAt": "2020-10-15T12:16:26.128Z",
        "status": "successful",
        "amount": 100,
        "currency": "XOF",
        "method": "mobile_money",
        "country": "CI",
        "fees": [
          {
            "id": "lAe5HnFpvOjwdT9vSIgPA",
            "rate": 123,
            "amount": 5,
            "currency": "XOF",
            "label": "<string>",
            "taxes": [
              "<string>"
            ]
          }
        ],
        "providerReference": "<string>",
        "gatewayId": "<string>",
        "number": "<string>",
        "failure": {
          "message": "<string>",
          "params": [
            "<string>"
          ]
        },
        "nextAction": {
          "message": "<string>",
          "data": {
            "url": "<string>",
            "urls": "<string>",
            "method": "post",
            "headers": {},
            "data": {}
          }
        },
        "paymentInformation": {
          "recipient_name_hashmac": "a1b2c3d4e5f6",
          "recipient_phone_hashmac": "a1b2c3d4e5f6",
          "customer_id_hashmac": "a1b2c3d4e5f6"
        },
        "isDelegated": true
      }
    ],
    "openAmount": false,
    "minAmount": 500,
    "maxAmount": 100000,
    "maximumPayments": 50,
    "customerFields": [
      {
        "fieldName": "national_id",
        "fieldLabel": "National ID",
        "isRequired": true,
        "fieldPlaceholder": "<string>"
      }
    ],
    "customerData": {
      "national_id": "AB123456"
    }
  }
]

Headers

​
ApiKey
string
required

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.

​
MerchantId
string
required

Your merchant ID. This information is available in our dashboard. If you don't have access to it, please reach the Support team.

​
Environment
enum<string>
required

Allow you to choose between the sandbox mode to perform some tests or the live mode for real world transactions.

Available options:
live,
sandbox

Query Parameters

​
fromCreatedAt
string

Filter by creation date from (ISO 8601) - inclusive start date

Example:

"2024-01-15T00:00:00.000Z"

​
toCreatedAt
string

Filter by creation date to (ISO 8601) - inclusive end date

Example:

"2024-01-15T23:59:59.999Z"

​
fromExpirationDate
string

Filter by expiration date from (ISO 8601) - inclusive start date

Example:

"2024-01-15T00:00:00.000Z"

​
toExpirationDate
string

Filter by expiration date to (ISO 8601) - inclusive end date

Example:

"2024-01-15T23:59:59.999Z"

​
status
enum<string>

Filter by payment link status

Available options:
active,
expired,
closed,
completed
Example:

"active"

Response

​
id
string
required

Unique identifier for the payment link

Example:

"pl_z1urYtVFgEebtcj8fxp4v"

​
url
string
required

URL for the payment link

Example:

"https://pay.hub2.com/pl_z1urYtVFgEebtcj8fxp4v"

​
status
enum<string>
required

Current status of the payment link

Available options:
active,
expired,
closed,
completed
Example:

"active"

​
purchaseReference
string
required

Merchant reference for the payment

Example:

"ORDER-12345"

​
amount
object
required

Amount intended to be charged in the smallest currency unit. Null when openAmount is true.

Example:

1000

​
currency
string
required

Three-letter ISO 4217 currency code

Example:

"XOF"

​
currentSuccessCount
number
required

Number of successful payments recorded for this link

Example:

0

​
maximumAttempts
number
required

Maximum number of failed payments allowed per user

Example:

3

​
createdAt
string
required

Creation date in ISO 8601 format

Example:

"2024-01-15T12:00:00.000Z"

​
updatedAt
string
required

Last update date in ISO 8601 format

Example:

"2024-01-15T12:30:00.000Z"

​
expirationDate
string
required

Expiration date in ISO 8601 format

Example:

"2024-01-15T14:30:00.000Z"

​
customerPhoneNumber
string
required

Restricted MSISDN

Example:

"123456789"

​
type
enum<string>
required

Type of the payment link

Available options:
single_use,
multi_use
Example:

"single_use"

​
paymentAttempts
object[]
required

List of payment attempts for this payment link

​
openAmount
boolean

When true, the payer decides the amount at payment time.

Example:

false

​
minAmount
number

Minimum amount the payer can enter (only when openAmount is true).

Example:

500

​
maxAmount
number

Maximum amount the payer can enter (only when openAmount is true).

Example:

100000

​
maximumPayments
number

Maximum successful payments allowed (omitted when unlimited multi_use)

Example:

50

​
customerFields
object[]

Custom form fields defined on this payment link. Absent when the link has no customer fields.

​
customerData
object

Collected payer data as fieldName → value pairs. Absent when no customerFields are defined.

Example:
{ "national_id": "AB123456" }