Payment Refund
Overview
The Payment Refund endpoint refunds a completed payment transaction. This is used when you need to return money for a payment that was already captured/collected. The refund will return the full amount back to the customer's card.
POST /v1/payments/{transactionId}/refund
What Happens Internally
Client Request → Firstoken API → [KOIN Refund] → Response
Validation: Verify the payment exists and is refundable
Refund Processing: Process the refund for the completed payment
Return Funds: Process refund back to customer's card
Response: Refund confirmation with transaction details
Request Body
{
"transaction_info": {
"type": "payment_refund",
"reference_code": "123456789"
},
"refund_info": {
"amount_details": {
"total_amount": 1000,
"currency": "BRL"
},
"installments": 1
},
"device_info": {
"ip_address": "12.7.8.120"
}
}
Field Specifications
URL Parameters
transactionId
String
Yes
Transaction ID from the original payment response
transaction_info (Required)
amount_details.total_amount
Number
Yes
Total amount for transaction
amount_details.currency
String
Yes
Currency code (BRL, USD, etc.)
installments
Number
Yes
Number of installments
refund_info (Required)
type
String
Yes
Must be "payment_void"
reference_code
String
Yes
Your reference for this void operation
device_info (Optional)
ip_address
String
No
Customer IP address (for fraud tracking)
Response Format
Success Response (200)
{
"status": "success",
"message": "Refund successful",
"data": {
"transaction_info": {
"type": "payment_refund_response",
"reference_code": "123456789",
"transaction_id": "0001753749137961743055",
"request_id": "7537491383836265204807",
"status": "Pending",
"reconciliation_id": "7537491301256093704806",
"created_at": "2025-07-29T00:32:18Z"
},
"order_info": {
"amount_details": {
"currency": "COP"
}
}
}
}
Error Response (400/500)
{
"status": "fail",
"message": "Invalid request",
"data": {
"code": 400,
"description": "Invalid transaction_id"
}
}
cURL Example
curl -X POST https://api.firstoken.co/v1/payments/0001750977715315130387/refund \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"transaction_info": {
"type": "payment_refund",
"reference_code": "refund_{{$guid}}"
},
"refund_info": {
"amount_details": {
"total_amount": 1000,
"currency": "BRL"
},
"installments": 1
},
"device_info": {
"ip_address": "12.7.8.120"
}
}'
Refund Status Values
Refunded
Payment successfully refunded
Pending
Refund request submitted, processing
Failed
Refund operation failed
Use Cases
When to Use Payment Refund
Customer Cancellation: Customer cancels order after payment
Merchant Error: Wrong amount charged or duplicate payment
Inventory Issues: Product not available after payment
Fraudulent Transaction: Suspected fraud detected after payment
System Error: Technical error resulted in incorrect charge
Refund Request: Customer requests immediate refund
Order Modification: Order cancelled and new one created
Void vs Refund
Timing
Before settlement
After settlement
Process
Cancels original transaction
Creates new refund transaction
Customer Statement
Original charge disappears
Shows original charge + refund
Processing Time
Immediate
3-5 business days typically
Fees
Usually no fees
May incur refund fees
Customer Experience
Processing Time: Refund typically takes 3-5 business days to appear
Statement: Customer sees original charge and separate refund entry
Notification: Customer should be notified of the refund processing
Last updated
Was this helpful?