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.



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

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:



349
350
351
352
353
354
355
356
357
358
359
 
# File 'lib/inttegro/resources/orders.rb', line 349

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:

  • payload (Hash) —

    Completion 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:



327
328
329
 
# File 'lib/inttegro/resources/orders.rb', line 327

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::PaymentStatus::PAID
  puts 'Payment confirmed successfully!'
end

Parameters:

  • payload (Hash) —

    Confirmation 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:



211
212
213
 
# File 'lib/inttegro/resources/orders.rb', line 211

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:

  • payload (Hash) —

    Order creation 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:



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

def create(payload)
  @http.post_resource("/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:



263
264
265
266
267
268
269
270
271
272
273
 
# File 'lib/inttegro/resources/orders.rb', line 263

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:



128
129
130
131
 
# File 'lib/inttegro/resources/orders.rb', line 128

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

#new(payload) ⇒ Object 



106
107
108
 
# File 'lib/inttegro/resources/orders.rb', line 106

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

#page(payload = {}) ⇒ Inttegro::OrderPage

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:

  • payload (Hash) (defaults to: {}) —

    Pagination and filter parameters (optional)

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:



414
415
416
 
# File 'lib/inttegro/resources/orders.rb', line 414

def page(payload = {})
  @http.post_resource("/orders/page", Inttegro::OrderPage, :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::PaymentNextActionType::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:

  • payload (Hash) —

    Payment 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:



185
186
187
 
# File 'lib/inttegro/resources/orders.rb', line 185

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

#refund(payload) ⇒ Inttegro::Refund

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

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

Examples:

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

puts "Refund created: #{refund.id}"

Parameters:

  • payload (Hash) —

    Create-refund payload containing order_id, reason, and line_items

Returns:

See Also:



383
384
385
 
# File 'lib/inttegro/resources/orders.rb', line 383

def refund(payload)
  @http.post_resource("/orders/refund", Inttegro::Refund, :refund, 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:



233
234
235
236
237
238
239
240
241
242
243
 
# File 'lib/inttegro/resources/orders.rb', line 233

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

#send_invoice(order_id:) ⇒ Inttegro::OrderDocumentDeliveryResult

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:



280
281
282
283
284
285
286
 
# File 'lib/inttegro/resources/orders.rb', line 280

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

#send_receipt(order_id:) ⇒ Inttegro::OrderDocumentDeliveryResult

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:



293
294
295
296
297
298
299
 
# File 'lib/inttegro/resources/orders.rb', line 293

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

#update(payload) ⇒ Object 



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

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