Skip to content
YusrDocs

Quick start#

This guide takes you from a new account to a confirmed sandbox payment in about ten minutes. You will create a transaction, show its account details, simulate the customer's bank transfer and receive a signed webhook.

Everything here runs in test mode: no real money moves, and you can repeat each step as often as you like.

1. Get your test secret key#

Create an account#

Sign up for a free account. Test keys are issued the moment you verify your email, before any business verification.

https://portal.yusr.ng/signup

Copy the test secret key#

In the dashboard, open Developers → API keys and copy the secret key that starts with sk_test_. It is shown in full only once, so store it in your password manager or secrets store.

Export it as an environment variable#

Every sample in these docs reads the key from YUSR_SECRET_KEY, so it never ends up in your code.

Shell
export YUSR_SECRET_KEY="sk_test_..."

2. Install a library (optional)#

The official libraries handle authentication, idempotency keys, retries and webhook verification for you. The Python samples use the popular requests package directly.

# Nothing to install: curl ships with macOS, Linux and Windows 10+.
curl --version

3. Create a transaction#

A transaction asks your customer to pay a specific amount. Yusr answers with a one-time account number that only accepts money for this payment.

All amounts are integers in kobo (₦1 = 100 kobo), so ₦25,000.00 is 2500000. The reference is your own identifier, such as an order number, and must be unique.

curl https://api.yusr.ng/v1/transactions \
  -H "Authorization: Bearer $YUSR_SECRET_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500000,
    "reference": "order-1042",
    "description": "Order #1042",
    "customer": { "name": "Ada Obi", "email": "ada@example.com" },
    "expires_in": 1800,
    "metadata": { "cart_id": "c_88" }
  }'

The API responds with 201 Created and the new transaction:

JSON
{
  "id": "txn_01JA9Q3K7M2V8X4N6P0R2T5W7Y",
  "object": "transaction",
  "mode": "test",
  "status": "pending",
  "amount": 2500000,
  "amount_received": 0,
  "fee": 37500,
  "fee_bearer": "merchant",
  "net_amount": 2462500,
  "currency": "NGN",
  "reference": "order-1042",
  "description": "Order #1042",
  "customer": { "name": "Ada Obi", "email": "ada@example.com", "phone": null },
  "payment": {
    "account_number": "9951643289",
    "bank_name": "Yusr Test Bank",
    "account_name": "ACME STORES / YUSR",
    "amount": 2500000,
    "expires_at": "2026-10-06T14:30:00.000Z"
  },
  "flags": { "overpaid": false, "underpaid": false, "late": false },
  "payments": [],
  "metadata": { "cart_id": "c_88" },
  "created_at": "2026-10-06T14:00:00.000Z",
  "updated_at": "2026-10-06T14:00:00.000Z",
  "paid_at": null,
  "expires_at": "2026-10-06T14:30:00.000Z"
}

Save the id: you need it to simulate the payment and to look the transaction up later.

4. Show the account details#

Your checkout page shows the customer everything they need to pay from their bank app. All of it is in the payment object:

ShowFieldExample
Amount to transferpayment.amount (kobo)₦25,000.00
Bankpayment.bank_nameYusr Test Bank (in live mode, the partner bank, for example Partner Bank)
Account numberpayment.account_number995 164 3289
Account namepayment.account_nameACME STORES / YUSR
Pay beforepayment.expires_ata countdown to 14:30

In test mode the bank is always Yusr Test Bank, a simulated bank that only exists in the sandbox. The account name carries your business display name, which you can change in Settings → Business profile.

Displaying payment details covers layout, copy buttons, countdowns and accessibility, and includes a drop-in widget.

5. Simulate the transfer#

In the sandbox you play the customer. The simulator credits the account as if a real transfer arrived, and fires the same webhooks and realtime events as a real payment.

curl https://api.yusr.ng/v1/sandbox/transactions/txn_01JA9Q3K7M2V8X4N6P0R2T5W7Y/simulate \
  -H "Authorization: Bearer $YUSR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "paid" }'

The response is the updated transaction. Its status is now paid, paid_at is set and the transfer appears in payments:

JSON
{
  "id": "txn_01JA9Q3K7M2V8X4N6P0R2T5W7Y",
  "object": "transaction",
  "mode": "test",
  "status": "paid",
  "amount": 2500000,
  "amount_received": 2500000,
  "fee": 37500,
  "fee_bearer": "merchant",
  "net_amount": 2462500,
  "currency": "NGN",
  "reference": "order-1042",
  "description": "Order #1042",
  "customer": { "name": "Ada Obi", "email": "ada@example.com", "phone": null },
  "payment": {
    "account_number": "9951643289",
    "bank_name": "Yusr Test Bank",
    "account_name": "ACME STORES / YUSR",
    "amount": 2500000,
    "expires_at": "2026-10-06T14:30:00.000Z"
  },
  "flags": { "overpaid": false, "underpaid": false, "late": false },
  "payments": [
    {
      "id": "pay_01JA9QB2T3W4X5Y6Z7A8B9C0D1",
      "amount": 2500000,
      "payer_name": "ADA OBI",
      "payer_bank": "Partner Bank",
      "payer_account_number": "******6221",
      "received_at": "2026-10-06T14:07:12.000Z"
    }
  ],
  "metadata": { "cart_id": "c_88" },
  "created_at": "2026-10-06T14:00:00.000Z",
  "updated_at": "2026-10-06T14:07:12.000Z",
  "paid_at": "2026-10-06T14:07:12.000Z",
  "expires_at": "2026-10-06T14:30:00.000Z"
}

Try the other outcomes too (underpaid, overpaid, late and expired) on fresh transactions. The sandbox guide explains each one.

6. Receive the webhook#

Webhooks tell your server about payments even when nobody is looking at the checkout page. They are the reliable way to fulfil orders.

Expose an HTTPS endpoint#

Add a POST route to your server, for example /webhooks/yusr. While developing on your laptop, use a tunnelling service such as ngrok or cloudflared to get a public URL that forwards to your local port. A localhost URL does not work, because Yusr's servers make the request.

Register the endpoint#

Register the URL in Developers → Webhooks in the dashboard, or with the API. The response contains the signing secret exactly once: store it as YUSR_WEBHOOK_SECRET.

Verify the signature and respond quickly#

Check the X-Yusr-Signature header against the raw request body, then return a 2xx status within 10 seconds.

curl https://api.yusr.ng/v1/webhooks \
  -H "Authorization: Bearer $YUSR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://shop.example.com/webhooks/yusr",
    "events": ["transaction.paid", "transaction.underpaid", "transaction.overpaid", "transaction.expired"]
  }'

A minimal handler verifies the signature with the raw body and acknowledges the event. The webhooks guide has complete, tested handlers for every language.

# Send a signed sample event to a registered endpoint to check your handler.
curl -X POST https://api.yusr.ng/v1/webhooks/whk_01JA9QF4H8C2M6N0P3R5T7V9X1/test \
  -H "Authorization: Bearer $YUSR_SECRET_KEY"

Now create another transaction and simulate a payment: your endpoint receives a transaction.paid event within seconds. The dashboard's Developers → Webhooks page shows every delivery attempt with its response code and latency.

Next steps#

You have collected your first sandbox payment. Before you go live, read these: