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.

POST https://sandbox.lyseis-pay.com/payments/initialize

Replace sandbox.lyseis-pay.com with live.lyseis-pay.com when moving to production.

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

email · string · required

The customer’s email address. Used to identify the payer and send payment receipts.

amount · string · required

The payment amount as a decimal string (e.g. "2500.00"). Must represent a positive value in the currency’s standard unit.

currency · string · required

ISO 4217 three-letter currency code. Example: NGN.

reference · string

A unique merchant-defined transaction reference. If omitted, Paylink auto-generates one. Must be unique across your account.

callback_url · string

The URL Paylink redirects the customer to after the payment attempt. The payment reference is appended as a query parameter.

webhook_url · 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.

metadata · object

Arbitrary key-value pairs you want to attach to this transaction. Returned as-is on verify and webhook payloads.

{ "order_id": "12345", "customer_tier": "gold" }

merchant_bears_fees · boolean · default: "false"

When true, processing fees are deducted from the merchant settlement rather than added to the customer’s charge. Defaults to false.

Example 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
}

Response

status · string

Indicates whether the initialization request succeeded. A value of "success" means the session was created and the authorization_url is ready to use.

authorization_url · 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.

reference · string

The transaction reference — either the one you supplied or the auto-generated value. Store this; it is required for verification and reconciliation.

Example Response

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

Initialization does not confirm that payment was collected. Payment happens asynchronously after the customer completes the checkout flow. Use the Verify Payment endpoint, Transaction History, or your configured webhook as the authoritative source of payment status.