API reference

Payments (intents)

Create, fetch and cancel payments.

A payment (intent) is an amount you expect to receive for one of your references. Create one per order, show the customer the instructions (or send them to checkoutUrl), and wait for the payment.verified webhook.

Create a payment#

POST/v1/intentsAPI key

Parameters

referencestringrequired

Your order / invoice ID (1–100 chars). Creating the same purpose + reference again returns the existing payment (idempotent).

amountPesewasintegerrequired

Amount due in pesewas (1 – 100,000,000).

purposestringoptional

Your category, letters/digits/_.-, default payment. References are unique per purpose.

amountPolicystringoptional

AT_LEAST (default), EXACT or ANY — see amount policies.

descriptionstringoptional

Shown on the checkout page (≤ 300 chars).

customerobjectoptional

{ ref?, name? } — your customer ID and display name.

metadataobjectoptional

Any JSON you want back in webhooks.

expiresInMinutesintegeroptional

Reference auto-match window for this payment (5 – 10,080). Default from Settings → Matching.

returnUrlURLoptional

Hosted checkout sends the customer here after a verified payment (with a short countdown), e.g. https://shop.com/orders/1001.

curl https://pay.yourshop.com/v1/intents \
  -H "Authorization: Bearer $LOKIPAY_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "reference": "ORDER-1001",
    "amountPesewas": 15000,
    "description": "Order #1001",
    "customer": { "ref": "cus_42", "name": "Ama" },
    "metadata": { "cart": "c_93" }
  }'

The payment object

json

{
  "id": "cmvymj4a1000621twmsz5y6i5",
  "shortRef": "Q9N2LPU7",
  "purpose": "payment",
  "reference": "ORDER-1001",
  "description": "Order #1001",
  "customerRef": "cus_42",
  "customerLabel": "Ama",
  "metadata": { "cart": "c_93" },
  "paymentLinkId": null,
  "returnUrl": "https://shop.example.com/orders/ORDER-1001",
  "status": "VERIFIED",
  "amountPolicy": "AT_LEAST",
  "expectedAmountPesewas": 15000,
  "receivedAmountPesewas": 15000,
  "claimedTransactionId": "92481234567",
  "claimedReference": null,
  "reviewReason": null,
  "createdAt": "2026-11-02T10:00:00.000Z",
  "expiresAt": "2026-11-02T11:00:00.000Z",
  "claimDeadline": "2026-11-05T10:00:00.000Z",
  "verifiedAt": "2026-11-02T10:01:12.000Z",
  "checkoutUrl": "https://pay.yourshop.com/checkout/cmvymj4a1000621twmsz5y6i5",
  "payTo": { "network": "MTN", "accountName": "Loki Store", "accountNumber": "0241234567", "instructions": "…" },
  "transaction": {
    "transactionId": "92481234567",
    "provider": "MTN",
    "amountPesewas": 15000,
    "payerName": "AMA SERWAA",
    "payerPhone": "0241112233",
    "reference": "Q9N2LPU7",
    "receivedAt": "2026-11-02T10:01:10.000Z"
  }
}

transaction is null until a MoMo SMS is linked. reviewReason is set while status is REVIEW.

Retrieve a payment#

GET/v1/intents/:idAPI key

GET/v1/intents/by-reference/:reference?purpose=paymentAPI key

Use the second form to look a payment up by your own reference (for example when the webhook was missed).

Cancel a payment#

POST/v1/intents/:id/cancelAPI key

Only PENDING or EXPIRED payments can be cancelled. Cancelling twice is safe. A cancelled payment can no longer be verified.

Polling

Webhooks are the recommended way to learn about status changes. If you poll, poll GET /v1/intents/:id no more than every few seconds while the customer is on your page.

Errors

Claims