Create vendor refund
Create a new vendor refund record (parent transaction).
Idempotency: Uses external_id field - duplicate requests with the same
external_id will return HTTP 200 with the existing refund instead of creating
a duplicate.
Required Fields:
vendor_id: UUID of the vendor issuing the refundtotal_refunded_amount_cents: Total amount being refunded in cents (e.g., 10050 for £100.50)currency: ISO 4217 currency code (EUR, GBP, USD)
Optional Fields:
external_id: Your system’s unique identifier (for idempotency)reference_number: External reference numberrefund_type: Type of refund (overpayment, billing_error, goods_return, etc.)refund_date: Date of refund (defaults to today)description: Detailed descriptionmemo: Internal memo/notesreason: Reason for the refundmetadata: Additional structured data (JSON object)allocations: Array of allocations to create with the refundpayments: Array of payments to create with the refunddocument: Optional document upload (multipart fieldfilewith optional document_type, upload_source, metadata, tags)
Common Scenarios:
-
Overpayment refund - Vendor returns excess payment
{ "vendor_id": "uuid", "total_refunded_amount_cents": 15000, "currency": "GBP", "refund_type": "overpayment", "description": "Refund of overpayment" } -
Billing error - Vendor refunds due to billing mistake
{ "vendor_id": "uuid", "total_refunded_amount_cents": 50000, "currency": "GBP", "refund_type": "billing_error", "reference_number": "REF-12345", "allocations": [{ "allocation_type": "bill", "bill_id": "bill-uuid", "amount_cents": 50000 }] } -
Complete refund with payment - Create refund with allocation and payment in one request
{ "vendor_id": "uuid", "total_refunded_amount_cents": 100000, "currency": "GBP", "external_id": "my-refund-123", "allocations": [{ "allocation_type": "bill", "bill_id": "bill-uuid", "amount_cents": 100000 }], "payments": [{ "refunded_amount_cents": 100000, "payment_method": "bank_transfer", "processor": "wise" }] }
Returns:
- HTTP 201: Refund created successfully
- HTTP 200: Existing refund (idempotent - same external_id)
- HTTP 400: Validation error
Authorizations
Business-scoped JWT token. Token payload includes business_id to automatically scope requests. Format: Bearer <your-jwt-token>
Use this for: Business-specific operations where the business context is embedded in the token.
Path Parameters
Body
Serializer for creating vendor refunds. Handles validation and conversion of amounts from base units to cents.
Vendor UUID
Total refunded amount in cents (e.g., 10050 for €100.50)
x >= 1External/partner refund ID for idempotency
255Type/reason for the refund
overpayment- overpaymentcredit_balance- credit_balanceduplicate_payment- duplicate_paymentbilling_error- billing_errorgoods_return- goods_returnservice_cancellation- service_cancellationother- other
overpayment, credit_balance, duplicate_payment, billing_error, goods_return, service_cancellation, other External reference number
100ISO 4217 currency code
EUR- EURGBP- GBPUSD- USD
EUR, GBP, USD Date when refund was issued (ISO date: YYYY-MM-DD)
Description of the refund reason or context
Internal memo or notes about this refund
Detailed explanation for the refund (max 500 characters)
500Custom key-value pairs for additional refund context (max 10kb)
Optional document upload
Response
Comprehensive serializer for vendor refund responses. Includes all refund details plus related allocations and payments.
Unique vendor refund identifier
UUID of the vendor who issued the refund
Vendor company name
Total refunded amount in cents
Total allocated amount in cents
Remaining unallocated amount in cents
Latest document linked to this vendor refund
Refund creation timestamp
Last update timestamp
Your external system identifier for idempotency
255Refund type: overpayment, credit_balance, billing_error, goods_return, duplicate_payment, service_cancellation, other
overpayment- Overpayment Refundcredit_balance- Credit Balance Refundduplicate_payment- Duplicate Paymentbilling_error- Billing Errorgoods_return- Goods Returnservice_cancellation- Service Cancellationother- Other
overpayment, credit_balance, duplicate_payment, billing_error, goods_return, service_cancellation, other External reference number for this refund
100Date when refund was issued
Expected date for refund completion
Refund currency (EUR, GBP, USD)
EUR- EuroGBP- British PoundUSD- US DollarSEK- Swedish KronaNOK- Norwegian KroneDKK- Danish KroneISK- Icelandic KrónaMYR- Malaysian RinggitSGD- Singapore Dollar
EUR, GBP, USD, SEK, NOK, DKK, ISK, MYR, SGD Refund status: pending, partially_allocated, allocated, completed, cancelled (computed from allocations)
pending- Pendingpartially_allocated- Partially Allocatedallocated- Allocatedcompleted- Completedcancelled- Cancelled
pending, partially_allocated, allocated, completed, cancelled Description of the refund reason or context
Internal memo or notes
Detailed explanation for the refund
500Custom key-value pairs