> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lyseis-pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```json Request theme={null}
{
  "email": "customer@example.com",
  "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:

```json Response theme={null}
{
  "status": "success",
  "authorization_url": "https://sandbox-checkout.lyseis-pay.com/pay/abc123",
  "reference": "order_12345"
}
```

<Tip>
  Save the `reference` value to your database before redirecting. You will need it to verify the payment outcome.
</Tip>

## 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`.

```http Example redirect (HTTP response header) theme={null}
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`<br />Expiry: `09/30`<br />CVV: `123`                                     |
| Successful Payment (with PIN) - Mastercard    | Card number: `5188 5136 1855 2975`<br />Expiry: `09/30`<br />CVV: `123`<br />PIN: `1234`                    |
| Successful Payment (with OTP) - Mastercard    | Card number: `5442 0561 0607 2595`<br />Expiry: `09/30`<br />CVV: `123`<br />PIN: `1234`<br />OTP: `123456` |
| Failed Payment (Insufficient Funds) - Verve   | Card number: `5060 6650 6066 5060 67`<br />Expiry: `09/30`<br />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
```

<Warning>
  **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.
</Warning>

## Verify Payment Status

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

```http Request theme={null}
GET /payments/verify/order_12345
```

```json Response theme={null}
{
  "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:

```json Webhook event payload (example) theme={null}
{
  "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" }
  }
}
```

<Tip>
  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.
</Tip>

## 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`)                        |

```http Example request theme={null}
GET /merchants/transactions?status=success&payment_method=card&page=1&page_size=20
```

***

<CardGroup cols={2}>
  <Card title="Payments API Reference" icon="code" href="/api-reference/payments/initialize">
    Full parameter list and response schema for the payments endpoints.
  </Card>

  <Card title="Webhooks Guide" icon="bell" href="/concepts/webhooks">
    Learn how to verify webhook signatures and handle events securely.
  </Card>
</CardGroup>