Skip to main content

Understand invoices

A finalized order includes an invoice—a hosted payment page where customers can review what they owe and complete payment. Draft orders omit invoice; set finalize: true during creation or call Finalize an order when the order is ready. This guide explains when to use the hosted invoice URL instead of building a custom checkout.

Use MCP to send and inspect order documents

An authenticated AI agent can send an invoice or receipt after confirmation, then look up the order to verify invoice state and delivery context.

MCP tools: send_order_invoice, send_order_receipt or get_order

Confirmed MCP actions require explicit form confirmation before Inttegro changes state.

Prerequisites

What is an invoice?

When you create an order with finalize: true, Inttegro includes two invoice URLs in the { "order": ... } response envelope:

Invoice URLs in order response

SDK versionv8.2.0
OrderResponse {
  order: { … },
}

The web URL is an interactive payment page. Send this to a customer to let them pay directly. The PDF URL generates a downloadable invoice document—useful for B2B customers who need a paper trail, accounting teams, or email attachments.

The URLs don't require an API key. Treat them as bearer capabilities and share them only with the intended customer.

Web invoice: the hosted payment page

When a customer opens the web invoice URL, they see:

  • Your merchant name and branding
  • A line-by-line breakdown of what they're being charged
  • The total amount and currency
  • A payment form appropriate to their region (mobile money, card, etc.)

Inttegro handles the entire payment flow on this page: collecting payment details, sending the OTP, waiting for confirmation, and showing a success or failure state. You don't write any frontend payment code.

This is the approach documented in Accept payment with Inttegro Checkout—create the order via API, then redirect or link the customer to the web invoice URL.

PDF invoice: the downloadable document

The PDF URL generates a formatted invoice document on demand—every request to it produces the current state of the invoice. This means:

  • Before payment: the PDF shows an outstanding balance with payment instructions
  • After payment: the PDF shows payment confirmation. Provide receipt_number on Create an order or Update an order when your accounting system needs a receipt reference in order API responses for reconciliation.

PDF invoices are useful when your customers are businesses that need documents for accounting, when you want to email an invoice attachment before requesting payment, or when you're integrating with an ERP that ingests invoice PDFs.

Invoice vs. custom checkout

The hosted invoice (Inttegro Checkout) handles the payment experience for you. You create the order, redirect the customer, and poll Lookup an order when your application needs the latest payment state. No frontend payment code required.

Building a custom checkout means you manage the UI yourself and call payment endpoints directly: /orders/pay, /orders/confirm_payment, and /orders/request_confirmation. This gives you complete control over the look and feel but requires you to implement the full payment flow, OTP collection UI, and error handling.

Choose Inttegro Checkout (hosted invoice) when:

  • Speed to market matters more than exact UI control
  • You want Inttegro to handle mobile money OTP flows
  • You're building a simple storefront or order management workflow
  • You don't have frontend engineers to build a custom checkout

Choose custom checkout when:

  • Your brand guidelines require a fully native experience
  • You're embedding payment into an existing mobile app or complex UI
  • You need fine-grained control over payment method selection and UX
  • You've already built a payment UI and want to wire it to Inttegro APIs

How the order and invoice stay in sync

The invoice reflects the live order state. If you update an order via /orders/update and reseal it, or seal it with /orders/finalize, the invoice immediately shows the updated total—the customer always sees current numbers, not a stale snapshot.

When payment completes, the invoice transitions from "pay now" to "payment confirmed" automatically. The same URL that showed the payment form now shows a receipt. You don't need to do anything—Inttegro handles the state machine.