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

1. Validation: Verify the payment exists and is refundable

2. Refund Processing: Process the refund for the completed payment

3. Return Funds: Process refund back to customer's card

4. 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",
      "fingerprint_session_id": "0a76c25669713d8d6d306ba8c21259b7",
  }
}

Field Specifications

URL Parameters

Parameter	Type	Required	Description
transactionId	String	Yes	Transaction ID from the original payment response

transaction_info (Required)

Field	Type	Required	Description
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)

Field	Type	Required	Description
type	String	Yes	Must be "payment_void"
reference_code	String	Yes	Your reference for this void operation

Device Info

Parameter	Type	Required	Description
ip_address	String	Yes	Customer's IP address
fingerprint_session_id*	String	Yes	A unique numerical ID generated for each user session on a website.

_{(*) The fingerprint_session_id is generated using a Koin script that is called from the webpage.}

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

Status	Description
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

Aspect	Payment Void	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