Skip to main content
You can refund a charge after it has been successfully completed. Refunds are issued in the charge’s settlement currency — the currency that was credited to your balance — not the currency the customer originally paid in.

​
Refundability

Not every charge can be refunded. Check the is_refundable field on a charge before attempting a refund. A charge is refundable when:
  • Its status is SUCCEEDED or ACCEPTED, and
  • The payment method supports refunds.
Retrieve a charge with GET /api/v1/payments/payins/{charge_id} and check is_refundable before initiating a refund.

​
Issue a refund

curl -X POST https://api.syncgrampay.com/api/v1/payments/refunds \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "charge_id": "chr_01j9abc123",
    "reference": "refund_ord_12345",
    "reason": "Customer requested cancellation"
  }'
Endpoint: POST /api/v1/payments/refunds
Authentication: API key or dashboard session

​
Request body

​
charge_id
string
required
The ID of the charge to refund.
​
reference
string
required
Your reference for this refund. Maximum 128 characters. Used to identify the refund in your system and for idempotency.
​
amount
number
Partial refund amount in the charge’s settlement currency. Omit to issue a full refund.
​
reason
string
Description of why the refund is being issued. Maximum 500 characters. Displayed in your dashboard.
​
fee_bearer
string
Who bears the refund processing fee. Accepted values: ORG, CUSTOMER. Defaults to your organization’s configured fee handling.
​
refund_address
string
Destination wallet address for crypto refunds. Required when refunding a crypto charge. Maximum 255 characters.
​
idempotency_key
string
Optional key to prevent duplicate refunds on retry. Maximum 255 characters. If you submit the same idempotency_key twice, the second request returns the original refund.
​
simulated_outcome
string
Test mode only. Forces a specific refund outcome. Accepted values: success, failed.

​
Response

{
  "refund_id": "ref_01j9ghi789",
  "charge_id": "chr_01j9abc123",
  "reference": "refund_ord_12345",
  "status": "PENDING",
  "requested_amount": "50.00",
  "refunded_amount": null,
  "refund_fee_amount": "0.50",
  "fee_bearer": "ORG",
  "reason": "Customer requested cancellation",
  "created_at": "2025-01-15T12:00:00Z",
  "updated_at": "2025-01-15T12:00:00Z",
  "completed_at": null
}
​
refund_id
string
Unique identifier for the refund.
​
charge_id
string
The charge this refund is associated with.
​
reference
string
Your reference from the request.
​
status
string
Current refund status. Starts as PENDING. Transitions to SUCCEEDED when the refund is processed, or FAILED if it cannot be completed.
​
requested_amount
string
The amount requested for refund in the settlement currency.
​
refunded_amount
string
The amount actually refunded. May differ from requested_amount if fees were deducted. Null while the refund is still pending.
​
refund_fee_amount
string
The processing fee applied to this refund.
​
fee_bearer
string
Who bears the refund fee: ORG or CUSTOMER.
​
completed_at
string
ISO 8601 datetime when the refund completed. Null until the refund reaches a terminal status.

​
Get a refund

Retrieve a refund by its ID. 
curl https://api.syncgrampay.com/api/v1/payments/refunds/ref_01j9ghi789 \
  -H "Authorization: Bearer sk_live_..."
Endpoint: GET /api/v1/payments/refunds/{refund_id}

​
Get a refund by charge

Look up the refund associated with a specific charge. 
curl https://api.syncgrampay.com/api/v1/payments/payins/chr_01j9abc123/refund \
  -H "Authorization: Bearer sk_live_..."
Endpoint: GET /api/v1/payments/payins/{charge_id}/refund

​
List refunds

Retrieve a paginated list of all refunds for your organization. 
curl "https://api.syncgrampay.com/api/v1/payments/refunds?limit=20&offset=0" \
  -H "Authorization: Bearer sk_live_..."
Endpoint: GET /api/v1/payments/refunds

​
Query parameters

​
limit
integer
default:"50"
Number of refunds to return. Range: 1–100.
​
offset
integer
default:"0"
Number of refunds to skip for pagination.
​
status
string
Filter by refund status: PENDING, SUCCEEDED, or FAILED.

​
Response

{
  "total": 12,
  "items": [
    {
      "refund_id": "ref_01j9ghi789",
      "charge_id": "chr_01j9abc123",
      "reference": "refund_ord_12345",
      "status": "SUCCEEDED",
      "requested_amount": "50.00",
      "refunded_amount": "49.50",
      "refund_fee_amount": "0.50",
      "fee_bearer": "ORG",
      "reason": "Customer requested cancellation",
      "created_at": "2025-01-15T12:00:00Z",
      "updated_at": "2025-01-15T12:08:33Z",
      "completed_at": "2025-01-15T12:08:33Z"
    }
  ]
}

​
Error cases

ScenarioHTTP statusError
Charge ID not found404Charge not found
Charge is not refundable400Charge status is not eligible for refund
Duplicate reference or idempotency_keyReturns the original refund—
Invalid partial amount400Amount must be greater than 0
Refunds cannot be cancelled once submitted. Verify the charge ID and amount before issuing a refund.