Skip to main content
Hosted checkout sends your customer to a Dollr payment page where they complete payment with mobile money or card — no Dollr account required. Dollr handles method selection, wallet prompts, and card authentication on the hosted UI. Use this when you want the fastest path to accepting payments without building your own payment form or calling executions/collection from your server.
API Reference: Create checkout source · Payment link

​
Hosted vs API-embedded

Hosted checkoutAPI-embedded (Quick Start)
Who collects payment detailsDollr hosted pageYour app / website
Server calls after publishShare url or payment linkSession → payment account → execute
Mobile moneyCustomer enters phone on hosted pageYou register wallet via API
CardsCustomer enters card on hosted pageYou integrate Stripe Elements + execute
Best forPayment links, simple integrationsCustom checkout UX, in-app flows

​
Path A — One-call checkout source

Create everything in a single request with mode: "HOSTED": 
POST /v1/checkouts/create

curl -X POST "https://api.heydollr.app/v1/checkouts/create" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "HOSTED",
    "source_kind": "INVOICE",
    "party_name": "Amara Kamara",
    "party_phone": "231771234567",
    "party_email": "amara@example.com",
    "currency": "USD",
    "items": [
      { "name": "Consulting", "currency": "USD", "amount": 250 }
    ],
    "success_url": "https://yourstore.com/checkout/success",
    "cancel_url": "https://yourstore.com/checkout/cancel"
  }'
Response fields you need:
FieldDescription
urlFull hosted payment URL — redirect or link the customer here
hosted_path_or_tokenPath or token for the hosted session (if building your own redirect)
source_idInvoice or order ID for status queries
source_numberHuman-readable document number
success_url / cancel_urlRedirect targets after payment or cancellation
Redirect the customer to url. They choose mobile money or card on the hosted page and complete payment there.
Request body uses source_kind; status and link APIs use source_type for the same concept (INVOICE or ORDER).
For document-first flows where you control line items and publish timing:
  1. Create and publish an invoice or order with as_payment_link: true
  2. Fetch the hosted URL:
GET /v1/links/pay?source_type=INVOICE&source_number={invoice_number}

curl "https://api.heydollr.app/v1/links/pay?source_type=INVOICE&source_number=INV-2025-0042" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response: { "url": "https://..." } — share or redirect to this URL.

​
Mobile money on hosted checkout

On the hosted page, the customer:
  1. Selects their mobile money operator (or Dollr infers it from phone)
  2. Enters their wallet phone number
  3. Approves the USSD / in-app prompt from their carrier
You do not need to call predictions/mmo-provider-info, payment-accounts/create, or executions/collection for hosted flows.
For API-embedded MoMo collection (your own UI), see Quick Start and Predictions.

​
Cards on hosted checkout

On the hosted page, the customer:
  1. Selects card as the payment method
  2. Enters card details on Dollr’s secure card form (Stripe-powered)
  3. Completes 3D Secure if required
You do not need Stripe Elements, client_secret, or server-side card execution for hosted flows.
For API-embedded card collection (Stripe Elements in your app), see Collect with card.

​
Redirect URLs

Set success_url and cancel_url when creating a hosted checkout source:
  • success_url — customer lands here after a successful payment
  • cancel_url — customer lands here if they abandon checkout
Query your backend or call GET /v1/status/source to confirm payment before fulfilling the order: 
GET /v1/status/source?source_type=INVOICE&source_id={source_id}
After payment, fetch a receipt URL for the customer: 
GET /v1/links/receipt?source_type=INVOICE&source_number={invoice_number}

​
Monitor payment status

ApproachWhen to use
GET /v1/status/sourceCheck if invoice/order is PAID (simple backends)
Realtime keysLive UI updates on your success page
GET /v1/invoices/receipt/{id}Full receipt with fees and line items

​
Fulfillment security

Never fulfill an order when the customer hits success_url alone. They may close the tab before payment completes, or navigate to success URL manually.
Correct pattern:
  1. Customer completes payment on Dollr hosted page
  2. Customer redirected to your success_url (optional UX)
  3. Your server calls GET /v1/status/source?source_type=INVOICE&source_id={id}
  4. Fulfill only when status === "PAID"
// app/api/orders/confirm/route.ts
export async function POST(req: Request) {
  const { sourceId, sourceType } = await req.json();
  const status = await fetch(
    `https://api.heydollr.app/v1/status/source?source_type=${sourceType}&source_id=${sourceId}`,
    { headers: { Authorization: `Bearer ${token}` } }
  ).then((r) => r.json());

  if (status.status !== "PAID") {
    return Response.json({ ready: false, status: status.status });
  }
  // Safe to fulfill — mark order complete in your DB
  return Response.json({ ready: true });
}
Run a background reconciliation job for orders stuck in pending — see Payment status patterns.

​
url vs hosted_path_or_token

FieldUse
urlPreferred — full hosted payment URL. Redirect or link customers here.
hosted_path_or_tokenInternal path or token for Dollr-hosted infrastructure. Use url unless Dollr support directs you otherwise.

​
Expiration

Hosted checkout sources may include expires_at. After expiry, generate a new checkout source or re-fetch the payment link if the source is still ACTIVE.
Last modified on June 23, 2026