asqash

Asqash API

Let your customers send their bill, cart or booking to someone else to pay, or share it with a group. You create a payment request from your server, we give you a link, and we tell you by webhook when it’s paid. When it’s fully paid, we send the money to your bank account.

No code needed? Create payment links in the dashboard instead.

Base URL: https://asqash.com. All bodies are JSON. Amounts are integers in kobo (4500000 is ₦45,000).

Keys and modes

Create keys in Dashboard → Developers and send them as a bearer token:

Authorization: Bearer sk_test_…

Keep keys on your server. Never put them in an app or web page.

Create a payment request

POST/v1/payment-requests

Send an Idempotency-Key header (up to 200 characters). Retrying with the same key returns the same request, so a timeout never creates two.

curl https://asqash.com/v1/payment-requests \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: order_1042" \
  -H "Content-Type: application/json" \
  -d '{
    "sector": "school_fees",
    "merchant_reference": "INV-1042",
    "amount_minor": 18500000,
    "currency": "NGN",
    "beneficiary_label": "Ada O., JSS2 second term",
    "purpose": "Tuition and books",
    "funding_mode": "fixed_share",
    "share_count": 4
  }'
FieldNotes
sectorRequired. See sectors.
merchant_referenceRequired. Your id for the bill. Only one open or paid request per reference.
amount_minorRequired. Total in kobo.
currencyRequired. NGN.
beneficiary_labelRequired, up to 80 characters. Shown to payers. Must not contain long numbers (account or patient numbers).
purposeOptional, up to 200 characters. Not allowed for hospital bills.
funding_modefull (one payer), fixed_share (equal shares) or open (anyone chips in).
share_countFor fixed_share: 2–500. Any rounding goes on the last share.
min_contribution_minorFor open. Smallest payment allowed, except when clearing what’s left.
expires_atOptional ISO time, up to 90 days ahead (default 7 days). If it isn’t fully paid by then, every payer is refunded.
metadataOptional object, returned to you and never shown to payers.

The response includes id, status (open, funded, expired, cancelled), paid_minor and share_url, the link to send to payers.

Sectors

SectorRules
school_feesNone.
hospital_billsPayers see your neutral name (set it in Settings) and “Medical bill” instead of any purpose.
utilitiesTracks delivery: tell us when the token or service was delivered.
online_shoppingTracks delivery.
travelTracks delivery. expires_at is required.
coursesTracks delivery.

Manage requests

GET/v1/payment-requests/:id returns the request and its successful payments.

POST/v1/payment-requests/:id/cancel stops an open request and refunds everyone who paid.

POST/v1/payment-requests/:id/fulfilment with {"status": "delivered"} or "failed", for sectors that track delivery.

GET/v1/events?since=ISO_TIME lists every event, including any whose webhook failed. Use it to catch up after downtime.

Refunds

Refunds always go back to the card or account that paid. There’s no way to send a refund anywhere else.

POST/v1/contributions/:id/refunds with optional amount_minor and reason.

POST/v1/payment-requests/:id/refunds with amount_minor refunds part of a paid request across all payers, in proportion to what each paid. Needs an Idempotency-Key.

A request that’s still collecting can’t be partly refunded, because that would reopen the balance others are paying towards. Cancel it instead. Refunds after you’ve been paid out come out of your next payout.

Webhooks

Set your webhook URL in the dashboard. We POST each event with these headers:

asqash-signature: t=1763380000,v1=5257a869…
asqash-event-id: 9f0c…

To verify, compute HMAC-SHA256 of {t}.{raw body} with your signing secret and compare it with v1. Reject timestamps older than 5 minutes.

const crypto = require('crypto');
function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Answer with any 2xx. Failed deliveries are retried 10 times with growing gaps (about an hour and a half in all). After that, catch up with GET /v1/events. Events may arrive more than once, so use the event id to ignore repeats.

EventWhen
request.createdA request was created.
contribution.succeededSomeone paid. Includes contribution_amount_minor and paid_minor.
request.fundedFully paid. Deliver what was ordered.
settlement.completedThe payout to your bank was sent.
settlement.failedThe payout failed. We’ll contact you.
request.expired / request.cancelledClosed without being paid. Everyone is being refunded.
refund.completed / refund.failedA refund finished or failed.
contribution.refunded_automaticallyA payment arrived after the bill was covered, so it was returned.

Revalidation

For API requests, set a revalidate URL. Before each payment starts, we POST {request_id, merchant_reference, amount_minor, currency} to it, signed like a webhook. Reply {"valid": true} if the bill still stands at that amount. Anything else, or no answer within 5 seconds, stops the payment, so nobody pays for a cart that changed or an item that sold out.

The “Pay with Asqash” button

<div id="pay"></div>
<script src="https://asqash.com/button/v1.js"></script>
<script>
  Asqash.button({
    amount_minor: 4500000, // only used to preview shares
    currency: 'NGN',
    createRequest: (choice) =>
      fetch('/api/asqash/create', {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify(choice),
      }).then((r) => r.json()),
  }).mount('#pay');
</script>

The customer picks how it should be paid. choice holds funding_mode, idempotency_key and, for splits, share_count. Your server adds the amount and bill details, creates the request with your secret key, and returns { share_url }.

Platforms with many sellers

If you run a marketplace, create a sub-merchant for each seller with POST /v1/sub-merchants (external_reference, name, display_name), then pass sub_merchant_id when creating a request. Payers see the seller’s name. Contact us to set up seller payouts.

Errors

{ "error": { "code": "invalid_request", "message": "…", "issues": [ … ] } }
StatusMeaning
401Missing or invalid key.
409Conflict: for example request_already_active or request_not_open.
422Invalid input. issues says which fields.
503A payment provider or your revalidate URL didn’t answer. Safe to retry.

Testing

With a test key, pay on the link using Paystack’s test card:

Card 4084 0840 8408 4081 · any future expiry · CVV 408

Questions? Email hello@asqash.com.