Inttegro PHP SDK

Orders
in package

Orders resource for creating orders, processing payments, and managing order lifecycle.

Orders are the central transaction object in Inttegro. They represent a purchase with line items, customer information, and payment details. Use this resource to create orders, charge customers, handle confirmations, and process refunds.

Tags
see
https://studio.inttegro.com/orders

for detailed guides

Table of Contents

Methods

__construct()  : mixed
cancel()  : Order
Cancel an order, stopping payment execution and preventing further processing.
complete()  : Order
Mark an order as completed, indicating fulfillment is done.
confirmPayment()  : Order
Confirm a pending payment using a verification token (e.g., OTP sent to customer's phone).
create()  : Order
Create a new order with line items, customer, and payment details.
createLegacy()  : Order
Compatibility route for POST /orders/new. Prefer create() for the canonical /orders/create endpoint.
finalize()  : Order
Finalize an order to make it immutable and ready for payment or fulfillment.
lookup()  : Order
Retrieve an existing order by its ID.
page()  : OrderPage
Retrieve a paginated list of orders.
pay()  : Order
Initiate payment for an existing order.
refund()  : Refund
Create a refund through the `/orders/refund` compatibility alias.
requestConfirmation()  : Order
Request a new confirmation token to be sent to the customer (e.g., resend OTP).
sendInvoice()  : OrderDocumentDeliveryResult
Send the hosted invoice link for an existing order.
sendReceipt()  : OrderDocumentDeliveryResult
Send the hosted receipt link for a paid order.
update()  : Order
Update mutable fields on an existing order (POST /orders/update).

Methods

cancel()

Cancel an order, stopping payment execution and preventing further processing.

public cancel(string $orderId[, array<string|int, mixed> $requestMeta = [] ]) : Order

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.

Parameters
$orderId : string

Unique identifier of the order to cancel (required)

$requestMeta : array<string|int, mixed> = []

Request controls such as idempotency_key (optional)

Tags
example

Cancel an order

$order = $client->orders->cancel(
    'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb'
);

echo "Order {$order->id} has been cancelled\n";
see
https://studio.inttegro.com/order-lifecycle

for order states

Return values
Order —

The cancelled order

complete()

Mark an order as completed, indicating fulfillment is done.

public complete(array<string|int, mixed> $payload) : Order

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 paid_out_of_band is set to true.

Parameters
$payload : array<string|int, mixed>

Completion parameters

  • order_id: string - Unique identifier of the order to complete (required)
  • paid_out_of_band: bool - Set to true if payment received outside Inttegro (default: false)
Tags
example

Complete order after fulfillment

$order = $client->orders->complete([
    'order_id' => 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb'
]);

echo "Order completed at: {$order->completedAt}\n";
see
https://studio.inttegro.com/order-lifecycle

for order states

Return values
Order —

The completed order

confirmPayment()

Confirm a pending payment using a verification token (e.g., OTP sent to customer's phone).

public confirmPayment(array<string|int, mixed> $payload) : Order

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.

Parameters
$payload : array<string|int, mixed>

Confirmation parameters

  • order_id: string - Unique identifier of the order being paid (required)
  • token: string - Verification token provided by customer (required, typically 6 digits)
Tags
example

Confirm payment with OTP

$order = $client->orders->confirmPayment([
    'order_id' => 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb',
    'token' => '123456'
]);

if ($order->payment?->status === 'succeeded') {
    echo "Payment confirmed successfully!\n";
}
see
https://studio.inttegro.com/accept-a-payment

for complete payment flow

Return values
Order —

The updated order

create()

Create a new order with line items, customer, and payment details.

public create(array<string|int, mixed> $payload) : Order

Creates an order representing a purchase. You can create an order for a new or existing customer, include multiple line items, and optionally execute payment immediately. Orders must have at least one line item and billing details.

Parameters
$payload : array<string|int, mixed>

Order creation parameters

  • customer_data: array - New customer information (required if customer_id not provided)
  • customer_id: string - Existing customer ID (required if customer_data not provided)
  • line_items: array - List of products/services being purchased (required)
  • billing_details: array - Billing contact information (required)
  • payment_method_id: string - ID of saved payment method to use
  • payment_method_data: array - Inline payment method details
  • execute_payment: bool - Whether to immediately charge (default: false)
  • checkout_settings: array - Checkout flow configuration with redirect_url and cancel_url
  • payout_settings: array - Order-specific payout destination configuration
  • custom_data: array - Key-value custom data (max 25KB, keys and values must be strings)
  • request_meta: array - Request controls such as idempotency_key
  • number: string - Optional order number for reference
  • statement_descriptor: string - Text on customer's bank statement (max 22 characters)
  • statement_descriptor_prefix: string - Static prefix, 2-10 characters, used to build prefix*order_id; mutually exclusive with statement_descriptor
  • finalize: bool - Whether to explicitly finalize order (default: false)
Tags
example

Create order with new customer and execute payment

$order = $client->orders->create([
    'request_meta' => [
        'idempotency_key' => 'order_2025_001',
    ],
    'execute_payment' => true,
    'customer_data' => [
        'name' => 'Akua Asantewaa',
        'email_address' => 'akua@example.com',
        'phone_number' => '+233541234567'
    ],
    'payment_method_data' => [
        'type' => 'mobile_money',
        'mobile_money' => [
            'network' => 'mtn',
            'account_number' => '0541234567'
        ]
    ],
    'line_items' => [[
        'type' => 'product',
        'product' => [
            'type' => 'digital',
            'name' => 'Premium Subscription',
            'quantity' => 1,
            'price' => ['currency' => 'ghs', 'value' => 5000]
        ]
    ]],
    'billing_details' => [
        'name' => 'Akua Asantewaa',
        'phone_number' => '+233541234567'
    ],
    'checkout_settings' => [
        'redirect_url' => 'https://example.com/order/complete',
        'cancel_url' => 'https://example.com/order/cancelled'
    ]
]);

echo "Created order: {$order->id}\n";
see
https://studio.inttegro.com/accept-a-payment

for payment flow guide

https://studio.inttegro.com/order-lifecycle

for order states

Return values
Order —

The created order

createLegacy()

Compatibility route for POST /orders/new. Prefer create() for the canonical /orders/create endpoint.

public createLegacy(array<string|int, mixed> $payload) : Order
Parameters
$payload : array<string|int, mixed>
Return values
Order

finalize()

Finalize an order to make it immutable and ready for payment or fulfillment.

public finalize(string $orderId[, array<string|int, mixed> $requestMeta = [] ]) : Order

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 if needed.

Parameters
$orderId : string

Unique identifier of the order to finalize (required)

$requestMeta : array<string|int, mixed> = []

Request controls such as idempotency_key (optional)

Tags
example

Finalize an order

$order = $client->orders->finalize(
    'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb'
);

echo "Order finalized at: {$order->sealedAt}\n";
see
https://studio.inttegro.com/order-lifecycle

for order states

Return values
Order —

The finalized order

lookup()

Retrieve an existing order by its ID.

public lookup(string $orderId[, array<string|int, mixed> $options = [] ]) : Order

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.

Parameters
$orderId : string

Unique identifier of the order to retrieve (required)

$options : array<string|int, mixed> = []

Additional options (currently unused)

Tags
example

Lookup an order

$order = $client->orders->lookup(
    'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb'
);

echo "Order status: {$order->status}\n";
if ($order->payment !== null) {
    echo "Payment status: {$order->payment->status}\n";
}
see
https://studio.inttegro.com/orders

for API reference

Return values
Order —

The complete order

page()

Retrieve a paginated list of orders.

public page([array<string|int, mixed> $payload = [] ]) : OrderPage

Returns orders in reverse chronological order (most recent first).

Parameters
$payload : array<string|int, mixed> = []

Pagination and filter parameters (optional)

  • page_number: int - Zero-based page index to retrieve (0-10)
  • page_size: int - Number of orders per page (1-256)
  • customer_id: string - Optional customer whose orders should be returned
Tags
example

Get first page of orders

$page = $client->orders->page([
    'page_size' => 25,
    'page_number' => 0
]);

echo "Retrieved " . count($page->orders) . " orders\n";
echo "Page number: {$page->number}\n";
see
https://studio.inttegro.com/pagination

for pagination guide

https://studio.inttegro.com/orders

for API reference

Return values
OrderPage —

Paginated orders and pagination details

pay()

Initiate payment for an existing order.

public pay(array<string|int, mixed> $payload) : Order

Supports three payment flows:

  1. Saved payment method: Provide only order_id to charge a previously saved payment method
  2. New payment method: Include payment_method_data with inline payment details
  3. Offline payment: Set paid_out_of_band to true for cash, bank transfer, or check payments

When payment requires customer confirmation (e.g., OTP), the returned order includes a nextAction field.

Parameters
$payload : array<string|int, mixed>

Payment parameters

  • order_id: string - Unique identifier of the order to pay (required)
  • payment_method_data: array - Inline payment method details (mobile money, card, etc.)
  • payment_method_id: string - ID of a saved payment method to use
  • paid_out_of_band: bool - Set to true if payment received outside Inttegro (default: false)
Tags
example

Pay with inline mobile money

$order = $client->orders->pay([
    'order_id' => 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb',
    'payment_method_data' => [
        'type' => 'mobile_money',
        'mobile_money' => [
            'network' => 'mtn',
            'account_number' => '0544998605'
        ]
    ]
]);

if ($order->payment?->nextAction?->type === 'confirm_payment') {
    echo "Customer needs to provide OTP sent to their phone\n";
}

Pay with saved payment method

$order = $client->orders->pay([
    'order_id' => 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb',
    'payment_method_id' => 'pm_xyz123abc456'
]);
see
https://studio.inttegro.com/accept-a-payment

for payment flow guide

https://studio.inttegro.com/charge-repeat-customers

for saved payment methods

Return values
Order —

The updated order and payment state

refund()

Create a refund through the `/orders/refund` compatibility alias.

public refund(array<string|int, mixed> $payload[, string|null $idempotencyKey = null ]) : Refund

This accepts the same line-item payload as $client->refunds->create() and returns the created Refund directly. New integrations should use the canonical method.

Parameters
$payload : array<string|int, mixed>

Create-refund payload containing order_id, reason, and line_items

$idempotencyKey : string|null = null

Optional key for safely retrying the request

Tags
example

Refund an order

$refund = $client->orders->refund([
    'order_id' => 'or_0123456789abcdefghijklmnopqrstuvwxyzABCD',
    'reason' => 'requested_by_customer',
    'line_items' => [[
        'order_line_item_id' => 'oli_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN',
        'refund_amount' => ['currency' => 'ghs', 'value' => 2500],
    ]],
]);

echo "Refund created: {$refund->id}\n";
Return values
Refund —

The created refund

requestConfirmation()

Request a new confirmation token to be sent to the customer (e.g., resend OTP).

public requestConfirmation(string $orderId[, array<string|int, mixed> $requestMeta = [] ]) : Order

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.

Parameters
$orderId : string

Unique identifier of the order requiring confirmation (required)

$requestMeta : array<string|int, mixed> = []

Request controls such as idempotency_key (optional)

Tags
example

Resend OTP to customer

$order = $client->orders->requestConfirmation(
    'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb'
);

echo "New OTP sent to customer\n";
see
https://studio.inttegro.com/accept-a-payment

for payment confirmation flow

Return values
Order —

The updated order

sendInvoice()

Send the hosted invoice link for an existing order.

public sendInvoice(array<string|int, mixed> $payload) : OrderDocumentDeliveryResult
Parameters
$payload : array<string|int, mixed>

Send invoice parameters

  • order_id: string - Unique identifier of the order whose invoice should be sent (required)
Return values
OrderDocumentDeliveryResult —

Order and delivery details

sendReceipt()

Send the hosted receipt link for a paid order.

public sendReceipt(array<string|int, mixed> $payload) : OrderDocumentDeliveryResult
Parameters
$payload : array<string|int, mixed>

Send receipt parameters

  • order_id: string - Unique identifier of the paid order whose receipt should be sent (required)
Return values
OrderDocumentDeliveryResult —

Order and delivery details

update()

Update mutable fields on an existing order (POST /orders/update).

public update(array<string|int, mixed> $payload) : Order
Parameters
$payload : array<string|int, mixed>
Return values
Order
On this page

Search results