Skip to main content
Initiates a refund for a charge. Refunds are processed in the charge’s settlement currency. You can issue a full refund by omitting amount, or a partial refund by specifying an amount. All refund endpoints accept both API key authentication and user JWT authentication.

​
Create a refund

POST /api/v1/payments/refunds
Requires API key or user JWT authentication via the Authorization: Bearer header.
​
charge_id
string
required
The ID of the charge to refund.
​
reference
string
required
Your reference for this refund. Maximum 128 characters. Used for idempotency and tracking.
​
amount
number
Partial refund amount in the charge’s settlement currency, as a decimal. Omit to refund the full settled amount.
​
fee_bearer
string
Who bears the refund processing fee: ORG (your organization) or CUSTOMER. Defaults to your organization’s configured setting when omitted.
​
reason
string
Optional explanation for the refund. Maximum 500 characters.
​
refund_address
string
Destination wallet address for crypto refunds. Required for charges paid via cryptocurrency. Minimum 1 character, maximum 255 characters.
​
idempotency_key
string
Optional idempotency key to prevent duplicate refunds on retried requests. Maximum 255 characters.
​
simulated_outcome
string
Test mode only. Force a specific outcome: success or failed.
Response
​
refund_id
string
required
Unique identifier for the refund.
​
charge_id
string
required
The charge this refund is associated with.
​
reference
string
required
Your reference for the refund.
​
status
string
required
Current refund status. Common values: pending, processing, succeeded, failed.
​
requested_amount
string
required
The amount requested for refund, as a decimal string in the settlement currency.
​
refunded_amount
string
The amount actually refunded so far. null until the refund is processed.
​
refund_fee_amount
string
required
The processing fee charged for the refund, as a decimal string.
​
fee_bearer
string
required
Who bears the refund fee: ORG or CUSTOMER.
​
reason
string
The reason provided at refund creation, if any.
​
created_at
string
required
ISO 8601 creation timestamp.
​
updated_at
string
required
ISO 8601 last-updated timestamp.
​
completed_at
string
ISO 8601 timestamp when the refund reached a terminal status, or null if not yet complete.
{
  "refund_id": "ref_a1b2c3d4e5f6",
  "charge_id": "ch_a1b2c3d4e5f6",
  "reference": "refund_ord_12345",
  "status": "pending",
  "requested_amount": "50.00",
  "refunded_amount": null,
  "refund_fee_amount": "0.50",
  "fee_bearer": "ORG",
  "reason": "Customer request",
  "created_at": "2024-01-16T09:00:00Z",
  "updated_at": "2024-01-16T09:00:00Z",
  "completed_at": null
}

​
Get a refund

GET /api/v1/payments/refunds/{refund_id}
Requires API key or user JWT authentication. Path parameters
​
refund_id
string
required
The ID of the refund to retrieve.
Returns a RefundResponse object with the same fields as the create response.

​
Get refund by charge

GET /api/v1/payments/payins/{charge_id}/refund
Returns the refund associated with a specific charge ID. Useful when you have the charge ID but not the refund ID.
​
charge_id
string
required
The charge ID to look up the refund for.

​
List refunds

GET /api/v1/payments/refunds
Requires API key or user JWT authentication. Query parameters
​
limit
integer
default:"50"
Maximum number of results to return. Accepts 1–100.
​
offset
integer
default:"0"
Number of results to skip for pagination.
​
status
string
Filter results to a specific refund status (e.g., pending, succeeded, failed).
Response
​
total
integer
required
Total number of refunds matching the query (before pagination).
​
items
object[]
required
Array of refund objects. Each item has the same fields as a single refund response.
{
  "total": 3,
  "items": [
    {
      "refund_id": "ref_a1b2c3d4e5f6",
      "charge_id": "ch_a1b2c3d4e5f6",
      "reference": "refund_ord_12345",
      "status": "succeeded",
      "requested_amount": "50.00",
      "refunded_amount": "50.00",
      "refund_fee_amount": "0.50",
      "fee_bearer": "ORG",
      "reason": "Customer request",
      "created_at": "2024-01-16T09:00:00Z",
      "updated_at": "2024-01-16T09:05:00Z",
      "completed_at": "2024-01-16T09:05:00Z"
    }
  ]
}

​
Error codes

StatusDescription
400Invalid request, charge not refundable, or simulated_outcome used outside test mode.
401Invalid or missing API key or JWT.
403Charge belongs to a different organization.
404Charge or refund not found.

​
Example

Create a full refund 
curl --request POST \
  --url https://api.syncgrampay.com/api/v1/payments/refunds \
  --header 'Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8i9j0' \
  --header 'Content-Type: application/json' \
  --data '{
    "charge_id": "ch_a1b2c3d4e5f6",
    "reference": "refund_ord_12345",
    "reason": "Customer request"
  }'
Create a partial refund 
curl --request POST \
  --url https://api.syncgrampay.com/api/v1/payments/refunds \
  --header 'Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8i9j0' \
  --header 'Content-Type: application/json' \
  --data '{
    "charge_id": "ch_a1b2c3d4e5f6",
    "reference": "partial_refund_ord_12345",
    "amount": 25.00,
    "fee_bearer": "ORG",
    "reason": "Partial service refund"
  }'
Get a refund 
curl --request GET \
  --url https://api.syncgrampay.com/api/v1/payments/refunds/ref_a1b2c3d4e5f6 \
  --header 'Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8i9j0'