Libraries and sample code

Vestrapay does not publish an official SDK or client library at the moment. The API is small and uses plain JSON over HTTPS, so any HTTP client works. This page gives you tested patterns for the pieces every integration needs: a thin client, safe error handling, verification and webhook signature checking.

When an official SDK ships, it will be announced here and on vestrapay.com. Code written against the raw API will keep working.

Configuration

Read two values from the environment and nothing else. Switching from sandbox to live then means changing configuration, not code. The same secret key verifies webhook signatures; see Webhooks.

Variable	Sandbox value	Live value
VESTRAPAY_SECRET_KEY	`sk_test_…`	`sk_live_…`
VESTRAPAY_API_URL	https://api.sandbox.vestrapay.app/v1	https://api.vestrapay.com/v1

A thin client

The client below sends the secret key, sets a timeout, unwraps the envelope and raises a typed error that carries the error code and the request ID. It is deliberately small. Copy it, then add logging and metrics for your stack.

class VestrapayError extends Error {
  constructor({ error, message, requestId, httpStatus }) {
    super(`${error}: ${message}`);
    this.code = error;
    this.requestId = requestId;
    this.httpStatus = httpStatus;
  }
}

async function vestrapay(method, path, body) {
  const res = await fetch(`${process.env.VESTRAPAY_API_URL}${path}`, {
    method,
    headers: {
      "x-api-key": process.env.VESTRAPAY_SECRET_KEY,
      "Content-Type": "application/json",
    },
    body: body ? JSON.stringify(body) : undefined,
    signal: AbortSignal.timeout(15_000),
  });

  const requestId = res.headers.get("x-request-id");
  const payload = await res.json();

  if (payload.status !== "success") {
    throw new VestrapayError({
      error: payload.error ?? "unknown_error",
      message: payload.message ?? "",
      requestId,
      httpStatus: res.status,
    });
  }
  return payload.data;
}

export const initialise = (payment) => vestrapay("POST", "/payment/initialize", payment);
export const verify = (reference) =>
  vestrapay("GET", `/payment/verify/${encodeURIComponent(reference)}`);

import os
import requests


class VestrapayError(Exception):
    def __init__(self, error, message, request_id, http_status):
        super().__init__(f"{error}: {message}")
        self.code = error
        self.request_id = request_id
        self.http_status = http_status


def _call(method, path, json=None):
    res = requests.request(
        method,
        os.environ["VESTRAPAY_API_URL"] + path,
        headers={"x-api-key": os.environ["VESTRAPAY_SECRET_KEY"]},
        json=json,
        timeout=15,
    )
    payload = res.json()
    if payload.get("status") != "success":
        raise VestrapayError(
            payload.get("error", "unknown_error"),
            payload.get("message", ""),
            res.headers.get("x-request-id"),
            res.status_code,
        )
    return payload["data"]


def initialise(payment: dict) -> dict:
    return _call("POST", "/payment/initialize", payment)


def verify(reference: str) -> dict:
    return _call("GET", f"/payment/verify/{reference}")

<?php
final class VestrapayError extends RuntimeException {
  public function __construct(
    public string $errorCode,
    string $message,
    public ?string $requestId,
    public int $httpStatus,
  ) {
    parent::__construct("$errorCode: $message");
  }
}

function vestrapay(string $method, string $path, ?array $body = null): array {
  $requestId = null;
  $ch = curl_init(getenv("VESTRAPAY_API_URL") . $path);
  curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => $method,
    CURLOPT_HTTPHEADER => [
      "x-api-key: " . getenv("VESTRAPAY_SECRET_KEY"),
      "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => $body ? json_encode($body) : null,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_HEADERFUNCTION => function ($ch, $line) use (&$requestId) {
      if (stripos($line, "x-request-id:") === 0) {
        $requestId = trim(substr($line, 13));
      }
      return strlen($line);
    },
  ]);
  $payload = json_decode(curl_exec($ch), true) ?? [];
  $httpStatus = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

  if (($payload["status"] ?? "") !== "success") {
    throw new VestrapayError(
      $payload["error"] ?? "unknown_error",
      $payload["message"] ?? "",
      $requestId,
      $httpStatus,
    );
  }
  return $payload["data"];
}

Initialise

Use the client to create a payment. The reference is generated by Vestrapay, so you save it after the call returns.

const session = await initialise({
  amount: order.amount, // "250.00"
  email: order.customerEmail,
  callbackUrl: "https://yourapp.com/paid",
  metadata: { orderId: order.id },
});

await db.orders.update(order.id, { vestrapayReference: session.reference });
// redirect to session.checkoutUrl

session = initialise({
    "amount": order.amount,  # "250.00"
    "email": order.customer_email,
    "callbackUrl": "https://yourapp.com/paid",
    "metadata": {"orderId": order.id},
})

order.vestrapay_reference = session["reference"]
order.save()
# redirect to session["checkoutUrl"]

$session = vestrapay("POST", "/payment/initialize", [
  "amount" => $order["amount"], // "250.00"
  "email" => $order["customer_email"],
  "callbackUrl" => "https://yourapp.com/paid",
  "metadata" => ["orderId" => $order["id"]],
]);

saveReference($order["id"], $session["reference"]);
// redirect to $session["checkoutUrl"]

Initialise is not idempotent. Every successful call creates a new transaction with a new reference. If a call times out, you cannot know whether a transaction was created. It is safe to initialise again, because an unpaid transaction simply expires, but make sure only the reference you finally redirect the customer to is stored on the order.

Verify and fulfil once

This pattern combines verification with idempotent fulfilment. It is the one to copy for both your webhook handler and your callback page.

async function settleOrder(reference) {
  const order = await db.orders.findByReference(reference);
  if (!order) return { handled: false, reason: "unknown_reference" };
  if (order.status === "paid") return { handled: true, reason: "already_paid" };

  const payment = await verify(reference);

  if (payment.status !== "success") {
    return { handled: false, reason: `payment_${payment.status}` };
  }
  if (payment.amount !== order.amount) {
    await flagForReview(order, payment); // never fulfil on a mismatch
    return { handled: false, reason: "amount_mismatch" };
  }

  // Unique constraint or conditional update so concurrent calls fulfil once
  const changed = await db.orders.markPaidIfPending(order.id, payment.paidAt);
  if (changed) await fulfil(order);
  return { handled: true, reason: "paid" };
}

def settle_order(reference: str) -> dict:
    order = db.orders.find_by_reference(reference)
    if order is None:
        return {"handled": False, "reason": "unknown_reference"}
    if order.status == "paid":
        return {"handled": True, "reason": "already_paid"}

    payment = verify(reference)

    if payment["status"] != "success":
        return {"handled": False, "reason": f"payment_{payment['status']}"}
    if payment["amount"] != order.amount:
        flag_for_review(order, payment)  # never fulfil on a mismatch
        return {"handled": False, "reason": "amount_mismatch"}

    # Conditional update so concurrent calls fulfil once
    if db.orders.mark_paid_if_pending(order.id, payment["paidAt"]):
        fulfil(order)
    return {"handled": True, "reason": "paid"}

function settleOrder(string $reference): array {
  $order = findOrderByReference($reference);
  if (!$order) return ["handled" => false, "reason" => "unknown_reference"];
  if ($order["status"] === "paid") return ["handled" => true, "reason" => "already_paid"];

  $payment = vestrapay("GET", "/payment/verify/" . rawurlencode($reference));

  if ($payment["status"] !== "success") {
    return ["handled" => false, "reason" => "payment_" . $payment["status"]];
  }
  if ($payment["amount"] !== $order["amount"]) {
    flagForReview($order, $payment); // never fulfil on a mismatch
    return ["handled" => false, "reason" => "amount_mismatch"];
  }

  // Conditional update so concurrent calls fulfil once
  if (markPaidIfPending($order["id"], $payment["paidAt"])) {
    fulfil($order);
  }
  return ["handled" => true, "reason" => "paid"];
}

Compare amounts as strings, or as decimals. Do not parse them to binary floating point. If your records store “250.5”, normalise to two decimal places before comparing with “250.50”.

Verify a webhook signature

Signature checking needs the raw request body, so it is covered with the webhook payload and retry behaviour on the Webhooks page, with the same three languages.

Handling errors well

Situation	What to do
Network timeout or connection reset	Retry reads (verify) with backoff. For initialise, see the note above.
HTTP 5xx or `processor.unavailable`	Retry with exponential backoff. The condition is temporary.
HTTP 4xx	Do not retry unchanged. The request is wrong or the state does not allow it. Fix and resend, or surface the message.
`invalid_credentials`, `invalid_key_environment`	A configuration problem. Alert your team. Retrying will not help.

Always log the X-Request-Id response header with the error code. See Errors.

Get started

Accept payments

Services & splits

Partners

Settlements

Libraries and sample code

Configuration

A thin client

Initialise

Verify and fulfil once

Verify a webhook signature

Handling errors well

​Configuration

​A thin client

​Initialise

​Verify and fulfil once

​Verify a webhook signature

​Handling errors well

Configuration

A thin client

Initialise

Verify and fulfil once

Verify a webhook signature

Handling errors well