Skip to content
YusrDocs

Displaying payment details#

Your customer pays by typing the details you show into their bank app. A clear payment screen is the biggest factor in whether they pay the right amount, to the right account, before it expires. This page covers what to show, how to lay it out and how to confirm the payment.

Transfer exactly

₦25,000.00

Bank
Partner Bank
Account number
Account name
ACME STORES / YUSR

Pay before 14:30, in 29:41

Waiting for your transfer

Example layout: amount first, then the three details the payer types into their bank app, then the deadline and a live status.

What to show#

Everything comes from the payment object of the transaction:

ElementFieldGuidance
Amountpayment.amountShow it first and largest, formatted in naira (₦25,000.00). Say exactly.
Bankpayment.bank_nameShow the value from the response. It can vary between transactions, so never hard-code it.
Account numberpayment.account_numberGroup as 3-3-4 for reading (991 234 5678), but copy the plain 10 digits.
Account namepayment.account_nameTell the customer they will see this name in their bank app. It confirms they're paying you.
Expirypayment.expires_atShow a countdown and the clock time ("Pay before 14:30").
Statusstatus"Waiting for your transfer", then "Payment received" when confirmed.

Prepare the checkout on your server#

Create the transaction and a client token on your server, then pass only what the page needs. Never send your secret key, and don't trust prices sent by the browser: compute the amount on the server.

# 1. Create the transaction
curl https://api.yusr.ng/v1/transactions \
  -H "Authorization: Bearer $YUSR_SECRET_KEY" \
  -H "Idempotency-Key: checkout-order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500000,
    "reference": "order-1042",
    "customer": { "name": "Ada Obi", "email": "ada@example.com" }
  }'

# 2. Create a client token for the checkout page (valid 30 minutes)
curl -X POST https://api.yusr.ng/v1/transactions/txn_01JA9Q3K7M2V8X4N6P0R2T5W7Y/client-token \
  -H "Authorization: Bearer $YUSR_SECRET_KEY"

Use the ready-made widget#

The fastest route is renderPaymentWidget from @yusr/js. It follows every guideline on this page: copy buttons with screen-reader announcements, a countdown, a live status region and a success state.

HTML
<div id="pay"></div>
<script src="https://unpkg.com/@yusr/js@1/dist/yusr.global.js"></script>
<script>
  fetch('/checkout/1042', { method: 'POST' })
    .then((res) => res.json())
    .then(({ transactionId, clientToken, transaction }) => {
      Yusr.renderPaymentWidget('#pay', {
        clientToken,
        transactionId,
        transaction, // renders immediately; live updates take over once connected
        baseUrl: 'https://api.yusr.ng',
        onPaid: () => (window.location.href = '/orders/1042/thank-you'),
      });
    });
</script>

Match it to your brand with CSS variables on .yusr-widget, such as --yusr-accent, --yusr-radius and --yusr-font. The root element also carries data-status and data-tone attributes for your own styles.

Build your own#

If you design your own screen, this React component shows the essentials: formatted amount, grouped account number with copy buttons, a countdown and a live status driven by realtime events.

TSX
'use client';

import { useEffect, useState } from 'react';
import { formatNaira, subscribeToTransaction } from '@yusr/js';

const groupAccount = (n) => n.replace(/^(\d{3})(\d{3})(\d{4})$/, '$1 $2 $3');

function useCountdown(expiresAt) {
  const [left, setLeft] = useState(() => Date.parse(expiresAt) - Date.now());
  useEffect(() => {
    const id = setInterval(() => setLeft(Date.parse(expiresAt) - Date.now()), 1000);
    return () => clearInterval(id);
  }, [expiresAt]);
  const s = Math.max(0, Math.floor(left / 1000));
  return { expired: s === 0, label: `${Math.floor(s / 60)}:${String(s % 60).padStart(2, '0')}` };
}

function CopyButton({ value, label }) {
  const [copied, setCopied] = useState(false);
  return (
    <button
      type="button"
      onClick={async () => {
        await navigator.clipboard.writeText(value);
        setCopied(true);
        setTimeout(() => setCopied(false), 2000);
      }}
      aria-label={`Copy ${label}`}
    >
      {copied ? 'Copied' : 'Copy'}
      <span className="sr-only" aria-live="polite">
        {copied ? `${label} copied` : ''}
      </span>
    </button>
  );
}

export function PayByTransfer({ transactionId, clientToken, initial, apiOrigin }) {
  const [txn, setTxn] = useState(initial);
  const { expired, label } = useCountdown(txn.payment.expires_at);

  useEffect(() => {
    const sub = subscribeToTransaction({
      clientToken,
      transactionId,
      baseUrl: apiOrigin,
      onState: setTxn, // current state on every (re)connect, then each update
    });
    return () => sub.unsubscribe();
  }, [clientToken, transactionId, apiOrigin]);

  if (txn.status === 'paid' || txn.status === 'overpaid') {
    return <p role="status">Payment received. Thank you!</p>;
  }

  const { payment } = txn;
  return (
    <section aria-labelledby="pay-title">
      <h2 id="pay-title">Pay by bank transfer</h2>
      <p>
        Transfer exactly <strong>{formatNaira(payment.amount)}</strong>{' '}
        <CopyButton value={String(payment.amount / 100)} label="amount" />
      </p>
      <dl>
        <dt>Bank</dt>
        <dd>{payment.bank_name}</dd>
        <dt>Account number</dt>
        <dd>
          <span style={{ fontVariantNumeric: 'tabular-nums' }}>
            {groupAccount(payment.account_number)}
          </span>{' '}
          <CopyButton value={payment.account_number} label="account number" />
        </dd>
        <dt>Account name</dt>
        <dd>{payment.account_name}</dd>
      </dl>
      <p>{expired ? 'This account has expired.' : `Expires in ${label}`}</p>
      <p role="status">
        {txn.status === 'underpaid'
          ? `We received ${formatNaira(txn.amount_received)}. Please send the remaining ${formatNaira(payment.amount - txn.amount_received)}.`
          : 'Waiting for your transfer…'}
      </p>
    </section>
  );
}

Layout and copy guidelines#

Amount#

  • Show the amount in naira with two decimals, and say "exactly": "Transfer exactly ₦25,000.00".
  • Warn that bank charges must not be deducted from the amount. If the customer's bank adds a transfer fee, it is charged on top; the amount that arrives must match.
  • Offer a copy button that copies the number without the currency symbol or separators (25000), which bank apps accept.

Account number#

  • Group the digits as 991 234 5678 so they're easy to read aloud and type, but copy the unbroken 9912345678.
  • Use a monospaced or tabular-numbers font so digits don't shift.
  • Each account number belongs to one transaction. Never reuse it for another order, print it on invoices for future use, or save it as a customer's "permanent" account.

Bank and account name#

  • Show the bank exactly as returned: the customer has to pick it from a list in their app.
  • Explain the account name: "You'll see ACME STORES / YUSR when you enter the account number." That confirmation is what reassures customers they're paying the right business.

Expiry#

  • Show a countdown from payment.expires_at, and the clock time for customers who switch apps.
  • Calculate the countdown from the server's expires_at, not from when the page loaded. Device clocks can be wrong; if precision matters, send your server's current time with the page and correct for the difference.
  • When the countdown reaches zero, stop showing the account details and offer to start again with a new transaction (new reference).
  • Choose an expires_in that fits how people pay: 30 minutes for an online checkout, up to 72 hours for an invoice.

One transaction per attempt#

Create a transaction when the customer reaches the payment step, and create a new one if they come back after it expires or change their basket. Reusing an old account number leads to late payments that need manual handling.

Confirm the payment#

Show a waiting state ("Waiting for your transfer…") and switch to a clear success state as soon as the payment is confirmed. Customers often stay on the page while they pay from their phone.

  • In the browser, use realtime with a client token. The widget and subscribeToTransaction do this for you.
  • Fulfil the order on your server from the verified webhook, never from the browser event.
  • If the customer reloads the page, render the latest state from your server (updated by webhooks).

Handle the edge cases#

StatusWhat to tell the customer
underpaid"We received ₦12,500.00 of ₦25,000.00. Send the remaining ₦12,500.00 to the same account before it expires."
overpaid"Payment received. You sent more than the amount due; we'll be in touch about the difference."
expired"This account has expired. Don't send money to it. Start a new payment to get a fresh account."
late_payment"Your transfer arrived after the account expired. We've received it and our team will follow up."
cancelled"This payment was cancelled. Don't send money to this account."

What happens to under-, over- and late payments is set in Settings → Payment behaviour: accept them, or refund them to the payer's account. Make sure your customer messages match your settings.

Accessibility#

  • Use real <button> elements for copy actions, with labels such as "Copy account number", and announce "Copied" through an aria-live region.
  • Put the payment status in a role="status" region so screen readers announce "Payment received" without the customer moving focus.
  • Don't rely on colour alone: pair status colours with text and icons.
  • Keep text selectable, so customers can copy details even if the clipboard API is blocked.
  • Make sure the layout works at 360 px wide, with copy buttons at least 44 px tall for touch.
  • Don't update the countdown in a live region every second; announce only important changes, such as one minute remaining.