Skip to main content

​
API Integration

Payment Links use the HUB2 API. The available endpoints are listed in the following documentation:

API Payment Links

​
Authentication

Your integration uses the same HUB2 API keys for authentication. The key must have the following permissions:
  • Api.payment_intent_create: create and close payment links
  • Api.payment_intent_read: retrieve and list payment links

Permissions configuration

​
API Endpoints

  • POST /payment-links: create a payment link and define the accepted payment methods and providers. The payment intent and the payment are created as the customer goes through the payment page. Example:
  • type defaults to single_use (one successful payment). Use multi_use to accept several payments, optionally capped with maximumPayments.
  • When expirationDate is omitted or already in the past, the link expires 15 minutes after creation.
  • successUrl and failureUrl must use the https scheme.
  • PATCH /payment-links/{id}/close: close a payment link before it expires
  • GET /payment-links: list the payment links you created
  • GET /payment-links/{id}: retrieve a payment link with its payment attempts
Rate limits per endpoint:
  • POST /payment-links: 100 requests per 10 seconds
  • GET /payment-links/{id}: 1 request per second
  • GET /payment-links: 1 request per 5 seconds
  • PATCH /payment-links/{id}/close: 1 request per second
Beyond these limits, the API responds with HTTP 429 Too Many Requests.

​
Card payments

A link offers card payments when paymentMethods contains credit_card. Card payments always use the card provider configured for your merchant account, so providers never lists a card provider. Your account must have card payments enabled: see Card payments in the configuration guide. For a card-only link, omit providers. An empty array is rejected with 400:
To offer mobile money and card on the same link, list both methods and send providers for mobile money:
On the checkout page, the customer sees the mobile money providers followed by a “Pay with card” option. On a card-only link, only the card option is shown. When the customer chooses card, the phone number field is hidden and the customer is redirected to a card payment page hosted by the card provider. Afterwards, the customer always lands on the HUB2 result page first; its button then takes them to your successUrl or failureUrl if you set them. A creation request that cannot be accepted returns 400 with a body containing status, code, message and request_id. Use code to decide what to do: A request that includes mobile_money without providers is also rejected with 400. Only a card-only link can omit them.

​
Webhooks

Payments made through a link trigger the usual payment.* and payment_intent.* webhooks. Payment links also have their own events: payment_links.created, payment_links.paid, payment_links.completed, payment_links.expired and payment_links.closed. If you have already configured webhooks for payments, no additional step is required. Otherwise, see:

Webhooks Integration Guide