Package com.inttegro

Class Client.OrdersClient

java.lang.Object

com.inttegro.Client.OrdersClient

Enclosing class:

Client

public static class Client.OrdersClient
extends Object

Constructor Summary

Constructors

Constructor	Description
OrdersClient(Client client)

Method Summary

Modifier and Type	Method	Description
Order	cancel(OrderCancelParams params)
Order	cancel(String orderId)	Cancels an existing order (POST /orders/cancel).
Order	complete(OrderCompleteParams params)	Marks an order as completed (POST /orders/complete).
Order	confirmPayment(OrderConfirmParams params)	Confirms a pending payment using a verification token (POST /orders/confirm_payment).
Order	create(OrderCreateParams params)	Creates a new order (POST /orders/new).
Order	finalizeOrder(OrderFinalizeParams params)
Order	finalizeOrder(String orderId)	Finalizes an order to make it ready for payment (POST /orders/finalize).
Order	lookup(String orderId)	Retrieves details of an existing order by its ID (POST /orders/lookup).
Order	newOrder(OrderCreateParams params)
OrderPage	page(OrderPageParams params)	Retrieves a paginated list of orders (POST /orders/page).
Order	pay(OrderPayParams params)	Initiates payment for an existing order (POST /orders/pay).
Refund	refund(CreateRefundParams params)	Deprecated.
Refund	refund(CreateRefundParams params, RequestOptions options)	Deprecated.
Order	requestConfirmation(OrderRequestConfirmationParams params)
Order	requestConfirmation(String orderId)	Requests a new confirmation token to be sent to the customer (POST /orders/request_confirmation).
OrderDocumentDeliveryResult	sendInvoice(OrderSendInvoiceParams params)	Sends the hosted invoice link for an existing order (POST /orders/send_invoice).
OrderDocumentDeliveryResult	sendReceipt(OrderSendReceiptParams params)	Sends the hosted receipt link for a paid order (POST /orders/send_receipt).
Order	update(OrderUpdateParams params)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

OrdersClient

public OrdersClient(Client client)

Method Details

create

public Order create(OrderCreateParams params)
             throws IOException,
InterruptedException,
ApiException

Creates a new order (POST /orders/new).

Creates a new order in the Inttegro platform. Supports two flows:

1. New customer flow: Provide customer_data to create a new customer and order
2. Existing customer flow: Provide customer_id and optionally payment_method_id for known customers

The order can be configured to execute payment immediately or require manual payment later. Set execute_payment=true to charge immediately. Include checkout_settings with redirect and cancel URLs for hosted checkout flows. Optionally set finalize=true to seal the order immediately.

Parameters:

params - order creation parameters including customer info, line items, and payment settings

Returns:

the created order

Throws:

IOException - if network communication fails

InterruptedException - if the request is interrupted

ApiException - if the API returns an error (400, 401, 422)

newOrder

public Order newOrder(OrderCreateParams params)
               throws IOException,
InterruptedException,
ApiException

Throws:

IOException

InterruptedException

ApiException

lookup

public Order lookup(String orderId)
             throws IOException,
InterruptedException,
ApiException

Retrieves details of an existing order by its ID (POST /orders/lookup).

Returns full order details including line items, payment status, customer information, invoice URLs, and all timestamps. The order may or may not exist.

Parameters:

orderId - unique identifier of the order to lookup

Returns:

the order details

Throws:

IOException - if network communication fails

InterruptedException - if the request is interrupted

ApiException - if the order is not found (404) or other API errors occur

update

public Order update(OrderUpdateParams params)
             throws IOException,
InterruptedException,
ApiException

Throws:

IOException

InterruptedException

ApiException

pay

public Order pay(OrderPayParams params)
          throws IOException,
InterruptedException,
ApiException

Initiates payment for an existing order (POST /orders/pay).

Supports two payment flows:

1. Use saved payment method: Provide only order_id to charge a previously saved payment method
2. Provide new payment details: Include payment_method_data with payment information (e.g., mobile money network and account number)

For out-of-band payments (cash, bank transfer, check), set paid_out_of_band=true to mark the payment as paid offline. This is mutually exclusive with payment_method_id and payment_method_data.

Parameters:

params - payment parameters including order ID and payment method information

Returns:

the updated order, including payment and next-action state

Throws:

IOException - if network communication fails

InterruptedException - if the request is interrupted

ApiException - if the order is not found (404), already paid, or other API errors occur

confirmPayment

public Order confirmPayment(OrderConfirmParams params)
                     throws IOException,
InterruptedException,
ApiException

Confirms a pending payment using a verification token (POST /orders/confirm_payment).

Use this endpoint when a payment requires confirmation (OTP verification). The payment response will indicate requires_confirmation=true when a token has been sent to the customer's phone or email. Submit the token the customer provides to complete the payment.

Parameters:

params - confirmation parameters including order ID and verification token (OTP)

Returns:

the updated order with confirmed payment status

Throws:

IOException - if network communication fails

InterruptedException - if the request is interrupted

ApiException - if the token is invalid (400), order not found (404), or other API errors occur

requestConfirmation

public Order requestConfirmation(String orderId)
                          throws IOException,
InterruptedException,
ApiException

Requests a new confirmation token to be sent to the customer (POST /orders/request_confirmation).

Triggers delivery of a new payment verification token (OTP) to the customer. Use this when the customer didn't receive the initial token or needs a replacement. The token will be sent via the same channel (SMS or email) as the original.

Parameters:

orderId - unique identifier of the order requiring confirmation

Throws:

IOException - if network communication fails

InterruptedException - if the request is interrupted

ApiException - if the order is not found (404) or doesn't require confirmation

requestConfirmation

public Order requestConfirmation(OrderRequestConfirmationParams params)
                          throws IOException,
InterruptedException,
ApiException

Throws:

IOException

InterruptedException

ApiException

finalizeOrder

public Order finalizeOrder(String orderId)
                    throws IOException,
InterruptedException,
ApiException

Finalizes an order to make it ready for payment (POST /orders/finalize).

Once finalized, the order becomes immutable—line items, totals, and customer data can no longer be changed. This endpoint generates an invoice and hosted checkout page that you can share with customers. The response includes invoice URLs and the sealed_at timestamp marking when the order was finalized.

Use this when you've finished building the cart and want to present it to the customer for payment.

Parameters:

orderId - unique identifier of the order to finalize

Returns:

the finalized order with invoice and checkout URLs

Throws:

IOException - if network communication fails

InterruptedException - if the request is interrupted

ApiException - if the order is not found (404), already finalized, or cannot be finalized (422)

finalizeOrder

public Order finalizeOrder(OrderFinalizeParams params)
                    throws IOException,
InterruptedException,
ApiException

Throws:

IOException

InterruptedException

ApiException

sendInvoice

public OrderDocumentDeliveryResult sendInvoice(OrderSendInvoiceParams params)
                                        throws IOException,
InterruptedException,
ApiException

Sends the hosted invoice link for an existing order (POST /orders/send_invoice).

Parameters:

params - send invoice parameters including order ID

Returns:

the order document delivery result

Throws:

IOException - if network communication fails

InterruptedException - if the request is interrupted

ApiException - if the order is not found or delivery fails

sendReceipt

public OrderDocumentDeliveryResult sendReceipt(OrderSendReceiptParams params)
                                        throws IOException,
InterruptedException,
ApiException

Sends the hosted receipt link for a paid order (POST /orders/send_receipt).

Parameters:

params - send receipt parameters including order ID

Returns:

the order document delivery result

Throws:

IOException - if network communication fails

InterruptedException - if the request is interrupted

ApiException - if the order is not found, unpaid, or delivery fails

complete

public Order complete(OrderCompleteParams params)
               throws IOException,
InterruptedException,
ApiException

Marks an order as completed (POST /orders/complete).

Transitions the order to the completed state. An order can only be completed if its associated payment has been successfully paid. Once completed, the order status becomes completed and the completed_at timestamp is set.

Use the paid_out_of_band parameter when payment happened offline (outside the Inttegro platform) to force the payment status to paid before completing the order. This is useful for cash payments, bank transfers, or other out-of-band payment methods.

Parameters:

params - completion parameters including order ID and optional out-of-band payment flag

Returns:

the completed order

Throws:

IOException - if network communication fails

InterruptedException - if the request is interrupted

ApiException - if the order is not found (404), payment not paid, or other API errors occur

cancel

public Order cancel(String orderId)
             throws IOException,
InterruptedException,
ApiException

Cancels an existing order (POST /orders/cancel).

Transitions the order to cancelled status. Use this when an order should be voided or abandoned. The order will reflect the cancelled_at timestamp. Cancelled orders cannot be paid or completed.

Parameters:

orderId - unique identifier of the order to cancel

Returns:

the cancelled order

Throws:

IOException - if network communication fails

InterruptedException - if the request is interrupted

ApiException - if the order is not found (404) or cannot be cancelled

cancel

public Order cancel(OrderCancelParams params)
             throws IOException,
InterruptedException,
ApiException

Throws:

IOException

InterruptedException

ApiException

refund

@Deprecated
public Refund refund(CreateRefundParams params)
              throws IOException,
InterruptedException,
ApiException

Deprecated.

Compatibility alias for Client.RefundsClient.create(CreateRefundParams). Accepts the same line-item refund request and returns the created refund.

Throws:

IOException

InterruptedException

ApiException

refund

@Deprecated
public Refund refund(CreateRefundParams params,
 RequestOptions options)
              throws IOException,
InterruptedException,
ApiException

Deprecated.

Compatibility alias with an explicit idempotency key.

Throws:

IOException

InterruptedException

ApiException

page

public OrderPage page(OrderPageParams params)
               throws IOException,
InterruptedException,
ApiException

Retrieves a paginated list of orders (POST /orders/page).

Returns recent orders with pagination support. Use the page_index and page_size parameters to control pagination. Orders are returned in reverse chronological order (newest first).

Parameters:

params - pagination parameters including page index and size

Returns:

the page of complete orders

Throws:

IOException - if network communication fails

InterruptedException - if the request is interrupted

ApiException - if invalid pagination parameters are provided (400)