REST API · v2 · Production

REST API Built for Scale
One Integration,
Every Payment Method

JSON-first, predictable responses, idempotency keys, cursor-based pagination, and real-time webhook delivery with exponential backoff retries. Every endpoint documented with live examples.

Quick Start Full Reference

PCI DSS Level 1 99.99% uptime SLA <150ms p99

create-payment.sh

# Create a PaymentIntent — charge €49.00
curl https://api.paymentgate.com/v2/payment_intents \
  -u sk_live_Nj8tR3mXpK9wA4sL: \
  -H "Idempotency-Key: ord_4e2b8f1a" \
  -d amount=4900 \
  -d currency=eur \
  -d "payment_method_types[]=card" \
  -d "metadata[order_id]=ORD-7741"

# 201 Created
{
  "id": "pi_3Qa9bLNj8tR3mXpK",
  "object": "payment_intent",
  "amount": 4900,
  "currency": "eur",
  "status": "requires_payment_method",
  "client_secret": "pi_3Qa9bL_secret_...",
  "created": 1745308800
}

150+

Endpoints

Official SDKs

99.99%

Uptime SLA

<150ms

p99 Latency

Quick Start

Up and running in minutes

Three steps from zero to your first successful charge.

Get Your API Key

~30 seconds

Sign up and navigate to the Dashboard. Sandbox keys are issued instantly — no credit card or business verification required during testing.

# Your test keys look like this
sk_test_Nj8tR3mXpK9wA4sL...
pk_test_Nj8tR3mXpK9wA4sL...

Make Your First Charge

~2 minutes

Create a PaymentIntent using a test card number. The full payment lifecycle — created, confirmed, captured — is visible in the sandbox dashboard in real time.

# Test card — always succeeds
4242 4242 4242 4242
Exp: 12/28  CVC: 123

Handle Webhooks

~5 minutes

Register an HTTPS endpoint to receive payment events. Verify the HMAC-SHA256 signature on every delivery before fulfilling orders — replay attacks are real.

# Verify webhook signature
pg-signature: t=1745308800,
  v1=3c4f9a2b8e1d...

Complete Quick Start — curl

Working example

# Step 1 — Create PaymentIntent
curl -X POST https://api.paymentgate.com/v2/payment_intents \
  -u sk_test_Nj8tR3mXpK9wA4sL: \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Idempotency-Key: test_$(uuidgen)" \
  -d amount=9900 \
  -d currency=eur \
  -d "payment_method_types[]=card"

# Step 2 — Confirm with test card token
curl -X POST https://api.paymentgate.com/v2/payment_intents/pi_.../confirm \
  -u sk_test_Nj8tR3mXpK9wA4sL: \
  -d payment_method=pm_card_visa

# Step 3 — Receive webhook (payment_intent.succeeded)
POST https://your-server.example.com/webhooks/paymentgate
pg-signature: t=1745308800,v1=3c4f9a2b...

{
  "type": "payment_intent.succeeded",
  "data": { "object": { "id": "pi_3Qa9bL...", "amount": 9900 } }
}

API Resources

API Reference Overview

Eight core resource groups covering the full payment lifecycle.

Payments

Create, confirm, capture, and cancel PaymentIntents across all supported payment methods.

24 endpoints

Refunds

Issue full or partial refunds. Query status and attach metadata for reconciliation.

8 endpoints

Customers

Store customer profiles, attach payment methods, and query billing history for CRM sync.

14 endpoints

Subscriptions

Recurring billing with trials, proration, usage-based pricing, and dunning automation.

18 endpoints

Webhooks

10 endpoints

Disputes

Submit evidence for chargebacks, track dispute status, and accept or contest per-case.

8 endpoints

Payouts

Initiate and track fund transfers to bank accounts or connected merchant accounts.

10 endpoints

Balance

Query available and pending balances, list balance transactions, and export CSV reports.

6 endpoints

Method	Endpoint	Description
POST	/v2/payment_intents	Create a PaymentIntent
GET	/v2/payment_intents/:id	Retrieve a PaymentIntent
POST	/v2/payment_intents/:id/confirm	Confirm a PaymentIntent
POST	/v2/payment_intents/:id/capture	Capture funds on an authorised intent
POST	/v2/payment_intents/:id/cancel	Cancel a PaymentIntent
GET	/v2/payment_intents	List PaymentIntents (cursor-paginated)
POST	/v2/payment_methods	Create a PaymentMethod (tokenise card)
GET	/v2/payment_methods/:id	Retrieve a PaymentMethod

Method	Endpoint	Description
POST	/v2/refunds	Create a refund (full or partial)
GET	/v2/refunds/:id	Retrieve a refund
POST	/v2/refunds/:id	Update refund metadata
GET	/v2/refunds	List refunds

Method	Endpoint	Description
POST	/v2/customers	Create a customer
GET	/v2/customers/:id	Retrieve a customer
POST	/v2/customers/:id	Update customer fields
DEL	/v2/customers/:id	Delete customer (GDPR erasure)
GET	/v2/customers	List customers

Method	Endpoint	Description
POST	/v2/subscriptions	Create a subscription
GET	/v2/subscriptions/:id	Retrieve a subscription
POST	/v2/subscriptions/:id	Upgrade / downgrade plan
DEL	/v2/subscriptions/:id	Cancel (immediate or period-end)
GET	/v2/subscriptions	List subscriptions

Method	Endpoint	Description
POST	/v2/webhook_endpoints	Register a webhook endpoint
GET	/v2/webhook_endpoints/:id	Retrieve endpoint config
POST	/v2/webhook_endpoints/:id	Update subscribed events
DEL	/v2/webhook_endpoints/:id	Delete endpoint

Method	Endpoint	Description
GET	/v2/disputes/:id	Retrieve a dispute
POST	/v2/disputes/:id	Submit evidence
POST	/v2/disputes/:id/close	Accept dispute (waive counter)
GET	/v2/disputes	List disputes

Method	Endpoint	Description
POST	/v2/payouts	Create manual payout
GET	/v2/payouts/:id	Retrieve payout status
POST	/v2/payouts/:id/cancel	Cancel pending payout
GET	/v2/payouts	List payouts

Method	Endpoint	Description
GET	/v2/balance	Retrieve current balance
GET	/v2/balance/history	List balance transactions
GET	/v2/balance/history/:id	Retrieve a balance transaction

Authentication

API Keys & Authentication

All requests are authenticated with your secret API key. Never expose secret keys in client-side code.

Bearer Token (preferred)

Pass your secret key in the Authorization header as a Bearer token. Use the publishable key (pk_) only for client-side tokenisation via our hosted fields SDK.

# Secret key — server-side only
Authorization: Bearer sk_live_Nj8tR3mXpK9w...

# HTTP Basic Auth (username = secret key)
curl https://api.paymentgate.com/v2/charges \
  -u sk_live_Nj8tR3mXpK9w:

Key Types

Each account has two pairs of keys — test and live. Test mode is fully isolated; no real money moves and test events do not affect live data.

Publishable

pk_test_ / pk_live_

Client-side · tokenisation only

Secret

sk_test_ / sk_live_

Server-side · full API access

Never commit secret keys to version control. Use environment variables.

Webhook Signature Verification

Every webhook delivery includes a pg-signature header containing an HMAC-SHA256 of the raw body. Verify this before processing to prevent replay attacks and spoofed payloads. Our SDKs provide a one-line helper for this.

// Node.js — one-liner verification
const event = pg.webhooks.constructEvent(
  req.rawBody,
  req.headers['pg-signature'],
  process.env.PG_WEBHOOK_SECRET
);
// throws if signature invalid

Official SDKs

6 Official SDKs

Install with one command. Full types, auto-retry with exponential backoff, and webhook helpers built in.

Node.js

v3.2.1

npm install @paymentgate/node

TypeScript generics · ESM + CJS · Deno/Bun support

Python

v3.1.4

pip install paymentgate

Async/await · Type hints · Django & FastAPI support

PHP

v4.3.0

composer require paymentgate/php

PSR-7/18 · Laravel Facade · Symfony Bundle

v3.0.2

go get github.com/paymentgate/go/v3

Context-aware · Goroutine-safe · Go modules

Ruby

v5.2.3

gem install paymentgate

Rails engine · Sorbet types · Rack middleware

Java

v3.2.0

Spring Boot starter · Reactive WebClient · Maven + Gradle

Full SDK Documentation

Rate Limits

Limits are applied per API key on a sliding 60-second window. Rate-limit headers are included on every response.

# Response headers on every request
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1745308860

# Limit exceeded — HTTP 429
{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Too many requests.",
    "retry_after": 22
  }
}

Idempotency key retries do not consume rate-limit tokens.

Tier	Req / sec	Req / min	Burst
Sandbox	2	100	20
Starter	5	300	60
Growth	17	1,000	200
Enterprise	Custom	Custom	Custom

Versioning Policy

We version the API via the URL path. Breaking changes are never introduced within a major version.

CURRENT v2

Active and fully supported. Cursor pagination, idempotent webhook delivery, 3DS2, and SEPA Direct Debit all landed in v2. All new features ship here.

DEPRECATED v1

Still operational but deprecated. No new features. End-of-life is 31 Dec 2026 — all v1 traffic will return 410 after that date. Migrate to v2 today.

Migration Guide

v1 to v2 migration takes under an hour. The primary change is cursor-based pagination replacing offset-based. All resource IDs and event types are unchanged.

v1 → v2 migration guide

REST API Built for ScaleOne Integration,Every Payment Method