Refunds

A refund returns money to the payer against a payment that has already succeeded. This is different from a payout, which sends money to a recipient rather than reversing an existing payment.

Request

Send a POST request to /refunds. Only payment_id is required — omit amount for a full refund.

curl --request POST \
  --url https://api.sandbox.pesaswap.io/refunds \
  --header "api-key: {{api_key}}" \
  --header "Content-Type: application/json" \
  --data '{
    "payment_id": "{{payment_id}}",
    "amount": 100,
    "reason": "Customer cancelled the order"
  }'

const response = await fetch("https://api.sandbox.pesaswap.io/refunds", {
  method: "POST",
  headers: {
    "api-key": "{{api_key}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    payment_id: "{{payment_id}}",
    amount: 100,
    reason: "Customer cancelled the order",
  }),
});

const refund = await response.json();
console.log(refund);

import requests

response = requests.post(
    "https://api.sandbox.pesaswap.io/refunds",
    headers={
        "api-key": "{{api_key}}",
        "Content-Type": "application/json",
    },
    json={
        "payment_id": "{{payment_id}}",
        "amount": 100,
        "reason": "Customer cancelled the order",
    },
)

refund = response.json()
print(refund)

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.sandbox.pesaswap.io/refunds",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "api-key: {{api_key}}",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "payment_id" => "{{payment_id}}",
        "amount" => 100,
        "reason" => "Customer cancelled the order",
    ]),
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

Field	Required	Notes
`payment_id`	yes	The payment to refund
`amount`	no	Omit for a full refund. Pass a smaller value for a partial refund
`reason`	no	Free text, shown in the dashboard
`refund_type`	no	`instant` or `scheduled`
`refund_id`	no	Your own identifier, useful for idempotency
`metadata`	no	Arbitrary key/value data you want stored with the refund

Response

A successful call returns a 200 with a refund object. The fields that matter right now:

{
  "refund_id": "{{refund_id}}",
  "payment_id": "{{payment_id}}",
  "amount": 100,
  "status": "pending"
}

What to do next

A refund does not settle synchronously. Poll GET /refunds/{refund_id} until the status settles.

curl --request GET \
  --url "https://api.sandbox.pesaswap.io/refunds/{{refund_id}}" \
  --header "api-key: {{api_key}}"

const response = await fetch(
  `https://api.sandbox.pesaswap.io/refunds/${refundId}`,
  {
    method: "GET",
    headers: {
      "api-key": "{{api_key}}",
    },
  }
);

const refund = await response.json();
console.log(refund);

import requests

response = requests.get(
    f"https://api.sandbox.pesaswap.io/refunds/{refund_id}",
    headers={"api-key": "{{api_key}}"},
)

refund = response.json()
print(refund)

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.sandbox.pesaswap.io/refunds/{$refundId}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
        "api-key: {{api_key}}",
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

Status reference

Status	What it means	What to do
`pending`	Submitted, not yet settled.	Keep polling.
`succeeded`	The money has been returned.	Stop — settled.
`failed`	The connector rejected the refund.	Stop — failed.
`review`	Held for manual review.	Keep polling.

Common errors

Payment not in succeeded status

Refunding a payment that is not in succeeded status.

Amount exceeds captured total

Refunding more than the captured amount.

Mistaking pending for a failure

Assuming pending means the refund failed — it means it is still in progress.

Next steps

Payouts

Send money to a recipient instead of reversing a payment.

Quickstart

Create and confirm your first payment.

Mandates and recurring

Set up recurring charges against a stored mandate.

Wallet payments

M-Pesa, Airtel, and MTN MoMo payments.

About Pesaswap

Payments Guide

Account Setup

Use Cases

Explore Pesaswap

Checklist for Production

FAQ

Request

Response

What to do next

Status reference

Common errors

Next steps

Payouts

Quickstart

Mandates and recurring

Wallet payments

​Request

​Response

​What to do next

​Status reference

​Common errors

​Next steps

Payouts

Quickstart

Mandates and recurring

Wallet payments

Request

Response

What to do next

Status reference

Common errors

Next steps