Skip to content

Refunds API

🤖 Explain with AI

The Refunds API allows you to create and manage refunds for previously processed payments.

Base URL

https://api.4geeks.io

Authentication

All endpoints require the X-Api-Key header:

X-Api-Key: sk_test_your_api_key_here

See Authentication for details.

Create Refund

Creates a refund for a payment.

POST /v1/refunds

Request Body

Field Type Required Description
payment_id string Yes Internal payment ID to refund
amount integer No Amount to refund in cents. If omitted, a full refund is processed
reason string No Reason for the refund

Request Example

curl -X POST 'https://api.4geeks.io/v1/refunds' \
  -H 'X-Api-Key: sk_test_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "payment_id": "pay_7g8h9i0j1k2l",
    "amount": 2500,
    "reason": "Customer requested partial refund"
  }'

import requests

response = requests.post(
    'https://api.4geeks.io/v1/refunds',
    headers={'X-Api-Key': 'sk_test_your_api_key_here'},
    json={
        'payment_id': 'pay_7g8h9i0j1k2l',
        'amount': 2500,
        'reason': 'Customer requested partial refund'
    }
)
print(response.json())

const response = await fetch('https://api.4geeks.io/v1/refunds', {
    method: 'POST',
    headers: {
        'X-Api-Key': 'sk_test_your_api_key_here',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        payment_id: 'pay_7g8h9i0j1k2l',
        amount: 2500,
        reason: 'Customer requested partial refund'
    })
});
const data = await response.json();
console.log(data);

Response (200 OK)

Field Type Description
id string Refund ID
object string Object type (default: “refund”)
payment_id string Associated payment ID
amount integer Refunded amount in cents
status string Refund status

Response Example

{
    "id": "ref_m3n4o5p6q7r8",
    "object": "refund",
    "payment_id": "pay_7g8h9i0j1k2l",
    "amount": 2500,
    "status": "pending"
}

List Refunds

Lists refunds with pagination.

GET /v1/refunds

Query Parameters

Parameter Type Required Default Description
limit integer No 10 Number of results per page
offset integer No 0 Number of results to skip

Request Example

curl -X GET 'https://api.4geeks.io/v1/refunds?limit=5&offset=0' \
  -H 'X-Api-Key: sk_test_your_api_key_here'

import requests

response = requests.get(
    'https://api.4geeks.io/v1/refunds',
    headers={'X-Api-Key': 'sk_test_your_api_key_here'},
    params={'limit': 5, 'offset': 0}
)
print(response.json())

const response = await fetch('https://api.4geeks.io/v1/refunds?limit=5&offset=0', {
    headers: {'X-Api-Key': 'sk_test_your_api_key_here'}
});
const data = await response.json();
console.log(data);

Response (200 OK)

Field Type Description
items array[RefundResponse] Array of refund objects
total_items integer Total number of refunds
limit integer Requested page size
offset integer Requested offset

Response Example

{
    "items": [
        {
            "id": "ref_m3n4o5p6q7r8",
            "object": "refund",
            "payment_id": "pay_7g8h9i0j1k2l",
            "amount": 2500,
            "status": "pending"
        },
        {
            "id": "ref_s9t0u1v2w3x4",
            "object": "refund",
            "payment_id": "pay_y5z6a7b8c9d0",
            "amount": 4999,
            "status": "succeeded"
        }
    ],
    "total_items": 2,
    "limit": 5,
    "offset": 0
}

Error Response (422 Validation Error)

All endpoints may return a 422 status when validation fails.

{
    "detail": [
        {
            "loc": ["body", "payment_id"],
            "msg": "field required",
            "type": "value_error.missing"
        }
    ]
}

Still questions? Ask the community or explore tutorials