Refunds

Process refunds for completed payments. The payment gateway supports refunds via cryptocurrency (blockchain address) or bank transfer.

Refund Flow

sequenceDiagram
    participant M as Merchant
    participant API as Payment Gateway API
    participant A as Admin
    participant C as Customer

    M->>API: Create Refund Request
    API->>API: Validate (payment must have refund=true)
    API->>A: Refund Request (PENDING)
    A->>API: Approve Refund
    API->>C: Process Refund
    API->>M: Webhook: payment.refund

Creating a Refund Request

POST /api/refund-request
Authorization: Bearer YOUR_OAUTH_TOKEN
Content-Type: application/json

Crypto Refund

Refund to a blockchain address:

{
  "paymentId": "550e8400-e29b-41d4-a716-446655440000",
  "blockchainAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
}

Bank Refund

Refund to a bank account:

{
  "paymentId": "550e8400-e29b-41d4-a716-446655440000",
  "bankName": "Deutsche Bank",
  "bankCode": "DEUTDEFF",
  "bankAccountNumber": "DE89370400440532013000",
  "bankAccountHolder": "John Doe"
}

Parameters

ParameterTypeRequiredDescription
paymentIdstringYesUUID of the payment to refund
blockchainAddressstringConditionalRefund destination blockchain address
bankNamestringConditionalBank name for bank refund
bankCodestringConditionalBank code / SWIFT / BIC
bankAccountNumberstringConditionalBank account number / IBAN
bankAccountHolderstringConditionalAccount holder name

Provide either blockchainAddress for crypto refund or all bank fields for bank refund.

Prerequisites

  • The payment must exist and have refund = true
  • No other refund request must exist for this payment

Response

{
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "paymentId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "PENDING",
    "refundAmount": {
      "value": 100.00,
      "amount": 10000,
      "formatted": "$100.00"
    },
    "blockchainAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "refundedAt": null,
    "createdAt": "2026-01-15T12:00:00Z",
    "updatedAt": "2026-01-15T12:00:00Z"
  }
}

Refund Status

StatusDescription
PENDINGRefund request created, awaiting approval
APPROVEDRefund approved and being processed
CANCELLEDRefund request rejected

Get Refund Request

GET /api/refund-request/{id}
Authorization: Bearer YOUR_OAUTH_TOKEN

Refund Webhook

When a refund is completed, a payment.refund webhook event is sent:

{
  "payment": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "REFUND",
    "refund": true,
    "refundedAmount": {
      "value": 100.00,
      "amount": 10000,
      "formatted": "$100.00"
    }
  }
}

Best Practices

  1. Verify payment status before requesting a refund
  2. Store refund references for reconciliation
  3. Handle webhook events for refund status updates
  4. Log all refund attempts for audit trails

Next Steps