Developers

A REST API that behaves like one

Predictable resources, idempotency keys on every write, signed webhooks with replay, and a sandbox that returns the same error codes as production. The reference below is the whole surface, not a selection.

214ms
Median authorisation: 99.995%
Rolling 12-month uptime: 2016-11-04
API version in force

Reference

The whole surface

Eight resources, versioned by date rather than by number, with the version pinned per API key. A new version never arrives without you asking for it.

Method	Path	Description
POST	/v1/payments	Create and authorise a payment against a token or a stored credential.
POST	/v1/payments/{id}/capture	Capture all or part of a previously authorised payment.
POST	/v1/payments/{id}/refund	Refund a captured payment, in full or partially, against the original credential.
GET	/v1/payments	List payments, filtered by status, reference, date range or settlement batch.
POST	/v1/payouts	Submit a single payout or a batch of up to 50,000 instructions.
GET	/v1/balances	Read available and pending balances per currency, with the next funding date.
GET	/v1/settlements/{id}/lines	Read a settlement batch line by line, with interchange and fees itemised.
POST	/v1/webhook_endpoints	Register an endpoint and receive the signing secret used to verify deliveries.

The API

One endpoint, one response, no surprises

A payment is a single POST. The response carries the fee breakdown, the risk decision and the settlement batch, so nothing has to be looked up afterwards.

POST /v1/payments

Request

curl https://api.northgatepay.example/v1/payments \
  -H "Authorization: Bearer ngp_live_9f2c..." \
  -H "Idempotency-Key: ord_88213-a" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4250,
    "currency": "GBP",
    "token": "tok_2Rf8Xq4mVn",
    "reference": "ORD-88213",
    "capture": true
  }'

Response

HTTP/1.1 201 Created
x-northgate-request-id: req_7Kd0Wm

{
  "id": "pay_3QhLm2Vx",
  "status": "captured",
  "amount": 4250,
  "currency": "GBP",
  "reference": "ORD-88213",
  "network": "visa",
  "scheme_response": "00",
  "risk": { "score": 7, "decision": "accept" },
  "exemption": "transaction_risk_analysis",
  "settlement": { "batch": "stl_2026_02_11", "date": "2026-02-12" },
  "fees": { "total": 80, "interchange": 43, "scheme": 7, "northgate": 30 },
  "latency_ms": 198
}

Client libraries

Generated from the same specification

Each library is generated from the OpenAPI document that describes the API, then hand-reviewed. They release together, on the same day.

Node.js

Latest 6.4.2

npm install @northgate/node

Python

Latest 5.1.0

pip install northgate

Ruby

Latest 4.9.3

gem install northgate

Go

Latest 3.7.1

go get northgatepay.example/go/v3

PHP

Latest 4.2.6

composer require northgate/northgate-php

Java

Latest 2.8.4

implementation "example.northgatepay:sdk:2.8.4"

Webhooks

Signed, ordered, replayable

Deliveries are signed with a per-endpoint secret, retried on an exponential schedule for 72 hours, and replayable from the console for any window in the last 30 days.

payment.authorised
payment.captured
payment.refunded
payment.disputed
payout.submitted
payout.settled
payout.returned
settlement.published

Next step

Read the reference, then send one request

A sandbox key is issued in the console without a sales conversation, and it returns the same error codes production does. When you are ready to talk commercials, an engineer takes the call.

Open the API reference Talk to sales