Class: Inttegro::Resources::Orders

Inherits:
Object
  • Object
show all
Defined in:
lib/inttegro/resources/orders.rb

Overview

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.

See Also:

Instance Method Summary collapse

Constructor Details

#initialize(http) ⇒ Orders

Returns a new instance of Orders.

Parameters:



15
16
17
 
# File 'lib/inttegro/resources/orders.rb', line 15

def initialize(http)
  @http = T.let(http, Inttegro::HTTPClient)
end

Instance Method Details

#cancel(order_id:, request_meta: nil) ⇒ Inttegro::Order

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.

Examples:

Cancel an order

order = client.orders.cancel(
  order_id: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb'
)

puts "Order #{order.id} has been cancelled"

Parameters:

  • order_id (String) —

    Unique identifier of the order to cancel (required)

  • request_meta (Hash, nil) (defaults to: nil) —

    Request controls such as idempotency_key (optional)

Returns:

See Also:



358
359
360
361
362
363
364
365
366
367
368
 
# File 'lib/inttegro/resources/orders.rb', line 358

def cancel(order_id:, request_meta: nil)
  @http.post_resource(
    "/orders/cancel",
    Inttegro::Order,
    :order,
    {
      order_id: order_id,
      request_meta: request_meta || stable_order_request_meta("cancel", order_id)
    }
  )
end

#complete(payload) ⇒ Inttegro::Order

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

Examples:

Complete order after fulfillment

order = client.orders.complete(
  order_id: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb'
)

puts "Order completed at: #{order.completed_at}"

Complete order with offline payment

result = client.orders.complete(
  order_id: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb',
  paid_out_of_band: true
)

Parameters:

Options Hash (payload):

  • :order_id (String) —

    Unique identifier of the order to complete (required)

  • :paid_out_of_band (Boolean) —

    Set to true if payment received outside Inttegro (default: false)

Returns:

See Also:



336
337
338
 
# File 'lib/inttegro/resources/orders.rb', line 336

def complete(payload)
  @http.post_resource("/orders/complete", Inttegro::Order, :order, payload)
end

#confirm_payment(payload) ⇒ Inttegro::Order

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.

Examples:

Confirm payment with OTP

order = client.orders.confirm_payment(
  order_id: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb',
  token: '123456'
)

if order.payment&.status == Inttegro::Payment::Status::PAID
  puts 'Payment confirmed successfully!'
end

Parameters:

Options Hash (payload):

  • :order_id (String) —

    Unique identifier of the order being paid (required)

  • :token (String) —

    Verification token provided by customer (required, typically 6 digits)

Returns:

See Also:



220
221
222
 
# File 'lib/inttegro/resources/orders.rb', line 220

def confirm_payment(payload)
  @http.post_resource("/orders/confirm_payment", Inttegro::Order, :order, payload)
end

#create(payload) ⇒ Inttegro::Order

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

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.

Examples:

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'
  }
)

puts "Created order: #{order.id}"

Create order with existing customer

result = client.orders.create(
  customer_id: 'cu_abc123',
  line_items: [{
    type: 'product',
    product: {
      type: 'physical',
      name: 'T-Shirt',
      quantity: 2,
      price: { currency: 'ghs', value: 8000 }
    }
  }],
  billing_details: {
    name: 'Kwame Osei',
    phone_number: '+233501234567'
  }
)

Parameters:

Options Hash (payload):

  • :customer_data (Hash) —

    New customer information (required if customer_id not provided)

  • :customer_id (String) —

    Existing customer ID (required if customer_data not provided)

  • :line_items (Array<Hash>) —

    List of products/services being purchased (required)

  • :billing_details (Hash) —

    Billing contact information (required)

  • :payment_method_id (String) —

    ID of saved payment method to use

  • :payment_method_data (Hash) —

    Inline payment method details

  • :execute_payment (Boolean) —

    Whether to immediately charge (default: false)

  • :checkout_settings (Hash) —

    Checkout flow configuration with redirect_url and cancel_url

  • :payout_settings (Hash) —

    Order-specific payout destination configuration

  • :custom_data (Hash) —

    Key-value custom data (max 25KB, keys and values must be strings)

  • :request_meta (Hash) —

    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 (Boolean) —

    Whether to explicitly finalize order (default: false)

Returns:

See Also:



103
104
105
 
# File 'lib/inttegro/resources/orders.rb', line 103

def create(payload)
  @http.post_resource("/orders/create", Inttegro::Order, :order, payload)
end

#create_with_response(payload) ⇒ Inttegro::APIResponse

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

Parameters:

Returns:



111
112
113
 
# File 'lib/inttegro/resources/orders.rb', line 111

def create_with_response(payload)
  @http.post_resource_with_response("/orders/create", Inttegro::Order, :order, payload)
end

#finalize(order_id:, request_meta: nil) ⇒ Inttegro::Order

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

Examples:

Finalize an order

order = client.orders.finalize(
  order_id: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb'
)

puts "Order finalized at: #{order.sealed_at}"

Parameters:

  • order_id (String) —

    Unique identifier of the order to finalize (required)

  • request_meta (Hash, nil) (defaults to: nil) —

    Request controls such as idempotency_key (optional)

Returns:

See Also:



272
273
274
275
276
277
278
279
280
281
282
 
# File 'lib/inttegro/resources/orders.rb', line 272

def finalize(order_id:, request_meta: nil)
  @http.post_resource(
    "/orders/finalize",
    Inttegro::Order,
    :order,
    {
      order_id: order_id,
      request_meta: request_meta || stable_order_request_meta("finalize", order_id)
    }
  )
end

#lookup(order_id:, **options) ⇒ Inttegro::Order

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.

Examples:

Lookup an order

order = client.orders.lookup(
  order_id: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb'
)

puts "Order status: #{order.status.serialize}"

Parameters:

  • order_id (String) —

    Unique identifier of the order to retrieve (required)

  • options (Hash) —

    Additional options (currently unused)

Returns:

See Also:



133
134
135
136
 
# File 'lib/inttegro/resources/orders.rb', line 133

def lookup(order_id:, **options)
  body = { order_id: order_id }.merge(options)
  @http.post_resource("/orders/lookup", Inttegro::Order, :order, body)
end

#page(payload = {}) ⇒ Inttegro::Order::Page

Retrieve a paginated list of orders.

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

Examples:

Get first page of orders

page = client.orders.page(
  page_size: 25,
  page_number: 0
)

puts "Retrieved #{page.orders&.length || 0} orders"

Restrict the page to one customer

customer_orders = client.orders.page(
  customer_id: 'cu_123',
  page_size: 50
)

Parameters:

Options Hash (payload):

  • :page_number (Integer) —

    Zero-based page index to retrieve (0-10)

  • :page_size (Integer) —

    Number of orders per page (1-256)

  • :customer_id (String) —

    Optional customer whose orders should be returned

Returns:

See Also:



397
398
399
 
# File 'lib/inttegro/resources/orders.rb', line 397

def page(payload = {})
  @http.post_resource("/orders/page", Inttegro::Order::Page, :page, payload || {})
end

#pay(payload) ⇒ Inttegro::Order

Initiate payment for an existing 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 next_action field.

Examples:

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&.next_action&.type == Inttegro::Payment::NextActionType::CONFIRM_PAYMENT
  # Customer needs to provide OTP sent to their phone
  puts 'Please enter the OTP sent to your phone'
end

Pay with saved payment method

result = client.orders.pay(
  order_id: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb',
  payment_method_id: 'pm_xyz123abc456'
)

Mark as paid offline

result = client.orders.pay(
  order_id: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb',
  paid_out_of_band: true
)

Parameters:

Options Hash (payload):

  • :order_id (String) —

    Unique identifier of the order to pay (required)

  • :payment_method_data (Hash) —

    Inline payment method details (mobile money, card, etc.)

  • :payment_method_id (String) —

    ID of a saved payment method to use

  • :paid_out_of_band (Boolean) —

    Set to true if payment received outside Inttegro (default: false)

Returns:

See Also:



194
195
196
 
# File 'lib/inttegro/resources/orders.rb', line 194

def pay(payload)
  @http.post_resource("/orders/pay", Inttegro::Order, :order, payload)
end

#request_confirmation(order_id:, request_meta: nil) ⇒ Inttegro::Order

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.

Examples:

Resend OTP to customer

result = client.orders.request_confirmation(
  order_id: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb'
)

puts 'New OTP sent to customer'

Parameters:

  • order_id (String) —

    Unique identifier of the order requiring confirmation (required)

  • request_meta (Hash, nil) (defaults to: nil) —

    Request controls such as idempotency_key (optional)

Returns:

See Also:



242
243
244
245
246
247
248
249
250
251
252
 
# File 'lib/inttegro/resources/orders.rb', line 242

def request_confirmation(order_id:, request_meta: nil)
  @http.post_resource(
    "/orders/request_confirmation",
    Inttegro::Order,
    :order,
    {
      order_id: order_id,
      request_meta: request_meta || stable_order_request_meta("request_confirmation", order_id)
    }
  )
end

#search(payload) ⇒ Inttegro::Search::Page

Search orders using indexed fields and full-text matching.

Parameters:

Returns:



405
406
407
 
# File 'lib/inttegro/resources/orders.rb', line 405

def search(payload)
  @http.post_resource("/orders/search", Inttegro::Search::Page, :search, payload)
end

#send_invoice(order_id:) ⇒ Inttegro::Order::DocumentDeliveryResult

Send the hosted invoice link for an existing order.

Parameters:

  • order_id (String) —

    Unique identifier of the order whose invoice should be sent (required)

Returns:



289
290
291
292
293
294
295
 
# File 'lib/inttegro/resources/orders.rb', line 289

def send_invoice(order_id:)
  @http.post_model(
    "/orders/send_invoice",
    Inttegro::Order::DocumentDeliveryResult,
    { order_id: order_id }
  )
end

#send_receipt(order_id:) ⇒ Inttegro::Order::DocumentDeliveryResult

Send the hosted receipt link for a paid order.

Parameters:

  • order_id (String) —

    Unique identifier of the paid order whose receipt should be sent (required)

Returns:



302
303
304
305
306
307
308
 
# File 'lib/inttegro/resources/orders.rb', line 302

def send_receipt(order_id:)
  @http.post_model(
    "/orders/send_receipt",
    Inttegro::Order::DocumentDeliveryResult,
    { order_id: order_id }
  )
end

#update(payload) ⇒ Inttegro::Order

Update mutable fields on an order.

Parameters:

Returns:



142
143
144
 
# File 'lib/inttegro/resources/orders.rb', line 142

def update(payload)
  @http.post_resource("/orders/update", Inttegro::Order, :order, payload)
end