Initialize, Redirect, and Verify Payments with Paylink

Learn how to initialize a payment session, redirect customers to checkout, verify payment status, and reliably handle completion via webhooks.

Use Paylink Checkout to collect card, bank transfer, USSD, and direct-debit payments from your customers. The flow has three steps: initialize a payment session on your server, redirect the customer to the hosted checkout page, then verify the result server-side once they return.

Initialize a Payment

Send a POST request to /payments/initialize from your server. Never call this endpoint from client-side code — your secret key must stay private.

Request

{
  "email": "[e-mail]",
  "amount": 2500.00,
  "currency": "NGN",
  "reference": "order_12345",
  "callback_url": "https://merchant.example.com/payment/callback",
  "webhook_url": "https://merchant.example.com/webhooks/payments",
  "metadata": { "order_id": "12345" },
  "merchant_bears_fees": false
}

Field	Required	Description
email	✅	Customer’s email address
amount	✅	Amount to charge in the specified currency
currency	✅	ISO currency code, e.g. NGN
reference	Optional	Your unique transaction reference. Auto-generated if omitted
callback_url	Optional	URL the customer is redirected to after checkout
webhook_url	Optional	URL that receives async payment event notifications
metadata	Optional	Arbitrary key-value data attached to the transaction
merchant_bears_fees	Optional	Set to true to absorb processing fees instead of passing them to the customer

A successful response returns an authorization_url that you use to redirect the customer:

Response

{
  "status": "success",
  "authorization_url": "https://sandbox-checkout.lyseis-pay.com/pay/abc123",
  "reference": "order_12345"
}

Save the reference value to your database before redirecting. You will need it to verify the payment outcome.

Redirect the Customer to Checkout

Redirect the customer’s browser to the authorization_url from the response. The customer completes payment on the Paylink-hosted checkout page and is then sent back to your callback_url.

Example redirect (HTTP response header)

HTTP/1.1 302 Found
Location: https://sandbox-checkout.lyseis-pay.com/pay/abc123

Use Sandbox Test Cards

Use the following cards on the sandbox checkout page to simulate different payment outcomes:

Scenario	Card details
Successful Payment (No Authentication) - Visa	Card number: 4084 1278 8317 2787 Expiry: 09/30 CVV: 123
Successful Payment (with PIN) - Mastercard	Card number: 5188 5136 1855 2975 Expiry: 09/30 CVV: 123 PIN: 1234
Successful Payment (with OTP) - Mastercard	Card number: 5442 0561 0607 2595 Expiry: 09/30 CVV: 123 PIN: 1234 OTP: 123456
Failed Payment (Insufficient Funds) - Verve	Card number: 5060 6650 6066 5060 67 Expiry: 09/30 CVV: 408

Handle the Callback

When the customer returns to your callback_url, Paylink appends the reference as a query parameter:

https://merchant.example.com/payment/callback?reference=order_12345

Never trust the callback URL alone to confirm a successful payment. A customer can visit your callback URL directly without completing payment. Always verify the payment server-side using the reference.

Verify Payment Status

Call GET /payments/verify/{reference} from your server immediately after receiving the callback:

Request

GET /payments/verify/order_12345

Response

{
  "status": "success",
  "message": "Payment verified successfully",
  "reference": "order_12345",
  "transaction_id": "txn_9876543210"
}

Only fulfil the order — ship goods, activate a subscription, grant access — when the returned status is success.

Payment Statuses

Status	Meaning
success	Payment completed and funds settled
processing	Payment received, awaiting confirmation
failed	Payment attempt was unsuccessful
abandoned	Customer left checkout without paying
reversed	Payment was reversed after initial success
expired	Checkout session timed out before payment

Use Webhooks for Reliable Delivery

Callbacks depend on the customer’s browser returning to your site, which can fail if they close the tab or lose connectivity. Webhooks are server-to-server notifications sent directly to your webhook_url, making them the most reliable way to track payment outcomes.

Always set a webhook_url when you initialize a payment:

Webhook event payload (example)

{
  "event_type": "charge_success",
  "status": "success",
  "message": "Payment completed successfully",
  "event_id": "evt_abc123xyz",
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "reference": "order_12345",
    "amount": 2500.00,
    "currency": "NGN",
    "metadata": { "order_id": "12345" }
  }
}

Respond to webhook requests with an HTTP 200 status as quickly as possible. Move order-fulfillment logic to a background job so you don’t time out.

View Transaction History

Retrieve a paginated list of all your transactions at GET /merchants/transactions. Use the query parameters below to filter results:

Parameter	Description
status	Filter by payment status (e.g. success, failed)
payment_method	Filter by method: card, bank_transfer, ussd, direct_debit
customer_email	Filter by customer email address
start_date	Earliest transaction date (ISO 8601)
end_date	Latest transaction date (ISO 8601)
page	Page number (default 1)
page_size	Results per page (default 10, max 100)

Example request

GET /merchants/transactions?status=success&payment_method=card&page=1&page_size=20

---

Payments API Reference

Full parameter list and response schema for the payments endpoints.

Webhooks Guide

Learn how to verify webhook signatures and handle events securely.