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"
  }
}

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 (Optional)

Field
Type
Required
Description

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

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

Last updated

Was this helpful?