Quickstart

This guide takes you from nothing to a verified sandbox payment. You will initialise a transaction from your server, redirect the customer to hosted checkout, and confirm the outcome before fulfilling the order. The same code runs on live later with a different key and host.

Before you begin

You need a sandbox merchant account and a test secret key.

Sign in or register at merchant.sandbox.vestrapay.app.
Open Settings → Developers and copy the test secret key. It starts with sk_test_.
Store it as an environment variable on your server. Never put a secret key in browser code, a mobile app or a public repository.

export VESTRAPAY_SECRET_KEY="sk_test_yourkey"

Sandbox and live use different hosts

The integration is identical in both environments. Only the key and the base URL change.

	Sandbox	Live
API base URL	https://api.sandbox.vestrapay.app/v1	https://api.vestrapay.com/v1
Checkout	https://checkout.sandbox.vestrapay.app	https://checkout.vestrapay.com
Dashboard	https://merchant.sandbox.vestrapay.app	https://merchant.vestrapay.com
Secret key prefix	`sk_test_`	`sk_live_`

A sandbox key sent to the live host, or the other way round, is rejected. Keep the base URL in configuration alongside the key so the two always change together.

Initialise, redirect and verify

Initialise the payment from your server

Send the amount and the customer’s details. The email is optional for hosted card checkout but required for pay with transfer, so send it whenever you have it.

curl -X POST https://api.sandbox.vestrapay.app/v1/payment/initialize \
  -H "x-api-key: $VESTRAPAY_SECRET_KEY" \
  -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" }
  }'

const res = await fetch("https://api.sandbox.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();
if (body.status !== "success") {
  throw new Error(`${body.error}: ${body.message}`);
}

const session = body.data;
// Save session.reference on the order, then redirect to session.checkoutUrl

import os
import requests

res = requests.post(
    "https://api.sandbox.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"},
    },
    timeout=15,
)
body = res.json()
if body["status"] != "success":
    raise RuntimeError(f'{body["error"]}: {body["message"]}')

session = body["data"]
# Save session["reference"] on the order, then redirect to session["checkoutUrl"]

<?php
$ch = curl_init("https://api.sandbox.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",
    "customerName" => "Jane Doe",
    "callbackUrl" => "https://yourapp.com/paid",
    "description" => "Order 12345",
    "metadata" => ["orderId" => "ORD_12345"],
  ]),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 15,
]);
$body = json_decode(curl_exec($ch), true);
if (($body["status"] ?? "") !== "success") {
  throw new RuntimeException(($body["error"] ?? "unknown") . ": " . ($body["message"] ?? ""));
}
$session = $body["data"];
// Save $session["reference"] on the order, then redirect to $session["checkoutUrl"]

Read the response

Initialise returns HTTP 201 and the session is in the data object:

{
  "status": "success",
  "data": {
    "reference": "VPY_TXN_ACME001",
    "accessCode": "a1b2c3d4e5f6a1b2",
    "checkoutUrl": "https://checkout.sandbox.vestrapay.app/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"
  }
}

Save data.reference on the order immediately. It is the only identifier you need later, for webhooks and for verification.

Redirect the customer

Send the browser to data.checkoutUrl. Hosted checkout lists the channels enabled for your account and handles card entry, 3-D Secure and the transfer countdown.

Handle the return and the webhook

When checkout finishes, the customer’s browser is sent to your callback URL with query parameters appended:

https://yourapp.com/paid?status=success&reference=VPY_TXN_ACME001&amount=100.00&currency=NGN

At the same time, Vestrapay posts a signed webhook to the endpoint you registered. Either signal can arrive first, and either can be repeated. Neither is proof of payment on its own. Both mean “go and check”.

Verify from your server

Look the payment up by reference with your secret key.

curl https://api.sandbox.vestrapay.app/v1/payment/verify/VPY_TXN_ACME001 \
  -H "x-api-key: $VESTRAPAY_SECRET_KEY"

const res = await fetch(
  `https://api.sandbox.vestrapay.app/v1/payment/verify/${encodeURIComponent(reference)}`,
  { headers: { "x-api-key": process.env.VESTRAPAY_SECRET_KEY } },
);
const body = await res.json();
if (body.status !== "success") throw new Error(body.error);

const payment = body.data;
if (payment.status === "success" && payment.amount === order.amount) {
  // Mark the order paid exactly once
}

import os
import requests

res = requests.get(
    f"https://api.sandbox.vestrapay.app/v1/payment/verify/{reference}",
    headers={"x-api-key": os.environ["VESTRAPAY_SECRET_KEY"]},
    timeout=15,
)
body = res.json()
if body["status"] != "success":
    raise RuntimeError(body["error"])

payment = body["data"]
if payment["status"] == "success" and payment["amount"] == order.amount:
    pass  # Mark the order paid exactly once

<?php
$ch = curl_init("https://api.sandbox.vestrapay.app/v1/payment/verify/" . rawurlencode($reference));
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER => ["x-api-key: " . getenv("VESTRAPAY_SECRET_KEY")],
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 15,
]);
$body = json_decode(curl_exec($ch), true);
if (($body["status"] ?? "") !== "success") {
  throw new RuntimeException($body["error"] ?? "verify_failed");
}
$payment = $body["data"];
if ($payment["status"] === "success" && $payment["amount"] === $order["amount"]) {
  // Mark the order paid exactly once
}

A successful lookup returns HTTP 200:

{
  "status": "success",
  "data": {
    "id": "3f2a0c1e-8b44-4d91-9c2a-1a2b3c4d5e6f",
    "reference": "VPY_TXN_ACME001",
    "amount": "100.00",
    "total": "101.50",
    "amountSettled": "100.00",
    "currency": "NGN",
    "status": "success",
    "channel": "card",
    "fees": "1.50",
    "merchantBearsCost": false,
    "paidAt": "2026-05-10T14:30:00.000Z",
    "metadata": { "orderId": "ORD_12345" }
  }
}

Anatomy of the initialise response

Field	Meaning
`reference`	Vestrapay’s identifier for this transaction, in the form `VPY_TXN_…`. Generated by Vestrapay. Use it for verification and support.
`accessCode`	A short-lived credential for the checkout calls of this one payment. Valid for 60 minutes.
`checkoutUrl`	The hosted checkout page for this payment, on the checkout host of the environment you called.
`amount`	The amount you asked to collect, echoed back as a string.
`cardFee`, `transferFee`	The fee that applies on each channel.
`cardTotal`, `transferTotal`	What the customer pays on each channel when the customer bears the fee.
`merchantBearsCost`	When true, the customer pays exactly `amount` and the fee is taken from your side.
`channels`	The channels available for this payment.
`status`	Always `pending` at this point.

Accept payments covers every request field, including metadata and distribution.

Fulfilment rules

These rules keep you safe whichever signal arrives first. They matter more than any other part of the integration.

Never fulfil from the browser return alone. Query parameters on the callback URL can be edited by anyone. Always call verify from your server.
Fulfil only on success with the right amount. Check that data.status is success and that data.amount equals the amount you expected for that order. A mismatch should be held for review, not fulfilled.
Fulfil once. Webhooks are retried and customers reload pages. Look the order up by reference, return early if it is already paid, and mark it paid inside a transaction or with a unique constraint. Verify a payment shows the pattern.
Keep the reference on the order. It is how you reconcile, answer support requests and match webhooks to orders.
Treat any other status as not paid. Pending and processing mean wait. Failed and abandoned are terminal. Let the customer start a new payment rather than reusing the old reference.

Next steps

Register a webhook

Receive payment outcomes without polling, and verify the signature.

Test payments

Mock cards and transfer simulation for the sandbox.

Split a collection

Send parts of each payment to different bank accounts.

Go live

KYB, live keys and the production checklist.

Get started

Accept payments

Services & splits

Partners

Settlements

Before you begin

Sandbox and live use different hosts

Initialise, redirect and verify

Anatomy of the initialise response

Fulfilment rules

Next steps

Register a webhook

Test payments

Split a collection

Go live

​Before you begin

​Sandbox and live use different hosts

​Initialise, redirect and verify

​Anatomy of the initialise response

​Fulfilment rules

​Next steps

Register a webhook

Test payments

Split a collection

Go live

Before you begin

Sandbox and live use different hosts

Initialise, redirect and verify

Anatomy of the initialise response

Fulfilment rules

Next steps