# Payment links, checkout and POS

Hosted payment links, the JavaScript checkout embed, Payment IDs and the Web POS: which to use and how to confirm payment safely.

## Three ways to take a payment without building a prompt screen

Mobile Money Collection gives you full control: you build the screen, the OTP step and the status page. When you would rather not build that, Moolre can host it for you. Pick the option that matches how your customer arrives.

| Option | Best for | You build | Result |
| --- | --- | --- | --- |
| Payment link (hosted page) | Online stores, invoices you send by message, one-off requests | One server call and a redirect | The customer pays on a Moolre-hosted page (Web POS) and returns to your site |
| Checkout embed (JavaScript inline) | A checkout inside your own page | A script tag or the @moolre/moolrejs package, plus a server call to confirm | A Moolre checkout opens over your page |
| Payment ID | Customers who pay later by USSD, or pay in person | One server call per customer or per order | A short ID the customer pays to from their phone |
| Web POS | Staff taking payments at a till, from the dashboard | Nothing: staff use the Moolre Web POS | Payments settle into your wallet |

## Step by step: a payment link



1. Create the order in your database with a unique externalref and status pending.
2. Call Generate Payment Link with your public key: type 1, amount, the business email, externalref, currency, accountnumber and reusable ("0" for a one-time link). Add expiration_time (minutes), a redirect URL for after payment, a callback URL and metadata if you need them.
3. Read the reply. POS09 means the link was created. Store data.reference and send the customer to data.authorization_url.
4. The customer pays on the hosted page with their mobile money.
5. Wait for the payment webhook (payment.succeeded) or check Payment Status with idtype 1 and your externalref. Do not trust the redirect alone: a customer can open your redirect URL without paying.
6. Mark the order paid and fulfil it once. If the link expires unpaid you receive payment_link.expired.

```curl
curl https://api.moolre.com/embed/link \
  -H "Content-Type: application/json" \
  -H "X-API-USER: $MOOLRE_USER" \
  -H "X-API-PUBKEY: $MOOLRE_PUBKEY" \
  -d '{
    "type": 1,
    "amount": "120.00",
    "email": "shop@example.com",
    "externalref": "ORDER-1001",
    "currency": "GHS",
    "accountnumber": "1000000000001",
    "reusable": "0",
    "expiration_time": 60,
    "redirect": "https://shop.example.com/thanks?ref=ORDER-1001",
    "callback": "https://shop.example.com/moolre/webhook",
    "metadata": {
      "orderId": "1001"
    }
  }'
```

```json
{
  "status": 1,
  "code": "POS09",
  "message": "POS payment link successfully generated.",
  "data": {
    "authorization_url": "https://pos.moolre.com/RZWs1yB6amGjNoiEQvlHPS5uqgp3Jc",
    "reference": "uuid-1234as2"
  },
  "go": null,
  "meta": {
    "requestid": "req_c68f4c66115c26725c796242",
    "notices": []
  }
}
```

- [Generate Payment Link (API reference)](https://docs.moolre.com/api/payments/links)

## Payment link rules and errors



| Topic | Rule |
| --- | --- |
| externalref | Unique per link. A duplicate returns INP02 (Transaction already exists) |
| reusable | "0" = the link works for one payment, "1" = it can take repeat payments |
| expiration_time | Minutes, minimum 1. An unpaid link then expires and sends payment_link.expired |
| redirect | Where the customer returns after paying. Never use it as proof of payment |
| callback | A callback URL for this link; the wallet callback is used otherwise |
| metadata | Your own data, returned in callbacks |
| Sandbox | Links created in the sandbox open the sandbox Web POS and cannot collect real money |

## Step by step: the checkout embed

The JavaScript inline checkout opens a Moolre payment window on top of your page, so the customer never leaves your site.

1. Create the order on your server with a unique externalref.
2. On the page, load the checkout with the @moolre/moolrejs package or the browser CDN script, passing your public key, the amount, the currency and the externalref. Only the public key goes to the browser.
3. The customer completes the payment in the window.
4. On your server, confirm the payment with Payment Status (never trust the browser callback alone) or wait for the webhook, then fulfil the order once.

> **Public key only in the browser:** The public key can start collections but cannot move money out. The private key, VAS keys and your wallet secret must never reach a browser.

- [JavaScript inline plugin](https://docs.moolre.com/plugins/javascript-inline)

## Step by step: a Payment ID

A Payment ID lets a customer pay later or in person by USSD, without a screen of yours.

1. Call Create Payment ID with your public key: type 2, the customer phone (+233 format), name, currency, an optional amount, a unique externalref and your accountnumber.
2. Give the customer the returned ID. They dial *203*<paymentid># (in the sandbox *203*6000*<paymentid>#) and pay to it.
3. Read the payments made against it with List Payment ID Transactions, or receive the payment webhook.
4. Check the state of the ID itself with Payment ID / Bank Account Status.

- [Create Payment ID](https://docs.moolre.com/api/payments/payment-id)
- [List Payment ID Transactions](https://docs.moolre.com/api/payments/payment-id/transactions)

## Web POS for staff

The Web POS is the Moolre page staff use to take a payment at a till: enter the amount, the customer approves on their phone, and the money settles into your wallet. It needs no code. Payment links open the same Web POS, so a staff member and an online customer both end up in the same reconciled wallet.

1. Open the Web POS from the Moolre app with the wallet you want to collect into.
2. Enter the amount and the customer's phone number and send the request.
3. Confirm in the app, or on your statement, that the payment arrived before handing over goods.

## Checklist



- [ ] Every link or checkout has a unique externalref stored before it is created.
- [ ] You fulfil from a verified webhook or from Payment Status, never from a redirect or a browser callback.
- [ ] Only the public key is ever in a browser.
- [ ] Expired and unpaid links leave the order pending, then cancelled by your own rules.
- [ ] You reconcile paid orders against the account statement.

- [E-commerce checkout (playbook)](https://docs.moolre.com/use-cases/e-commerce-checkout)
- [Collect payments, step by step](https://docs.moolre.com/guides/collect-payments)
