Skip to main content
View as Markdown

Refunds

Refunds return all or part of a paid order to the customer's original payment method. Use this API to create a refund, follow its progress, cancel it before processing begins, or browse previous refunds.

For an explanation of refund eligibility, lifecycle, and effects on balances and payouts, read the Refunds product guide. This page is the endpoint reference.

Create new refunds through POST /refunds/create.

The refund object

A refund records the amounts requested against an order's line items, why they were returned, where the money is settled, and the refund's current status. Payment-method refunds begin as Inttegro.RefundStatuses.Pending and then become Inttegro.RefundStatuses.Processing, Inttegro.RefundStatuses.Succeeded, or Inttegro.RefundStatuses.Failed. Offline refunds begin as Inttegro.RefundStatuses.Pending and become Inttegro.RefundStatuses.Succeeded only after a trusted operator records the settlement. A refund canceled before processing begins has a Inttegro.RefundStatuses.Canceled status.

Order responses may include the same objects in refunds, with the newest refund first. Optional properties and lifecycle timestamps appear when they have a value.

Each refund line includes an immutable

lineItems[].orderLineItem snapshot when the originating order can be resolved. Treat it as a union selected by lineItems[].orderLineItem.type: "product", "fee", or "shipping". Match the allocation to the order through order_line_item.id. For product lines, order_line_item.product.id links to the source catalog product; inline products omit that product ID.

Properties​

TypeScript SDK responseRefundv12.0.0
Warning

The settlement snapshot never contains a full phone or bank-account number, provider identifiers, fingerprints, credentials, verification request IDs, or custom data. Store it with the refund as historical display evidence; use Payment Methods endpoints for current management state.

Failure reason values​

POST/refunds/create

Create a refund

Return all or part of one or more paid order line items. Inttegro sends each amount back through the payment method used for the order. Processing happens asynchronously, so every new refund begins in Inttegro.RefundStatuses.Pending status.

Before creating the refund:

  • Read the order to obtain its line-item IDs and current refundable amounts.
  • Include each line item once, using the same currency and no more than its remaining refundable amount.
  • Reuse the same idempotency key and request body if the result of a request is uncertain.

Request attributes​

TypeScript SDK requestCreateRefundRequestv12.0.0

Response​

Returns the new refund in Inttegro.RefundStatuses.Pending status. Save its id and use Lookup a refund when you need its latest status.

Request

POST/refunds/create
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.refunds.create({
  customData: {
    warehouse: "accra",
  },
  lineItems: [
    {
      orderLineItemId: "oli_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN",
      reason: Inttegro.RefundReasons.ItemDamaged,
      reasonDetails: "Packaging was crushed.",
      refundAmount: {
        currency: "ghs",
        value: 2500,
      },
    },
    {
      orderLineItemId: "oli_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn",
      refundAmount: {
        currency: "ghs",
        value: 1000,
      },
    },
  ],
  orderId: "or_0123456789abcdefghijklmnopqrstuvwxyzABCD",
  reason: Inttegro.RefundReasons.RequestedByCustomer,
  reasonDetails: "Customer returned part of the order.",
  reference: "return_1042",
}, {
  idempotencyKey: "refund-return-1042",
})

Response excerpt

SDK versionv12.0.0
RefundResponse {
  refund: { … },
}
POST/refunds/cancel

Cancel a refund

Cancel a refund while its status is Inttegro.RefundStatuses.Pending, before Inttegro begins processing it. Cancellation releases the balance reserved for the refund and restores the affected order lines' refundable amounts.

A refund cannot be canceled once it is Inttegro.RefundStatuses.Processing, Inttegro.RefundStatuses.Succeeded, or Inttegro.RefundStatuses.Failed. Repeating this operation for an already canceled refund returns the same refund, making retries safe when you reuse the same idempotency key and request body.

Request attributes​

TypeScript SDK requestCancelRefundRequestv12.0.0
  • Name
    reason
    Type
    string
    Description

    Optional explanation for canceling the refund. Inttegro removes leading and trailing whitespace; when supplied, the remaining text must contain 1–2,048 characters. It is returned as

    cancelReason

    . An idempotent repeat preserves the explanation recorded by the first successful cancellation.

  • Name
    refundId
    Type
    string
    Required
    required
    Description

    Refund to cancel, with the rf_ prefix.

  • requestMetaRequestMetaOptional body-level idempotency key. Prefer the Idempotency-Key header for new integrations.Click or tap to expand
    • Name
      idempotencyKey
      Type
      string
      Description
      Stable retry key from 1 through 255 characters. It must match the Idempotency-Key header when both are present.

Response​

Returns the refund in Inttegro.RefundStatuses.Canceled status. When a reason was supplied, the response includes cancelReason; the selected SDK view shows its native property name.

Request

POST/refunds/cancel
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.refunds.cancel({
  reason: "Customer asked us to stop the return.",
  refundId: "rf_1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcd",
}, {
  idempotencyKey: "cancel-refund-return-1042",
})
POST/refunds/lookup

Lookup a refund

Retrieve a refund's current status and line-item amounts. Use this after creating or canceling a refund, or when helping a customer with a return.

Request attributes​

TypeScript SDK requestLookupRefundRequestv12.0.0
  • Name
    refundId
    Type
    string
    Required
    required
    Description

    Refund to retrieve, with the rf_ prefix.

Response​

Returns the requested refund.

Request

POST/refunds/lookup
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.refunds.lookup({
  refundId: "$INTTEGRO_REFUND_ID",
})
POST/refunds/page

List refunds

Browse refunds from newest to oldest. Use this endpoint to build refund history, customer-service, and reconciliation views.

Pages are one-based. pageSize defaults to 256, and the response's size is the number of refunds actually returned. An empty page is successful and contains size set to 0 and an empty refunds collection.

Request attributes​

TypeScript SDK requestPageRefundsRequestv12.0.0
  • Name
    pageNumber
    Type
    number
    Required
    required
    Description

    Page to retrieve, from 1 through 10.

  • Name
    pageSize
    Type
    number
    Description

    Maximum refunds to request, from 1 through 256. Defaults to 256.

Response​

Returns the page number, number of results, and a refunds array. An empty page returns an empty refunds collection and size set to 0.

Request

POST/refunds/page
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.refunds.page({
  pageNumber: 1,
  pageSize: 20,
})

Response excerpt

SDK versionv12.0.0
PageResponse {
  page: { … },
}

Handling refund failures

Request errors and terminal refund failures are different. A request rejected before a refund is created uses the standard error envelope. An accepted refund that later reaches

Inttegro.RefundStatuses.Failed includes failure.

Use the reason to choose the next step:

  • Refunds product guide — Understand eligibility, lifecycle, balances, and payouts.
  • Lookup an order — Read the paid order and its line-item IDs before creating a refund.
  • Errors — Handle Inttegro API errors consistently.