Your server creates a payment link. Your customer pays through Payligne hosted checkout. Payligne confirms the payment, notifies your webhook, and redirects the customer back to your application.
Developer guide
Use this simple order: create a link, send the link to your customer, wait for payment, then use the webhook to update your order.
1. POST /api/payment-links
Send your external_reference.
2. Send the returned link.url to your customer.
3. The customer pays on the hosted Payligne page.
4. Payligne sends payment.successful to your webhook.
5. Match data.external_reference to your order.Developer guide
Create an API key in the Payligne dashboard. Use it only on your server. Every protected request uses the same Bearer header.
Create the API key in your Payligne dashboard.
Use it only from your server:
Authorization: Bearer pl_live_xxx
Content-Type: application/json
Never put this key in your customer-facing browser code.Developer guide
Create one payment link for one order. Send your own unique external_reference. API-created links and API checkout accounts always expire after 30 minutes. Web-created links can be set from 30 minutes up to 24 hours. The checkout total uses the charge preference saved in your Settings.
POST /api/payment-links
Authorization: Bearer <api_key>
Content-Type: application/json
{
"external_reference": "ORDER-20261008-0001",
"title": "Website consultation",
"description": "30-minute discovery call",
"amount": 32000,
"quantity": 1,
"expiry": "30m",
"buttonLabel": "Pay now",
"redirectUrl": "https://merchant.example/orders/ORDER-20261008-0001/paid"
}
The external_reference must be unique within your Payligne account. API-created links are capped at 30 minutes.Developer guide
Save the link and send the returned URL to your customer. The amount is your order amount. payableAmount is what the customer must pay after your charge setting is applied.
{
"link": {
"id": "consultation-8x9k2m",
"external_reference": "ORDER-20261008-0001",
"amount": 32000,
"charge": 640,
"chargePayer": "customer",
"payableAmount": 32640,
"url": "https://payligne.example/checkout/consultation-8x9k2m",
"redirectUrl": "https://merchant.example/orders/ORDER-20261008-0001/paid"
}
}
Send link.url to the customer.Developer guide
This endpoint is optional. Use it only when your server needs the payment account before the customer opens the link. Send the same external_reference and amount used when the link was created.
POST /api/payment-links/consultation-8x9k2m/checkout
Authorization: Bearer <api_key>
Content-Type: application/json
{
"external_reference": "ORDER-20261008-0001",
"amount": 32000
}
Response
{
"status": "pending",
"external_reference": "ORDER-20261008-0001",
"amount": 32000,
"charge": 640,
"chargePayer": "customer",
"payableAmount": 32640,
"account": {
"number": "3000000786",
"name": "Payment account",
"bank": "Example Bank",
"expiresAt": "2026-10-15T10:00:00+01:00"
}
}Developer guide
Use this endpoint to check payment status. A pending response means the customer has not paid. A paid response means you can mark your order complete. The webhook is the recommended source of truth.
POST /api/payment-links/consultation-8x9k2m/confirm
Authorization: Bearer <api_key>
Content-Type: application/json
{
"external_reference": "ORDER-20261008-0001"
}
Response
{
"status": "paid",
"external_reference": "ORDER-20261008-0001",
"reference": "PAY-TRX-0001",
"redirect": "https://merchant.example/orders/ORDER-20261008-0001/paid"
}Developer guide
Register your HTTPS webhook once. When payment succeeds, Payligne sends payment.successful. Verify the signature, find your order using external_reference, and return a successful response.
POST /api/webhooks
Authorization: Bearer <api_key>
Content-Type: application/json
{
"url": "https://merchant.example/webhooks/payligne",
"events": ["payment.successful"]
}
Save the returned secret. Payligne sends:
POST https://merchant.example/webhooks/payligne
Content-Type: application/json
X-Payligne-Event: payment.successful
X-Payligne-Signature: <hex HMAC-SHA256>
{
"id": "evt_xxx",
"event": "payment.successful",
"created_at": "2026-10-08T20:00:00Z",
"data": {
"external_reference": "ORDER-20261008-0001",
"reference": "MED-TRX-0001",
"amount": 32640,
"order_amount": 32000,
"charge": 640,
"charge_payer": "customer",
"currency": "NGN",
"source": "payment_link",
"payment_link_id": "consultation-8x9k2m",
"customer": { "name": "Ada Example", "email": "ada@example.com" }
}
}
signature = HMAC-SHA256(raw_request_body, webhook_secret)Never expose private credentials in client code.
Secure your application and webhook URLs.
Make link and event handling idempotent.