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_…sk_test_keys use Paystack test mode. Nothing real is charged and payouts are simulated unless you add a test bank account.sk_live_keys move real money. They’re available once your business is verified.
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
}'| Field | Notes |
|---|---|
sector | Required. See sectors. |
merchant_reference | Required. Your id for the bill. Only one open or paid request per reference. |
amount_minor | Required. Total in kobo. |
currency | Required. NGN. |
beneficiary_label | Required, up to 80 characters. Shown to payers. Must not contain long numbers (account or patient numbers). |
purpose | Optional, up to 200 characters. Not allowed for hospital bills. |
funding_mode | full (one payer), fixed_share (equal shares) or open (anyone chips in). |
share_count | For fixed_share: 2–500. Any rounding goes on the last share. |
min_contribution_minor | For open. Smallest payment allowed, except when clearing what’s left. |
expires_at | Optional ISO time, up to 90 days ahead (default 7 days). If it isn’t fully paid by then, every payer is refunded. |
metadata | Optional 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
| Sector | Rules |
|---|---|
school_fees | None. |
hospital_bills | Payers see your neutral name (set it in Settings) and “Medical bill” instead of any purpose. |
utilities | Tracks delivery: tell us when the token or service was delivered. |
online_shopping | Tracks delivery. |
travel | Tracks delivery. expires_at is required. |
courses | Tracks 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.
| Event | When |
|---|---|
request.created | A request was created. |
contribution.succeeded | Someone paid. Includes contribution_amount_minor and paid_minor. |
request.funded | Fully paid. Deliver what was ordered. |
settlement.completed | The payout to your bank was sent. |
settlement.failed | The payout failed. We’ll contact you. |
request.expired / request.cancelled | Closed without being paid. Everyone is being refunded. |
refund.completed / refund.failed | A refund finished or failed. |
contribution.refunded_automatically | A 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": [ … ] } }| Status | Meaning |
|---|---|
| 401 | Missing or invalid key. |
| 409 | Conflict: for example request_already_active or request_not_open. |
| 422 | Invalid input. issues says which fields. |
| 503 | A 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 408Questions? Email hello@asqash.com.