Skip to main content
View as Markdown

Accept payment with Inttegro Checkout

Present Inttegro-hosted Checkout from the payment reference your application already owns. Inttegro handles amount selection when applicable, payment, confirmation, and receipt generation.

Choose the Checkout reference

What your application hasWhat to pass to CheckoutWhat not to do
An existing fixed-price or customer-selected Purchase IntentPass its sale_... ID to createCheckout({ purchaseIntentId }).Do not create an Order first. For customer-selected pricing, do not collect the amount yourself.
An application-approved purchase with known customer and line itemsCreate and finalize the Order on your server, then pass its or_... ID to createCheckout({ orderId }).Do not expose the API key or let the browser change commercial details.

For an existing Purchase Intent, the complete browser handoff is deliberately small:

import { loadInttegro } from '@inttegro/js'

const inttegro = await loadInttegro()
if (!inttegro) throw new Error('Checkout requires a browser.')

const checkout = inttegro.createCheckout({ purchaseIntentId })
await checkout.present()

See the JavaScript Checkout guide for embedded presentation, framework adapters, lifecycle events, and server-side reconciliation. The remaining steps on this page cover the new-Order path.

Use MCP for Order-based Checkout

When your application needs a new Order, an authenticated AI agent can create it, send its invoice link after confirmation, and keep checking its state. If you already have a Purchase Intent, pass it directly to the web SDK instead.

MCP tools: create_order, send_order_invoice, get_order or render_order_card

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

Note

Recommended approach. See Inttegro Checkout for why this works better than custom checkout.

Step 1: create an order

Call /orders/create with customer details and line items, and set finalize to true. Finalization seals the order and generates its hosted invoice URLs. Store the order ID for status tracking.

Send a unique, stable Idempotency-Key header for each order-creation attempt. If a request times out or its result is unclear, retry the same request with the same key so it does not create a second order. Use a new key when the request payload changes. requestMeta.idempotencyKey remains accepted for compatibility, but new integrations should use the header.

Create order

POST/orders/create
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.orders.create({
  requestMeta: {
    idempotencyKey: "order_inv_001",
  },
  customerData: {
    name: "Gloria Kesewaa",
    emailAddress: "[email protected]",
    phoneNumber: "+233544998605",
  },
  finalize: true,
  lineItems: [
    {
      type: Inttegro.LineItemTypes.Product,
      product: {
        type: Inttegro.ProductTypes.Physical,
        name: "Utility Sneakers",
        quantity: 1,
        price: {
          currency: "ghs",
          value: 20000,
        },
      },
    },
  ],
})

Response​

Note

Partial response. See complete Order object.

Response excerpt

SDK versionv12.0.0
OrderResponse {
  order: { … },
}

Step 2: direct customer to payment

Choose how to get the customer to the payment page:

Read the web invoice URL from the created order and return it to your client. Check that the invoice is present before redirecting; draft orders do not have one. Your client can then open the returned URL using its normal navigation mechanism.

Step 3: track payment status

Use /orders/lookup to check payment status. Poll periodically or check when the customer returns to your app. When status becomes Inttegro.OrderStatuses.Paid, funds are in your Inttegro balance.

Check status

POST/orders/lookup
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.orders.lookup({
  orderId: "or_XyZ9kL2mQrTfVqYz1wNb",
})

Customization

Configure redirect and cancel URLs​

{
  checkoutSettings: {
    redirectUrl: "https://yoursite.com/order/complete",
    cancelUrl: "https://yoursite.com/order/cancelled",
  },
}

Strongly recommended for a delightful customer experience. When payment completes, customers land on your checkoutSettings.redirectUrl where you can show order confirmation and next steps. When customers abandon checkout without paying, they land on your checkoutSettings.cancelUrl where you can show incomplete order details or offer alternative payment methods.

Add line item details​

{
  lineItems: [
    {
      product: {
        name: "Utility Sneakers",
        about: "Size: 42 | Color: Black",
      },
    },
  ],
}

Appears below product name on invoice.

Update branding​

Change logo, business name, and colors in the Inttegro dashboard under Settings → Branding. Applies to all new invoices instantly.

See Checkout customization for more options.

Common patterns

Subscriptions: Create new order each cycle, send new invoice URL.

Deposits: Create separate orders for deposit and balance. Link them with a shared value in customData.

Multi-currency: Create one order per currency.

Order limits: Each order can contain up to 64 line items. Order totals are capped at 100,000 for "ghs" and 50,000 for all other supported currencies, measured in the currency's smallest unit. Contact support if you need these limits increased.

See Common patterns for implementation details.

Next steps