POST
/v1/refundsInitiate Refund
Merchant sends a payment ID and amount to return money to a customer. Refunds can be full or partial, depending on your business needs.
Overview
Create a refund for a completed payment. You can refund the full amount or a partial amount. Refunds are processed asynchronously and you'll receive a webhook notification when the refund is completed.
Important Notes:
- Refunds can only be issued for succeeded payments
- Partial refunds are allowed, but total refunds cannot exceed the original payment amount
- Refunds typically take 3-5 business days to appear in the customer's account
- Always include an idempotency_key to prevent duplicate refunds
Request
Request Body
Required and optional fields
payment_idrequired
The ID of the payment to refund
amountrequired
Refund amount in smallest currency unit. Must be less than or equal to the original payment amount
reasonoptional
Reason for the refund (for your records)
Code Examples
curl -X POST "https://api.altafinex.com/v1/refunds" \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"payment_id": "pay_1234567890abcdef",
"amount": 5000,
"reason": "Customer requested refund",
"idempotency_key": "refund-key-12345"
}'Response
Status Codes
200
Refund created successfully400
Invalid request data401
Authentication failed404
Payment not found409
Duplicate refund request422
Refund not allowed or amount exceeds paymentSuccess Response
Example response for a successful request
{
"refund_id": "ref_1234567890abcdef",
"payment_id": "pay_1234567890abcdef",
"status": "pending",
"amount": 5000,
"currency": "THB",
"reason": "Customer requested refund",
"created_at": "2024-01-15T11:00:00Z"
}Error Response
Example response for an error
{
"error": {
"code": "refund_not_allowed",
"message": "This payment cannot be refunded",
"type": "refund_error"
}
}