Cancel an order, stopping payment execution and preventing further processing.
Canceling an order is irreversible and should be done when the customer requests cancellation or the order cannot be fulfilled. If payment was already captured, you'll need to refund it separately.
Cancellation parameters
Cancel order request
OptionalexecuteRefund?: booleanRecord whether a refund was requested as part of the cancellation
Order ID to cancel
Optionalreason?: stringOptional cancellation reason
OptionalrequestMeta?: RequestMetaRequest metadata such as idempotency controls
Cancelled order object
const order = await inttegro.orders.cancel({
orderId: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb',
});
console.log(`Order ${order.id} has been cancelled`);
https://studio.inttegro.com/order-lifecycle for order states
Mark an order as completed, indicating fulfillment is done.
Call this after you've shipped physical goods or delivered digital products to the customer.
Completing an order transitions it to its final state and can optionally mark payment as received
offline (out-of-band) if paidOutOfBand is set to true.
Completion parameters
Complete order request
Order ID to complete
OptionalpaidOutOfBand?: booleanWhether payment was collected out of band
Completed order object
// Complete order after fulfillment
const order = await inttegro.orders.complete({
orderId: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb',
});
console.log(`Order completed at: ${order.completedAt}`);
// Complete order with offline payment
const result = await inttegro.orders.complete({
orderId: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb',
paidOutOfBand: true,
});
https://studio.inttegro.com/order-lifecycle for order states
Confirm a pending payment using a verification token (e.g., OTP sent to customer's phone).
Call this method when a payment requires customer confirmation and you've collected the verification token from the customer. The token is typically a 6-digit OTP sent via SMS or email to the customer.
Confirmation parameters
Confirm payment request
Confirmation challenge being answered
Order ID
Payment being confirmed
OptionalrequestMeta?: RequestMetaRequest metadata such as idempotency controls
Confirmation token (e.g., OTP)
Updated order with payment status
// After receiving OTP from customer
const order = await inttegro.orders.confirmPayment({
orderId: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb',
paymentId: 'py_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN',
confirmationId: 'pc_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN',
token: '123456',
});
if (order.payment?.status === 'paid') {
console.log('Payment confirmed successfully!');
}
https://studio.inttegro.com/accept-a-payment for complete payment flow
Create a new order with line items, customer, and optional payment details.
Creates an order representing a purchase. Supports two flows:
customerData to create a new customer and ordercustomerId and optionally paymentMethodId for known customersSet executePayment to true to immediately charge the customer after order creation. The order can
be configured with checkout redirect URLs for hosted payment flows.
Order creation parameters
Created order with customer, line items, payment intent (if applicable), and optional redirect URL
// Create order with new customer and execute payment
const order = await inttegro.orders.create({
requestMeta: {
idempotencyKey: 'order_2025_001',
},
executePayment: true,
customerData: {
name: 'Gloria Kesewaa',
emailAddress: 'gloria@example.com',
phoneNumber: '+233544998605',
},
paymentMethodData: {
type: 'mobile_money',
mobileMoney: {
network: 'mtn',
accountNumber: '0544998605',
},
},
lineItems: [{
type: 'product',
product: {
type: 'physical',
name: 'Utility Sneakers',
quantity: 1,
price: { currency: 'ghs', value: 20000 },
},
}],
checkoutSettings: {
redirectUrl: 'https://example.com/order/complete',
cancelUrl: 'https://example.com/order/cancelled',
},
});
console.log(`Created order: ${order.id}`);
// Create order with existing customer for later payment
const order = await inttegro.orders.create({
customerId: 'cu_abc123',
lineItems: [{
type: 'product',
product: {
type: 'digital',
name: 'Premium Subscription',
quantity: 1,
price: { currency: 'ghs', value: 5000 },
},
}],
});
Finalize an order to make it immutable and ready for payment or fulfillment.
Finalizing (sealing) an order locks its line items and totals, making it ready for payment execution or order completion. Most orders are finalized automatically, but you can explicitly finalize an order if needed.
Finalization parameters
Finalize order request
Order ID to finalize
OptionalrequestMeta?: RequestMetaRequest metadata such as idempotency controls
Finalized order object
const order = await inttegro.orders.finalize({
orderId: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb',
});
console.log(`Order finalized at: ${order.sealedAt}`);
https://studio.inttegro.com/order-lifecycle for order states
Retrieve an existing order by its ID.
Returns full order details including customer, line items, payment state, and invoice information. Use this to check order status, retrieve payment details, or display order confirmation to customers.
Lookup parameters
Lookup order request
Order ID to lookup
Complete order object with all related data
const order = await inttegro.orders.lookup({
orderId: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb',
});
console.log(`Order status: ${order.status}`);
console.log(`Payment status: ${order.payment?.status}`);
https://studio.inttegro.com/orders for API reference
Create a new order through the legacy compatibility route.
Prefer create, which uses the canonical /orders/create endpoint.
Retrieve a paginated list of orders.
Returns orders in reverse chronological order (most recent first).
Pagination and filter parameters (optional)
Page orders request
OptionalcustomerId?: stringOptionalpageNumber?: numberOptionalpageSize?: numberPaginated list of orders with pagination details
// Get first page of orders
const page = await inttegro.orders.page({
pageSize: 25,
pageNumber: 0,
});
console.log(`Retrieved ${page.orders?.length ?? 0} orders`);
// Restrict the page to one customer
const customerOrders = await inttegro.orders.page({
customerId: 'cu_123',
pageSize: 50,
});
Initiate payment for an existing order.
Supports three payment flows:
orderId to charge a previously saved payment methodpaymentMethodData with inline payment details (mobile money, card, etc.)paidOutOfBand to true for cash, bank transfer, or check paymentsWhen payment requires customer confirmation (e.g., OTP), the returned order includes a nextAction field
indicating what the customer needs to do. Call confirmPayment() once the customer provides the token.
Payment parameters
Updated order with typed payment and next-action state
// Pay with inline mobile money
const order = await inttegro.orders.pay({
orderId: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb',
paymentMethodData: {
type: 'mobile_money',
mobileMoney: {
network: 'mtn',
accountNumber: '0544998605',
},
},
});
if (order.payment?.nextAction?.type === 'confirm_payment') {
// Customer needs to provide OTP sent to their phone
const token = await promptCustomerForOTP();
await inttegro.orders.confirmPayment({
orderId: order.id,
paymentId: order.payment.id,
confirmationId: order.payment.nextAction.confirmPayment.request.id,
token,
});
}
// Pay with saved payment method
const order = await inttegro.orders.pay({
orderId: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb',
paymentMethodId: 'pm_xyz123abc456',
requestMeta: {
idempotencyKey: 'order_initial_charge_001',
},
});
// Mark as paid offline (cash, bank transfer, etc.)
const order = await inttegro.orders.pay({
orderId: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb',
paidOutOfBand: true,
});
Create a refund through the /orders/refund compatibility alias.
This accepts the same line-item request as refunds.create and returns the created
Refund directly. New integrations should prefer refunds.create.
Refund parameters
OptionalcustomData?: Record<string, string>OptionalreasonDetails?: stringOptionalreference?: stringOptionalrequestMeta?: RequestMetaOptional transport controls, including an explicit idempotency key
The created refund
const refund = await inttegro.orders.refund({
orderId: 'or_0123456789abcdefghijklmnopqrstuvwxyzABCD',
reason: 'requested_by_customer',
lineItems: [{
orderLineItemId: 'oli_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN',
refundAmount: { currency: 'ghs', value: 2500 },
}],
});
console.log(`Refund created: ${refund.id}`);
Request a new confirmation token to be sent to the customer (e.g., resend OTP).
Use this when the customer didn't receive the original OTP or the token expired. A fresh verification token will be sent via SMS or email to the customer's registered contact information.
Request parameters
Request confirmation request
Order ID
OptionalrequestMeta?: RequestMetaRequest metadata such as idempotency controls
Updated order
// Resend OTP to customer
const order = await inttegro.orders.requestConfirmation({
orderId: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb',
});
console.log('New OTP sent to customer');
https://studio.inttegro.com/accept-a-payment for payment confirmation flow
Send the hosted invoice link for an existing order to the customer.
Inttegro delivers the invoice link to every contact method available on the order customer.
Send invoice parameters
Send order document request
The order and document delivery details
Send the hosted receipt link for a paid order to the customer.
Inttegro delivers receipts only after the order has been paid.
Send receipt parameters
Send order document request
The order and document delivery details
Update mutable order metadata, line items, invoice settings, or attached payment method.
Orders resource for managing complete order lifecycle operations.