Moneybag

Refunds API

Process full or partial refunds for completed transactions

Refunds API

Process refunds for completed transactions. Supports both full and partial refunds with configurable options.

Coming Soon

This API endpoint is currently under development. Documentation will be updated once the feature is available.


Overview

The Refunds API allows you to:

  • Process full refunds for transactions
  • Issue partial refunds
  • Track refund status
  • Handle refund webhooks
  • Query refund history

Create Refund

Initiate a refund for a completed transaction.

Endpoint

POST /api/v2/payments/refund

Request Headers

Content-Type: application/json
X-Merchant-API-Key: YOUR_API_KEY

Request Body

{
  "transaction_id": "TXN_1234567890",
  "refund_amount": 500.00,
  "refund_reason": "Customer request",
  "refund_type": "partial",
  "notify_customer": true,
  "metadata": {
    "order_id": "ORD_123",
    "refund_request_id": "REF_456"
  }
}

Parameters

ParameterTypeRequiredDescription
transaction_idstringYesOriginal transaction ID to refund
refund_amountdecimalNoAmount to refund (omit for full refund)
refund_reasonstringYesReason for the refund
refund_typestringNofull or partial (default: full)
notify_customerbooleanNoSend refund notification to customer
metadataobjectNoAdditional metadata for the refund

Response

Success Response (200 OK)

{
  "success": true,
  "data": {
    "refund_id": "REF_9876543210",
    "transaction_id": "TXN_1234567890",
    "refund_amount": 500.00,
    "refund_status": "processing",
    "estimated_completion": "2024-12-20T10:00:00Z",
    "created_at": "2024-12-18T15:30:00Z"
  }
}

Error Response (400 Bad Request)

{
  "success": false,
  "error": {
    "code": "REFUND_EXCEEDED",
    "message": "Refund amount exceeds original transaction amount"
  }
}

Get Refund Status

Check the status of a refund request.

Endpoint

GET /api/v2/payments/refund/{refund_id}

Request Headers

X-Merchant-API-Key: YOUR_API_KEY

Response

{
  "success": true,
  "data": {
    "refund_id": "REF_9876543210",
    "transaction_id": "TXN_1234567890",
    "refund_amount": 500.00,
    "refund_status": "completed",
    "completed_at": "2024-12-19T14:20:00Z",
    "created_at": "2024-12-18T15:30:00Z"
  }
}

Refund Status Values

StatusDescription
pendingRefund request received
processingRefund being processed
completedRefund successfully completed
failedRefund failed
cancelledRefund cancelled

List Refunds

Get a list of all refunds for your account.

Endpoint

GET /api/v2/payments/refunds

Query Parameters

ParameterTypeDescription
pageintegerPage number (default: 1)
limitintegerResults per page (default: 20, max: 100)
statusstringFilter by refund status
from_datestringStart date (YYYY-MM-DD)
to_datestringEnd date (YYYY-MM-DD)

Response

{
  "success": true,
  "data": {
    "refunds": [
      {
        "refund_id": "REF_9876543210",
        "transaction_id": "TXN_1234567890",
        "refund_amount": 500.00,
        "refund_status": "completed",
        "created_at": "2024-12-18T15:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "pages": 3
    }
  }
}

Cancel Refund

Cancel a pending refund request.

Endpoint

POST /api/v2/payments/refund/{refund_id}/cancel

Request Headers

X-Merchant-API-Key: YOUR_API_KEY

Response

{
  "success": true,
  "message": "Refund cancelled successfully",
  "data": {
    "refund_id": "REF_9876543210",
    "refund_status": "cancelled"
  }
}

Batch Refunds

Process multiple refunds in a single request.

Endpoint

POST /api/v2/payments/refunds/batch

Request Body

{
  "refunds": [
    {
      "transaction_id": "TXN_1234567890",
      "refund_amount": 500.00,
      "refund_reason": "Customer request"
    },
    {
      "transaction_id": "TXN_0987654321",
      "refund_amount": 300.00,
      "refund_reason": "Product defect"
    }
  ]
}

Response

{
  "success": true,
  "data": {
    "batch_id": "BATCH_123456",
    "total_refunds": 2,
    "successful": 2,
    "failed": 0,
    "refunds": [
      {
        "transaction_id": "TXN_1234567890",
        "refund_id": "REF_111",
        "status": "processing"
      },
      {
        "transaction_id": "TXN_0987654321",
        "refund_id": "REF_222",
        "status": "processing"
      }
    ]
  }
}

Refund Webhooks

Receive notifications about refund status changes.

Webhook Events

EventDescription
refund.initiatedRefund request created
refund.processingRefund being processed
refund.completedRefund successfully completed
refund.failedRefund failed
refund.cancelledRefund cancelled

Webhook Payload Example

{
  "event": "refund.completed",
  "timestamp": "2024-12-19T14:20:00Z",
  "data": {
    "refund_id": "REF_9876543210",
    "transaction_id": "TXN_1234567890",
    "refund_amount": 500.00,
    "refund_status": "completed",
    "original_amount": 1000.00,
    "remaining_amount": 500.00
  }
}

Testing Refunds

Sandbox Testing

Use these test scenarios in sandbox:

Transaction AmountRefund AmountResult
AnySame as transactionFull refund success
AnyLess than transactionPartial refund success
AnyMore than transactionError: exceeds limit
999.00AnyRefund fails

Test Card Behaviors

Different test cards produce different refund behaviors:

  • 4111111111111111: Instant refund
  • 5555555555554444: 24-hour refund delay
  • 378282246310005: Refund failure

Error Codes

CodeDescriptionSolution
REFUND_EXCEEDEDRefund amount exceeds transactionCheck refund amount
ALREADY_REFUNDEDTransaction already fully refundedVerify transaction status
REFUND_WINDOW_EXPIREDRefund period expired (180 days)Contact support for manual processing
INSUFFICIENT_BALANCEMerchant balance insufficientAdd funds to account
REFUND_NOT_ALLOWEDPayment method doesn't support refundsManual processing required

Best Practices

  1. Idempotency: Use idempotency keys to prevent duplicate refunds
  2. Validation: Verify refund amount before processing
  3. Webhooks: Implement webhook handlers for refund status
  4. Monitoring: Track refund rates and patterns
  5. Customer Communication: Notify customers of refund status

FAQ

Q: How long do refunds take? A: Typically 5-7 business days depending on payment method.

Q: Can I refund more than the original amount? A: No, refunds cannot exceed the original transaction amount.

Q: Is there a time limit for refunds? A: Refunds can be processed within 180 days of the original transaction.

Q: Can I cancel a refund? A: Only pending refunds can be cancelled. Once processing, they cannot be stopped.