Paylink Quickstart: Initialize and Verify a Payment

Follow this step-by-step guide to get your API credentials, sign your first request, initialize a payment, and verify it — all in the sandbox.

This guide walks you through everything you need to make your first API call to Paylink. By the end you will have initialized a sandbox payment and received a hosted checkout URL you can open in a browser.

1. Get your API credentials

   Sign in to the Paylink Dashboard and navigate to Settings → API Keys. Create a new key pair to obtain your:

   • API Key ID (X-Key-Id) — a public identifier for the key
   • API Secret — the private value you use to sign requests

   Store the secret somewhere safe (for example, an environment variable). You will not be able to view it again after initial creation.

   Store credentials as environment variables

   export LYSEIS_API_KEY_ID="your_key_id_here"
   export LYSEIS_API_SECRET="your_secret_here"
   
2. Set your base URL to sandbox

   All calls in this guide target the sandbox environment. The sandbox is fully isolated from live funds, so you can experiment freely.

   Environment	API Base URL
   Sandbox	https://sandbox.lyseis-pay.com
   Live	https://live.lyseis-pay.com

   Set the base URL in your environment so you can switch to live later with a single change:

   Set base URL

   export LYSEIS_BASE_URL="https://sandbox.lyseis-pay.com"
   
3. Sign your first request

   Every protected endpoint requires three authentication headers. You build the X-Signature by computing an HMAC-SHA256 digest over {timestamp}:{raw_request_body} using your API secret.

   Here is a reusable Python helper that builds the headers for any request body:

   signing.py

   import hashlib
   import hmac
   import time
   
   API_KEY_ID = "your_key_id_here"
   API_SECRET = "your_secret_here"
   
   body = '{"email":"[e-mail]","amount":"2500.00","currency":"NGN"}'
   timestamp = str(int(time.time()))
   message = f"{timestamp}:{body}".encode()
   signature = hmac.new(API_SECRET.encode(), message, hashlib.sha256).hexdigest()
   
   headers = {
       "Content-Type": "application/json",
       "X-Key-Id": API_KEY_ID,
       "X-Timestamp": timestamp,
       "X-Signature": signature,
   }
   

   Sign the exact bytes you send as the request body. Any change to JSON whitespace after signing — even a single added space — will invalidate the signature and produce a 401 error.

4. Initialize a payment

   Call POST /payments/initialize to create a new payment session. The response contains an authorization_url — redirect your customer there to complete payment on the hosted checkout page.

   Request

   POST /payments/initialize

   POST https://sandbox.lyseis-pay.com/payments/initialize
   Content-Type: application/json
   X-Key-Id: your_key_id_here
   X-Timestamp: 1700000000
   X-Signature: <computed_signature>
   

   Request body

   {
     "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"
   }
   

   Response

   200 OK

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

   Open the authorization_url in your browser to walk through the sandbox checkout flow. Use the sandbox test cards to simulate different payment outcomes.

5. Verify the payment

   After your customer completes checkout (or your webhook fires), confirm the final payment status by calling GET /payments/verify/{reference}.

   GET /payments/verify/{reference}

   GET https://sandbox.lyseis-pay.com/payments/verify/order_12345
   X-Key-Id: your_key_id_here
   X-Timestamp: 1700000060
   X-Signature: <computed_signature>
   

   A successful verification returns a status field of "success" and the full payment record. Store the verified status in your database before fulfilling the order — never rely solely on the callback redirect.

---

This quickstart only covers the essentials of request signing. To understand the full signing algorithm, replay-attack protection, and how to handle authentication errors, read the Authentication page.

Next Steps

Authentication

Deep-dive into HMAC-SHA256 signing, required headers, and how to handle auth errors.

Webhooks

Set up your webhook endpoint to receive real-time payment status updates.

Accept Payments

Build a full end-to-end checkout flow with the Paylink hosted payment page.