Hosted Checkout - Dollr Developer Docs

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 checkout	API-embedded (Quick Start)
Who collects payment details	Dollr hosted page	Your app / website
Server calls after publish	Share `url` or payment link	Session → payment account → execute
Mobile money	Customer enters phone on hosted page	You register wallet via API
Cards	Customer enters card on hosted page	You integrate Stripe Elements + execute
Best for	Payment links, simple integrations	Custom 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:

Field	Description
`url`	Full hosted payment URL — redirect or link the customer here
`hosted_path_or_token`	Path or token for the hosted session (if building your own redirect)
`source_id`	Invoice or order ID for status queries
`source_number`	Human-readable document number
`success_url` / `cancel_url`	Redirect 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).

Path B — Invoice or order + payment link

For document-first flows where you control line items and publish timing:

Create and publish an invoice or order with as_payment_link: true
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:

Selects their mobile money operator (or Dollr infers it from phone)
Enters their wallet phone number
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:

Selects card as the payment method
Enters card details on Dollr’s secure card form (Stripe-powered)
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}

Receipt link

After payment, fetch a receipt URL for the customer:

GET /v1/links/receipt?source_type=INVOICE&source_number={invoice_number}

Monitor payment status

Approach	When to use
`GET /v1/status/source`	Check if invoice/order is `PAID` (simple backends)
Realtime keys	Live 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:

Customer completes payment on Dollr hosted page
Customer redirected to your success_url (optional UX)
Your server calls GET /v1/status/source?source_type=INVOICE&source_id={id}
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`

Field	Use
`url`	Preferred — full hosted payment URL. Redirect or link customers here.
`hosted_path_or_token`	Internal 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.

Collect via checkout — API shortcut without manual party setup
Payment links · Checkouts
Choose your integration
Quick Start — API-embedded collection

​Hosted vs API-embedded

​Path A — One-call checkout source

​Path B — Invoice or order + payment link

​Mobile money on hosted checkout

​Cards on hosted checkout

​Redirect URLs

​Receipt link

​Monitor payment status

​Fulfillment security

​url vs hosted_path_or_token

​Expiration

​Related

Hosted vs API-embedded

Path A — One-call checkout source

Path B — Invoice or order + payment link

Mobile money on hosted checkout

Cards on hosted checkout

Redirect URLs

Receipt link

Monitor payment status

Fulfillment security

`url` vs `hosted_path_or_token`

Expiration

Related