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 older POST /orders/refund route remains available for compatibility and is documented with the Orders API.

Operations

Create a refund
Cancel a refund
Lookup a refund
List refunds

The refund object

A refund records the amounts requested against an order's line items, why they were returned, and the refund's current status. New refunds begin as pending and then become processing, succeeded, or failed. A refund canceled before processing begins has a canceled status.

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

Properties

Name
canceled_at
Type
timestamp
Description
When the refund entered the canceled state. Omitted otherwise.
Name
created_at
Type
timestamp
Description
When the refund was created.
custom_dataobjectClick or tap to expand
Your metadata, returned as string values. Omitted when empty.
Name
failed_at
Type
timestamp
Description
When the refund entered the failed state. Omitted otherwise.
Name
id
Type
string
Description
Unique refund identifier with the rf_ prefix.
line_itemsobjectImmutable allocations describing how much is refunded for each order line item.Click or tap to expand
- Name
  id
  Type
  string
  Description
  Server-generated refund line-item ID with the rli_ prefix.
- Name
  order_line_item_id
  Type
  string
  Description
  Strong reference to the original order line item, with the oli_ prefix.
- Name
  original_amount_paid
  Type
  object
  View original_amount_paid attributesClick or tap to expand
  Amount originally paid for this order line allocation.
  Name
  currency
  Type
  string
  Description
  Lowercase currency code.
  Name
  value
  Type
  integer
  Description
  Positive amount in the smallest currency unit.
- Name
  reason
  Type
  enum
  Description
  Independent reason for refunding this line. Omitted when not provided.
- Name
  reason_details
  Type
  string
  Description
  Line-specific explanation. Omitted when not provided.
- Name
  refund_amount
  Type
  object
  View refund_amount attributesClick or tap to expand
  Amount returned for this line.
  Name
  currency
  Type
  string
  Description
  Lowercase currency code.
  Name
  value
  Type
  integer
  Description
  Positive amount in the smallest currency unit.
Name
order_id
Type
string
Description
Paid order covered by this refund, with the or_ prefix.
Name
processing_at
Type
timestamp
Description
When refund processing began. Omitted until processing starts.
Name
reason
Type
enum
Description
Overall refund reason: custom, duplicate, fraudulent, item_damaged, item_not_as_described, item_not_received, item_returned, order_canceled, or requested_by_customer.
Name
reason_details
Type
string
Description
Overall explanation. Omitted when not provided.
Name
reference
Type
string
Description
Your reconciliation reference. Omitted when not provided.
Name
status
Type
enum
Description
Current state: canceled, failed, pending, processing, or succeeded.
Name
succeeded_at
Type
timestamp
Description
When the refund entered the succeeded state. Omitted otherwise.
totalobjectSum of the requested line-item refund amounts.Click or tap to expand
- Name
  currency
  Type
  string
  Description
  Lowercase currency code.
- Name
  value
  Type
  integer
  Description
  Positive amount in the smallest currency unit.

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

custom_dataobjectClick or tap to expand
Optional metadata for reconciliation. The object can contain at most 25 KB of JSON, and each key can contain at most 256 characters. Stored values are returned as strings.
line_itemsobjectrequiredOne to 64 order line-item allocations to refund. Each order line item can appear only once.Click or tap to expand
- Name
  order_line_item_id
  Type
  string
  Required
  required
  Description
  Order line-item ID with the oli_ prefix. It must belong to order_id.
- Name
  reason
  Type
  enum
  Description
  Optional reason specific to this line. It is independent of the overall refund reason. Allowed values: custom, duplicate, fraudulent, item_damaged, item_not_as_described, item_not_received, item_returned, order_canceled, or requested_by_customer.
- Name
  reason_details
  Type
  string
  Description
  Optional line-specific explanation, up to 2,048 characters. Requires a line-level reason and is required when that reason is custom.
- Name
  refund_amount
  Type
  object
  Required
  required
  View refund_amount attributesClick or tap to expand
  Positive amount to refund for this line. It cannot exceed the remaining refundable amount.
  Name
  currency
  Type
  string
  Required
  required
  Description
  Currency code. It is normalized to lowercase and must match the order line item.
  Name
  value
  Type
  integer
  Required
  required
  Description
  Amount in the smallest currency unit; minimum 1.
Name
order_id
Type
string
Required
required
Description
Paid order to refund, using the or_ ID returned by Inttegro.
Name
reason
Type
enum
Required
required
Description
Overall refund reason. Allowed values: custom, duplicate, fraudulent, item_damaged, item_not_as_described, item_not_received, item_returned, order_canceled, or requested_by_customer.
Name
reason_details
Type
string
Description
Optional overall explanation, up to 2,048 characters. Required when reason is custom.
Name
reference
Type
string
Description
Optional non-empty reconciliation reference, up to 256 characters.

Response

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

Request

POST/refunds/create

curl --fail-with-body https://api.inttegro.com/refunds/create \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-return-1042" \
  -d '{
    "custom_data": {
      "warehouse": "accra"
    },
    "line_items": [
      {
        "order_line_item_id": "oli_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN",
        "reason": "item_damaged",
        "reason_details": "Packaging was crushed.",
        "refund_amount": {
          "currency": "ghs",
          "value": 2500
        }
      },
      {
        "order_line_item_id": "oli_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn",
        "refund_amount": {
          "currency": "ghs",
          "value": 1000
        }
      }
    ],
    "order_id": "or_0123456789abcdefghijklmnopqrstuvwxyzABCD",
    "reason": "requested_by_customer",
    "reason_details": "Customer returned part of the order.",
    "reference": "return_1042"
  }'

SDK versionv8.2.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",
})

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
  "github.com/zebodotdev/inttegro-sdk-go/v4/money"
)

func main() {
  ctx := context.Background()
  client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))

  params := inttegro.CreateRefundRequest{
    CustomData: map[string]string{
      "warehouse": "accra",
    },
    LineItems: []inttegro.CreateRefundLineItem{
      {
        OrderLineItemID: "oli_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN",
        Reason: func() *inttegro.RefundReason { value := inttegro.RefundReasonItemDamaged; return &value }(),
        ReasonDetails: "Packaging was crushed.",
        RefundAmount: money.AmountParams{
          Currency: money.GHS,
          Value: 2500,
        },
      },
      {
        OrderLineItemID: "oli_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn",
        RefundAmount: money.AmountParams{
          Currency: money.GHS,
          Value: 1000,
        },
      },
    },
    OrderID: "or_0123456789abcdefghijklmnopqrstuvwxyzABCD",
    Reason: inttegro.RefundReasonRequestedByCustomer,
    ReasonDetails: "Customer returned part of the order.",
    Reference: "return_1042",
  }
  result, err := client.Refunds.Create(ctx, params)
  if err != nil {
    log.Fatal(err)
  }
  _ = result
}

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.refunds.create(inttegro.refunds.CreateRequest(
  custom_data={
    "warehouse": "accra",
  },
  line_items=[
    inttegro.refunds.LineItem(
      order_line_item_id="oli_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN",
      reason=inttegro.RefundReason.ITEM_DAMAGED,
      reason_details="Packaging was crushed.",
      refund_amount=inttegro.refunds.AmountParams(
        currency=inttegro.Currency.GHS,
        value=2500,
      ),
    ),
    inttegro.refunds.LineItem(
      order_line_item_id="oli_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn",
      refund_amount=inttegro.refunds.AmountParams(
        currency=inttegro.Currency.GHS,
        value=1000,
      ),
    ),
  ],
  order_id="or_0123456789abcdefghijklmnopqrstuvwxyzABCD",
  reason=inttegro.RefundReason.REQUESTED_BY_CUSTOMER,
  reason_details="Customer returned part of the order.",
  reference="return_1042",
),
    idempotency_key="refund-return-1042")

SDK versionv5.3.0

<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->refunds->create([
  'custom_data' => [
    'warehouse' => 'accra',
  ],
  'line_items' => [
    [
      'order_line_item_id' => 'oli_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN',
      'reason' => \Inttegro\RefundReason::ItemDamaged,
      'reason_details' => 'Packaging was crushed.',
      'refund_amount' => [
        'currency' => 'ghs',
        'value' => 2500,
      ],
    ],
    [
      'order_line_item_id' => 'oli_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn',
      'refund_amount' => [
        'currency' => 'ghs',
        'value' => 1000,
      ],
    ],
  ],
  'order_id' => 'or_0123456789abcdefghijklmnopqrstuvwxyzABCD',
  'reason' => \Inttegro\RefundReason::RequestedByCustomer,
  'reason_details' => 'Customer returned part of the order.',
  'reference' => 'return_1042',
], "refund-return-1042");

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.refunds.create(
  custom_data: {
    warehouse: "accra",
  },
  line_items: [
    {
      order_line_item_id: "oli_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN",
      reason: Inttegro::RefundReason::ITEM_DAMAGED,
      reason_details: "Packaging was crushed.",
      refund_amount: {
        currency: "ghs",
        value: 2500,
      },
    },
    {
      order_line_item_id: "oli_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn",
      refund_amount: {
        currency: "ghs",
        value: 1000,
      },
    },
  ],
  order_id: "or_0123456789abcdefghijklmnopqrstuvwxyzABCD",
  reason: Inttegro::RefundReason::REQUESTED_BY_CUSTOMER,
  reason_details: "Customer returned part of the order.",
  reference: "return_1042",
  idempotency_key: "refund-return-1042"
)

SDK versionv5.2.0

import com.inttegro.Client;
import com.inttegro.refunds.CreateRefundParams;
import java.util.Map;
import com.inttegro.refunds.CreateRefundLineItem;
import com.inttegro.refunds.RefundReason;
import com.inttegro.money.AmountParams;
import com.inttegro.money.Currency;
import com.inttegro.RequestOptions;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = CreateRefundParams.builder()
      .customData(Map.<String, String>ofEntries(
          Map.entry("warehouse", "accra")
        ))
      .lineItem(CreateRefundLineItem.builder()
          .orderLineItemId("oli_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN")
          .reason(RefundReason.ITEM_DAMAGED)
          .reasonDetails("Packaging was crushed.")
          .refundAmount(AmountParams.of(Currency.GHS, 2500))
          .build())
      .lineItem(CreateRefundLineItem.builder()
          .orderLineItemId("oli_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn")
          .refundAmount(AmountParams.of(Currency.GHS, 1000))
          .build())
      .orderId("or_0123456789abcdefghijklmnopqrstuvwxyzABCD")
      .reason(RefundReason.REQUESTED_BY_CUSTOMER)
      .reasonDetails("Customer returned part of the order.")
      .reference("return_1042")
      .build();
    var result = client.refunds().create(params, RequestOptions.withIdempotencyKey("refund-return-1042"));
  }
}

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.Refunds.CreateAsync(new Inttegro.CreateRefundRequest {
  CustomData = new Dictionary<string, string> {
    ["warehouse"] = "accra",
  },
  LineItems = new List<Inttegro.CreateRefundLineItem> {
    new Inttegro.CreateRefundLineItem {
      OrderLineItemId = "oli_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN",
      Reason = Inttegro.RefundReason.ItemDamaged,
      ReasonDetails = "Packaging was crushed.",
      RefundAmount = new Inttegro.Money.AmountParams {
        Currency = Inttegro.Money.Currency.GHS,
        Value = 2500,
      },
    },
    new Inttegro.CreateRefundLineItem {
      OrderLineItemId = "oli_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn",
      RefundAmount = new Inttegro.Money.AmountParams {
        Currency = Inttegro.Money.Currency.GHS,
        Value = 1000,
      },
    },
  },
  OrderId = "or_0123456789abcdefghijklmnopqrstuvwxyzABCD",
  Reason = Inttegro.RefundReason.RequestedByCustomer,
  ReasonDetails = "Customer returned part of the order.",
  Reference = "return_1042",
}, "refund-return-1042");

Response

Object
JSON

SDK versionv8.2.0

RefundResponse {
  refund: { … },
}

SDK versionv8.2.0

{
  "refund": {
    "created_at": "2026-08-30T12:00:00Z",
    "custom_data": { … },
    "id": "rf_1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcd",
    "line_items": [ … ],
    "order_id": "or_0123456789abcdefghijklmnopqrstuvwxyzABCD",
    "reason": "requested_by_customer",
    "reason_details": "Customer returned part of the order.",
    "reference": "return_1042",
    "total": { … },
    "status": "pending"
  }
}

POST/refunds/cancel

Cancel a refund

Stop a pending refund 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 processing, succeeded, or 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

Name
refund_id
Type
string
Required
required
Description
Refund to cancel, with the rf_ prefix.
request_metaobjectOptional body-level idempotency key. Prefer the Idempotency-Key header for new integrations.Click or tap to expand
- Name
  idempotency_key
  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 canceled status.

Request

POST/refunds/cancel

curl --fail-with-body https://api.inttegro.com/refunds/cancel \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cancel-refund-return-1042" \
  -d '{"refund_id":"rf_1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcd"}'

SDK versionv8.2.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({
  refundId: "rf_1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcd",
}, {
  idempotencyKey: "cancel-refund-return-1042",
})

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)

func main() {
  ctx := context.Background()
  client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))

  params := inttegro.CancelRefundRequest{
    RefundID: "rf_1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcd",
  }
  result, err := client.Refunds.Cancel(ctx, params)
  if err != nil {
    log.Fatal(err)
  }
  _ = result
}

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.refunds.cancel("rf_1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcd")

SDK versionv5.3.0

<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->refunds->cancel("rf_1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcd");

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.refunds.cancel(refund_id: "rf_1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcd")

SDK versionv5.2.0

import com.inttegro.Client;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var result = client.refunds().cancel("rf_1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcd");
  }
}

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.Refunds.CancelAsync("rf_1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcd");

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

Name
refund_id
Type
string
Required
required
Description
Refund to retrieve, with the rf_ prefix.

Response

Returns the requested refund.

Request

POST/refunds/lookup

: "${INTTEGRO_API_KEY:?INTTEGRO_API_KEY is required}"
: "${INTTEGRO_REFUND_ID:?INTTEGRO_REFUND_ID is required}"

curl --fail-with-body https://api.inttegro.com/refunds/lookup \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"refund_id\":\"$INTTEGRO_REFUND_ID\"}"

SDK versionv8.2.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",
})

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)

func main() {
  ctx := context.Background()
  client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))

  params := inttegro.LookupRefundRequest{
    RefundID: "$INTTEGRO_REFUND_ID",
  }
  result, err := client.Refunds.Lookup(ctx, params)
  if err != nil {
    log.Fatal(err)
  }
  _ = result
}

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.refunds.lookup("$INTTEGRO_REFUND_ID")

SDK versionv5.3.0

<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->refunds->lookup("$INTTEGRO_REFUND_ID");

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.refunds.lookup(refund_id: "$INTTEGRO_REFUND_ID")

SDK versionv5.2.0

import com.inttegro.Client;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var result = client.refunds().lookup("$INTTEGRO_REFUND_ID");
  }
}

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.Refunds.LookupAsync("$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. page_size defaults to 256, and the response's page.size is the number of refunds actually returned. An empty page is successful and contains size: 0 and refunds: [].

Request attributes

Name
page_number
Type
integer
Required
required
Description
Page to retrieve, from 1 through 10.
Name
page_size
Type
integer
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 refunds: [] and size: 0.

Request

POST/refunds/page

: "${INTTEGRO_API_KEY:?INTTEGRO_API_KEY is required}"

curl --fail-with-body https://api.inttegro.com/refunds/page \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page_number":1,"page_size":20}'

SDK versionv8.2.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,
})

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)

func main() {
  ctx := context.Background()
  client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))

  params := inttegro.PageRefundsRequest{
    PageNumber: 1,
    PageSize: 20,
  }
  result, err := client.Refunds.Page(ctx, params)
  if err != nil {
    log.Fatal(err)
  }
  _ = result
}

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.refunds.page(inttegro.refunds.PageRequest(
  page_number=1,
  page_size=20,
))

SDK versionv5.3.0

<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->refunds->page([
  'page_number' => 1,
  'page_size' => 20,
]);

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.refunds.page(
  page_number: 1,
  page_size: 20
)

SDK versionv5.2.0

import com.inttegro.Client;
import com.inttegro.refunds.RefundPageParams;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = RefundPageParams.builder()
      .pageNumber(1)
      .pageSize(20)
      .build();
    var result = client.refunds().page(params);
  }
}

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.Refunds.PageAsync(new Inttegro.PageRefundsRequest {
  PageNumber = 1,
  PageSize = 20,
});

Response

Object
JSON

SDK versionv8.2.0

PageResponse {
  page: { … },
}

SDK versionv8.2.0

{
  "page": {
    "number": 1,
    "refunds": [ … ],
    "size": 1
  }
}

Handling refund failures

Read error.code, fix_code, and detail to decide what to do next.

If an amount, currency, or line item is no longer valid, retrieve the order again and rebuild the refund from its current refundable amounts.
If the merchant balance cannot cover the refund or the original payment method is unavailable, resolve that condition before creating another refund.
If refundable capacity changed concurrently, retrieve the order and refund state before retrying.
Retry a transient failure only when fix_code recommends it. Keep the same endpoint, idempotency key, and request body.

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.

The refund object

Properties​

Create a refund

Request attributes​

Response​

Request

Response

Cancel a refund

Request attributes​

Response​

Request

Lookup a refund

Request attributes​

Response​

Request

List refunds

Request attributes​

Response​

Request

Response

Handling refund failures

Related resources

Properties

Request attributes

Response

Request attributes

Response

Request attributes

Response

Request attributes

Response