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

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

<Steps>
  <Step title="Get your API credentials">
    Sign in to the [Paylink Dashboard](https://dashboard.lyseis-pay.com) 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.

    ```bash title="Store credentials as environment variables" theme={null}
    export LYSEIS_API_KEY_ID="your_key_id_here"
    export LYSEIS_API_SECRET="your_secret_here"
    ```
  </Step>

  <Step title="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:

    ```bash title="Set base URL" theme={null}
    export LYSEIS_BASE_URL="https://sandbox.lyseis-pay.com"
    ```
  </Step>

  <Step title="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:

    ```python title="signing.py" theme={null}
    import hashlib
    import hmac
    import time

    API_KEY_ID = "your_key_id_here"
    API_SECRET = "your_secret_here"

    body = '{"email":"customer@example.com","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,
    }
    ```

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

  <Step title="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**

    ```http title="POST /payments/initialize" theme={null}
    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>
    ```

    ```json title="Request body" 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"
    }
    ```

    **Response**

    ```json title="200 OK" theme={null}
    {
      "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](/guides/accept-payments#use-sandbox-test-cards) to simulate different payment outcomes.
  </Step>

  <Step title="Verify the payment">
    After your customer completes checkout (or your webhook fires), confirm the final payment status by calling `GET /payments/verify/{reference}`.

    ```http title="GET /payments/verify/{reference}" theme={null}
    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.
  </Step>
</Steps>

***

<Note>
  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](/authentication) page.
</Note>

## Next Steps

<CardGroup cols={3}>
  <Card title="Authentication" icon="lock" href="/authentication">
    Deep-dive into HMAC-SHA256 signing, required headers, and how to handle auth errors.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/concepts/webhooks">
    Set up your webhook endpoint to receive real-time payment status updates.
  </Card>

  <Card title="Accept Payments" icon="credit-card" href="/guides/accept-payments">
    Build a full end-to-end checkout flow with the Paylink hosted payment page.
  </Card>
</CardGroup>