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.
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.
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.
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.
The API responds with 201 Created and the new transaction:
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:
| Show | Field | Example |
|---|---|---|
| Amount to transfer | payment.amount (kobo) | ₦25,000.00 |
| Bank | payment.bank_name | Yusr Test Bank (in live mode, the partner bank, for example Partner Bank) |
| Account number | payment.account_number | 995 164 3289 |
| Account name | payment.account_name | ACME STORES / YUSR |
| Pay before | payment.expires_at | a 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.
The response is the updated transaction. Its status is now paid, paid_at is set and the transfer appears in
payments:
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.
A minimal handler verifies the signature with the raw body and acknowledges the event. The webhooks guide has complete, tested handlers for every language.
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: