Refunds

A Refund represents a reversal of a previously captured payment.

POST/v1/refunds

Create a new refund

Create a Refund

Creates a refund for a captured payment.

Request Body

Parameter	Type	Required	Description
payment_id	string	✓	ID of the payment to refund
amount	integer		Amount to refund in cents (default: full amount)
reason	string		Reason for refund: duplicate, fraudulent, requested_by_customer
metadata	object		Custom key-value pairs

Example Request

cURL

curl https://api.salamgateway.com/v1/refunds \
  -X POST \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "pay_abc123",
    "amount": 10000,
    "reason": "requested_by_customer"
  }'

Node.js

const refund = await salam.refunds.create({
  payment_id: 'pay_abc123',
  amount: 10000,
  reason: 'requested_by_customer',
});

Response

{
  "id": "rfnd_xyz789",
  "object": "refund",
  "payment_id": "pay_abc123",
  "amount": 10000,
  "currency": "MYR",
  "reason": "requested_by_customer",
  "status": "pending",
  "metadata": {},
  "created_at": "2024-01-15T12:00:00Z"
}

---

GET/v1/refunds/:id

Retrieve a refund

Retrieve a Refund

Retrieves the details of an existing refund.

Path Parameters

Parameter	Description
id	The refund ID

Example

cURL

curl https://api.salamgateway.com/v1/refunds/rfnd_xyz789 \
  -H "Authorization: Bearer sk_live_xxx"

Node.js

const refund = await salam.refunds.retrieve('rfnd_xyz789');

---

GET/v1/refunds

List all refunds

List Refunds

Returns a paginated list of refunds.

Query Parameters

Parameter	Description
payment_id	Filter by payment ID
status	Filter by status: pending, succeeded, failed
page	Page number (default: 1)
limit	Items per page (default: 20, max: 100)

Example

cURL

curl "https://api.salamgateway.com/v1/refunds?status=succeeded" \
  -H "Authorization: Bearer sk_live_xxx"

Node.js

const refunds = await salam.refunds.list({
  status: 'succeeded',
});

Refund Object

Attributes

Attribute	Type	Description
id	string	Unique refund identifier
object	string	Always "refund"
payment_id	string	ID of the payment being refunded
amount	integer	Amount refunded in cents
currency	string	Three-letter ISO currency code
reason	string	Reason for the refund
status	string	Refund status
metadata	object	Custom metadata
created_at	string	Creation timestamp

Refund Status

Status	Description
pending	Refund initiated, processing
succeeded	Refund completed successfully
failed	Refund failed

Refund Processing Time

FPX refunds typically take 3-5 business days to appear in the customer's bank account.