Developer Documentation

Build payments in minutes,
not months

A clean REST API, official SDKs, real-time webhooks, and a full sandbox — everything you need to go from first request to production.

Get API Keys View Reference

99.99%

uptime SLA

< 100ms

avg response

REST + Webhooks

architecture

collect-payment.ts

1import Vestpay from 'vestpay';
2
3const vestpay = new Vestpay({
4  apiKey: process.env.VESTPAY_SECRET_KEY,
5});
6
7const session = await vestpay.sessions.create({
8  amount: 2000,
9  currency: 'GBP',
10  ruleset_id: 'ruleset_xxx',
11  recipient_id: 'rec_xxx',
12  customer: { email: 'user@example.com' },
13});
14
15// Redirect customer to hosted checkout
16redirect(session.checkout_url);

Quickstart

From zero to first payment in 4 steps

terminal

1npm install vestpay
2# or
3pnpm add vestpay
4# or
5yarn add vestpay

API Reference

Explore the endpoints

A concise REST API. Every endpoint returns predictable JSON with consistent error shapes.

Create Session

Create a hosted checkout session. Returns a checkout_url to redirect your customer to.

POST /v1/session

Request

1POST https://api.vestpay.io/v1/session
2Authorization: Bearer vestpay_sk_xxx
3Content-Type: application/json
4
5{
6  "amount": 2000,
7  "currency": "GBP",
8  "ruleset_id": "ruleset_abc",
9  "recipient_id": "rec_xyz789",
10  "customer": {
11    "email": "customer@example.com"
12  },
13  "metadata": {
14    "order_id": "order_001"
15  }
16}

Click “Run Request” to see the response

SDKs & Libraries

Official SDKs for your stack

Drop-in libraries that handle authentication, retries, error parsing, and type safety — so you can focus on your product logic.

Node.js

TypeScript / JavaScript

Full-featured SDK with TypeScript types. Works with Node, Next.js, Remix, and any JS runtime.

npm install vestpay

Python

Python 3.8+

Pythonic SDK with type hints. Compatible with Django, FastAPI, Flask, and standard Python scripts.

pip install vestpay

Coming soon

Go 1.18+

Idiomatic Go client with context support, automatic retries, and full API coverage.

go get github.com/vestpay/vestpay-go

Coming soon

Ruby

Ruby 3.0+

Clean Ruby gem following idiomatic patterns. First-class support for Rails applications.

gem install vestpay

Don't see your language? All endpoints are standard REST — any HTTP client works.

Webhooks & Events

React to every payment in real time

session.completedPOST /your-webhook

1{
2  "event_id": "evt_789xyz012abc",
3  "type": "session.completed",
4  "api_version": "2026-01-01",
5  "created_at": "2026-01-31T03:00:00.000Z",
6  "data": {
7    "session_id": "ses_abc123def456",
8    "amount": 2000,
9    "currency": "GBP",
10    "status": "completed",
11    "recipient_id": "rec_xyz789",
12    "ruleset_id": "ruleset_abc",
13    "customer": {
14      "email": "customer@example.com"
15    },
16    "metadata": {
17      "order_id": "order_001"
18    },
19    "completed_at": "2026-01-31T03:00:00.000Z"
20  }
21}

Session

session.pendingSession created, awaiting payment

session.completedPayment received and confirmed

session.expiredSession window elapsed without payment

session.cancelledSession manually cancelled

Payout

payout.initiatedPayout sent to banking rails

payout.completedFunds arrived in recipient account

payout.failedPayout rejected — requires retry

Recipient

recipient.verifiedBank account verified and active

recipient.suspendedRecipient account suspended

Signed payloads

Every webhook is signed with HMAC-SHA256. Verify the vestpay-signature header before processing.

Automatic retries

Failed deliveries are retried up to 5 times with exponential back-off over 24 hours.

Event log

All events are stored for 30 days. Replay any event directly from the dashboard.

Sub-second delivery

Events are dispatched within milliseconds of the state change in our system.

Resources

Everything you need to ship

Guides, references, and tooling — built to get you unblocked fast.

Quick Start Guide

Step-by-step walkthrough to collect your first payment — from API key to live transaction in under 10 minutes.

Read guide

API Reference

Full endpoint documentation with parameters, request/response shapes, error codes, and field descriptions.

View reference

Test Mode & Sandbox

Use your vestpay_sk_test_ key to simulate payments, payouts, and webhook events — no real money moves.

Open sandbox

Changelog

Track every API update, new field, deprecation, and breaking change. We version our API so you're never surprised.

View changelog

API Status

Real-time uptime dashboard. Subscribe to incidents, maintenance windows, and performance alerts.

Check status

Developer Support

Stuck? Our developer team responds within 1 business day. Enterprise plans include dedicated Slack support.

Get help

Integration best practices

Authentication

All requests require a Bearer token in the Authorization header. Use test keys (vestpay_sk_test_) in development and live keys (vestpay_sk_live_) in production.

Idempotency

Send an Idempotency-Key header on POST requests to safely retry without double-charging. Keys expire after 24 hours.

Error handling

Errors return a consistent shape: { "error": { "code": "...", "message": "...", "param": "..." } } with standard HTTP status codes.

Ready to build?

Start collecting payments
in minutes

Create your free account, grab your API keys, and make your first test payment today. No contracts, no setup fees.

Get API Keys — it's free Talk to our team

No credit card required · Full sandbox access · 99.99% uptime SLA

Build payments in minutes, not months