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

# Quickstart

> Initialize a payment with your secret key and send the customer to Vestrapay checkout.

You need a Vestrapay merchant account and a test secret key from the dashboard (Settings → Developers).

<Steps>
  <Step title="Initialize from your server">
    <CodeGroup>
      ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl -X POST https://server.staging.vestrapay.app/v1/payment/initialize \
        -H "x-api-key: sk_test_yourkey" \
        -H "Content-Type: application/json" \
        -d '{
          "amount": "100.00",
          "email": "customer@email.com",
          "customerName": "Jane Doe",
          "callbackUrl": "https://yourapp.com/paid",
          "description": "Order 12345",
          "metadata": { "orderId": "ORD_12345" }
        }'
      ```

      ```javascript Node theme={"theme":{"light":"github-light","dark":"github-dark"}}
      const res = await fetch("https://server.staging.vestrapay.app/v1/payment/initialize", {
        method: "POST",
        headers: {
          "x-api-key": process.env.VESTRAPAY_SECRET_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          amount: "100.00",
          email: "customer@email.com",
          customerName: "Jane Doe",
          callbackUrl: "https://yourapp.com/paid",
          description: "Order 12345",
          metadata: { orderId: "ORD_12345" },
        }),
      });
      const body = await res.json();
      const session = body.data;
      // redirect the customer to session.checkoutUrl
      ```

      ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
      import os, requests

      res = requests.post(
          "https://server.staging.vestrapay.app/v1/payment/initialize",
          headers={"x-api-key": os.environ["VESTRAPAY_SECRET_KEY"]},
          json={
              "amount": "100.00",
              "email": "customer@email.com",
              "customerName": "Jane Doe",
              "callbackUrl": "https://yourapp.com/paid",
              "description": "Order 12345",
              "metadata": {"orderId": "ORD_12345"},
          },
      )
      session = res.json()["data"]
      ```

      ```php PHP theme={"theme":{"light":"github-light","dark":"github-dark"}}
      $ch = curl_init("https://server.staging.vestrapay.app/v1/payment/initialize");
      curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => [
          "x-api-key: " . getenv("VESTRAPAY_SECRET_KEY"),
          "Content-Type: application/json",
        ],
        CURLOPT_POSTFIELDS => json_encode([
          "amount" => "100.00",
          "email" => "customer@email.com",
          "callbackUrl" => "https://yourapp.com/paid",
        ]),
        CURLOPT_RETURNTRANSFER => true,
      ]);
      $session = json_decode(curl_exec($ch), true)["data"];
      ```
    </CodeGroup>
  </Step>

  <Step title="Response">
    HTTP 201. The session is in `data`:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "status": "success",
      "data": {
        "reference": "VPY_TXN_ACME001",
        "accessCode": "a1b2c3d4e5f6a1b2",
        "checkoutUrl": "https://checkout.vestrapay.com/a1b2c3d4e5f6a1b2",
        "amount": "100.00",
        "cardFee": "1.50",
        "transferFee": "1.00",
        "cardTotal": "101.50",
        "transferTotal": "101.00",
        "currency": "NGN",
        "merchantBearsCost": false,
        "channels": ["card", "bank_transfer", "bank_payment", "ussd"],
        "status": "pending"
      }
    }
    ```

    Store `data.reference` on the order and redirect the customer to `data.checkoutUrl`.
  </Step>

  <Step title="Customer pays">
    Hosted checkout shows the channels you have enabled. Card uses hosted fields. Transfer shows a dedicated virtual account.
  </Step>

  <Step title="Handle the return, then verify">
    When checkout finishes, the browser hits your `callbackUrl` with `status`, `reference`, `amount`, and `currency` as query params. We also POST `payment.completed` to your webhook. On either signal, [verify](/payments/verify) the reference before you fulfill.
  </Step>
</Steps>