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
Creates the orders resource client.
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.
createWithResponse()  : Response
Create a new order and keep HTTP response metadata with the decoded order.
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()  : Page
Retrieve a paginated list of orders.
pay()  : Order
Initiate payment for an existing order.
requestConfirmation()  : Order
Request a new confirmation token to be sent to the customer (e.g., resend OTP).
search()  : ResourceSearchPage
Search orders with a typed resource-local query.
sendInvoice()  : DocumentDeliveryResult
Send the hosted invoice link for an existing order.
sendReceipt()  : DocumentDeliveryResult
Send the hosted receipt link for a paid order.
update()  : Order
Update mutable fields on an existing order (POST /orders/update).

Methods

__construct()

Creates the orders resource client.

public __construct(HttpClient $http) : mixed
Parameters
$http : HttpClient

Shared authenticated HTTP transport used by this resource client.

cancel()

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

public cancel(string $orderId[, array<string, 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, 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, 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, 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?->format(DATE_RFC3339) . "\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, 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, 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, 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, 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

createWithResponse()

Create a new order and keep HTTP response metadata with the decoded order.

public createWithResponse(array<string, mixed> $payload) : Response
Parameters
$payload : array<string, mixed>

Order creation parameters.

Return values
Response —

Response whose data is an Order.

finalize()

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

public finalize(string $orderId[, array<string, 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, mixed> = []

Request controls such as idempotency_key (optional)

Tags
example

Finalize an order

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

echo "Order finalized at: " . $order->sealedAt?->format(DATE_RFC3339) . "\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, 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, 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, mixed> $payload = [] ]) : Page

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

Parameters
$payload : array<string, 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
Page —

Paginated orders and pagination details

pay()

Initiate payment for an existing order.

public pay(array<string, 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, 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

requestConfirmation()

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

public requestConfirmation(string $orderId[, array<string, 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, 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, mixed> $payload) : DocumentDeliveryResult
Parameters
$payload : array<string, mixed>

Send invoice parameters

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

Order and delivery details

sendReceipt()

Send the hosted receipt link for a paid order.

public sendReceipt(array<string, mixed> $payload) : DocumentDeliveryResult
Parameters
$payload : array<string, mixed>

Send receipt parameters

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

Order and delivery details

update()

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

public update(array<string, mixed> $payload) : Order

Sends the documented request through the shared authenticated transport and hydrates the successful response into the declared return type.

Parameters
$payload : array<string, mixed>

Request fields keyed by the documented snake_case API names.

Return values
Order —

The updated order.

On this page

Search results