Skip to content

An API you can integrate in an afternoon

Predictable REST endpoints, amounts in integer kobo, signed webhooks and a sandbox that behaves like production. Everything is in the docs; no sales call needed to start.

Your first payment in three calls

Create a transaction, simulate the customer’s transfer in the sandbox, and read the result. Then swap the simulation for a webhook handler.

Full quick start

# 1. Create a transaction (test key from the dashboard)
curl https://api.yusr.ng/v1/transactions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500000,
    "reference": "order-1042",
    "customer": { "name": "Ada Obi", "email": "ada@example.com" }
  }'

# 2. Simulate the customer's transfer (sandbox only)
curl -X POST https://api.yusr.ng/v1/sandbox/transactions/txn_.../simulate \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "paid" }'

Official libraries

Use a library for the boring parts: retries, idempotency, signature checks. Or call the REST API directly from any language.

Using Python, Go, Java or something else? The API reference has cURL and Python samples for every endpoint, and the OpenAPI document can generate a client for most languages.

  • Typed client for Node.js 18+ with automatic idempotency keys, retries, webhook verification, pagination and a waitForPayment helper.

    npm install @yusr/node
  • An accessible payment widget and live transaction updates with short-lived client tokens. Your secret key never reaches the browser.

    npm install @yusr/js
  • PHP 8.1+ client with typed exceptions, safe retries, auto-pagination and webhook verification, plus a Laravel example.

    composer require yusr/yusr-php

Verify, deduplicate, fulfil

Every delivery carries an HMAC-SHA256 signature over a timestamp and the raw body. Verify it with one call, reply 2xx within 10 seconds, and use the event id to ignore duplicates.

Webhooks guide

Express webhook handler
import express from 'express';
import { Yusr } from '@yusr/node';

const app = express();

app.post('/webhooks/yusr', express.raw({ type: 'application/json' }), (req, res) => {
  const event = Yusr.webhooks.constructEvent(
    req.body, // raw bytes, not parsed JSON
    req.headers,
    process.env.YUSR_WEBHOOK_SECRET,
  );
  if (event.type === 'transaction.paid') {
    fulfilOrder(event.data.transaction.reference);
  }
  res.sendStatus(200); // within 10 seconds
});

What else is in the box

Error catalogueChangelog

  • OpenAPI 3.1

    A machine-readable description of every endpoint, request and response. Import it into your API client or generate types.

  • Sandbox simulator

    Trigger paid, underpaid, overpaid, late and expired outcomes with one request.

  • Live events

    Push payment status to your checkout page the instant it changes.

  • Safe retries

    Idempotency keys on every create call, and stable error codes with the fix spelled out.

  • Key management

    Separate test and live keys, rolling without downtime, and IP allowlists for live keys.

  • Request logs

    The last 30 days of API requests and every webhook attempt, in the dashboard.

Get your test keys in minutes

Create an account, copy your test keys and make a sandbox transaction. Nothing is charged until real money arrives.