> ## 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 a New Payment — POST /payments/initialize

> POST /payments/initialize — starts a new payment session. Accepts email, amount, and currency. Returns an authorization_url and transaction reference.

Use this endpoint to begin a new payment session for a customer. On success, the response includes an `authorization_url` — a hosted checkout page where the customer completes payment — and a `reference` you can use to track the transaction.

```http theme={null}
POST https://sandbox.lyseis-pay.com/payments/initialize
```

<Note>
  Replace `sandbox.lyseis-pay.com` with `live.lyseis-pay.com` when moving to production.
</Note>

## Headers

| Header         | Value                                   |
| -------------- | --------------------------------------- |
| `X-Key-Id`     | Your merchant key ID                    |
| `X-Timestamp`  | Unix timestamp of the request (seconds) |
| `X-Signature`  | HMAC-SHA256 signature of the payload    |
| `Content-Type` | `application/json`                      |

## Request Body

<ParamField body="email" type="string" required>
  The customer's email address. Used to identify the payer and send payment receipts.
</ParamField>

<ParamField body="amount" type="string" required>
  The payment amount as a decimal string (e.g. `"2500.00"`). Must represent a positive value in the currency's standard unit.
</ParamField>

<ParamField body="currency" type="string" required>
  ISO 4217 three-letter currency code. Example: `NGN`.
</ParamField>

<ParamField body="reference" type="string">
  A unique merchant-defined transaction reference. If omitted, Paylink auto-generates one. Must be unique across your account.
</ParamField>

<ParamField body="callback_url" type="string">
  The URL Paylink redirects the customer to after the payment attempt. The payment `reference` is appended as a query parameter.
</ParamField>

<ParamField body="webhook_url" type="string">
  A URL that receives real-time HTTP POST notifications for payment status changes. Overrides the default webhook URL configured in your dashboard for this transaction.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value pairs you want to attach to this transaction. Returned as-is on verify and webhook payloads.

  ```json theme={null}
  { "order_id": "12345", "customer_tier": "gold" }
  ```
</ParamField>

<ParamField body="merchant_bears_fees" type="boolean" default="false">
  When `true`, processing fees are deducted from the merchant settlement rather than added to the customer's charge. Defaults to `false`.
</ParamField>

## Example Request

```json 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
}
```

## Response

<ResponseField name="status" type="string">
  Indicates whether the initialization request succeeded. A value of `"success"` means the session was created and the `authorization_url` is ready to use.
</ResponseField>

<ResponseField name="authorization_url" type="string">
  The hosted Paylink checkout URL. Redirect or link the customer here to complete payment. The URL is single-use and expires after a short window.
</ResponseField>

<ResponseField name="reference" type="string">
  The transaction reference — either the one you supplied or the auto-generated value. Store this; it is required for verification and reconciliation.
</ResponseField>

## Example Response

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

<Note>
  Initialization does **not** confirm that payment was collected. Payment happens asynchronously after the customer completes the checkout flow. Use the [Verify Payment](/api-reference/payments/verify) endpoint, [Transaction History](/api-reference/payments/history), or your configured webhook as the authoritative source of payment status.
</Note>