Server API
Payment links & transactions
Ask to be paid with a link, then see whether it was.
A payment link is a hosted page for one-time payments. Mercestack creates a Bachs checkout session and redirects the payer to Bachs; payment details stay on the hosted checkout, never in your app. Available payment methods depend on the settlement currency and the Bachs corridors enabled for the platform account. When the payment is confirmed, the link's status becomes paid and payment_link.paid fires.
- 01
Create a link
Use the server API or attach a link to an invoice, order or class fee.
- 02
Send the payer to checkout
The hosted payment page is served by Bachs. Keep your Mercestack reference for the return trip.
- 03
Wait for confirmation
Use the signed Mercestack webhook or read the transaction back; a browser redirect alone is not proof of payment.
Payment status is authoritative
Verify the transaction or process payment.transaction.succeeded before granting access or shipping an order.
Refunds depend on the rail
Bachs processes eligible refunds asynchronously. NGN bank-transfer collections do not support provider refunds; check the transaction's provider and status before offering one.
| Status | Means |
|---|---|
active | Not paid yet — or, for a reusable link, still taking payments |
paid | Paid. A single-use link takes no further payments |
inactive | Switched off |
expired | Past its expiresAt |
Create a payment link
/v1/payment-linksNeeds a fixed amount or an invoiceId. The currency is your workspace's.
Body
titlestringrequired- Shown to the payer.
amountstring- Major units:
"25000.00". descriptionstring- Shown under the title.
customerIduuid- Link it to a customer.
invoiceIduuid- Collect an invoice; stays open until it's settled.
expiresAtISO 8601- Stops accepting payment after this.
reusableboolean- Take any number of payments.
curl -X POST https://api.mercestack.com/v1/payment-links \
-H "Authorization: Bearer sk_test_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"title":"Deposit — order 1042","amount":"25000"}'{
"id": "4c0a…",
"title": "Deposit — order 1042",
"amount": "25000.00",
"amountMinor": "2500000",
"currency": "NGN",
"status": "active",
"paid": false,
"paidAt": null,
"reusable": false,
"url": "https://mercestack.com/pay/vJZKPXDrY8Ko65V8",
"customerId": null,
"invoiceId": null,
"expiresAt": null,
"createdAt": "2026-09-27T10:00:00.000Z"
}List payment links
/v1/payment-linksFilter by status to find what's still unpaid.
Query parameters
limitinteger- How many to return, 1–100. Defaults to 25.
cursorstringnextCursorfrom the previous page.statusstringactive,paid,inactive,expired.
curl https://api.mercestack.com/v1/payment-links?status=paid \
-H "Authorization: Bearer sk_test_…"{ "object": "list", "data": [ { "id": "4c0a…", "status": "paid", "paid": true, … } ], "hasMore": false, "nextCursor": null }Get a payment link
/v1/payment-links/:idCheck paid before you ship.
curl https://api.mercestack.com/v1/payment-links/LINK_ID \
-H "Authorization: Bearer sk_test_…"{ "id": "4c0a…", "status": "paid", "paid": true, "paidAt": "2026-09-27T11:20:00.000Z", … }Deactivate a payment link
/v1/payment-links/:id/deactivateStops it taking payments. A paid link stays paid.
curl -X POST https://api.mercestack.com/v1/payment-links/LINK_ID/deactivate \
-H "Authorization: Bearer sk_test_…"{ "id": "4c0a…", "status": "inactive", … }List transactions
/v1/transactionsEvery payment attempt: store orders, payment links, invoices and class fees.
Query parameters
limitinteger- How many to return, 1–100. Defaults to 25.
cursorstringnextCursorfrom the previous page.statusstringsuccess,failed,refunded…emailstring- The payer's email.
paymentLinkIduuid- Payments to one link.
curl https://api.mercestack.com/v1/transactions?status=success \
-H "Authorization: Bearer sk_test_…"{
"object": "list",
"data": [
{
"id": "a91c…",
"reference": "ms_8Kq2…",
"status": "success",
"amount": "25000.00",
"amountMinor": "2500000",
"fees": "375.00",
"currency": "NGN",
"channel": "card",
"customerEmail": "[email protected]",
"paymentLinkId": "4c0a…",
"invoiceId": null,
"orderId": null,
"paidAt": "2026-09-27T11:20:00.000Z",
"createdAt": "2026-09-27T11:19:02.000Z"
}
],
"hasMore": false,
"nextCursor": null
}Get a transaction
/v1/transactions/:idBy id, or by the payment reference printed on the customer's receipt.
curl https://api.mercestack.com/v1/transactions/ms_8Kq2 \
-H "Authorization: Bearer sk_test_…"{ "id": "a91c…", "reference": "ms_8Kq2…", "status": "success", … }