Create vendor refund payment with allocations
Create a vendor refund payment with embedded allocations in a single atomic operation.
This endpoint follows the same pattern as invoice payments, where allocations are embedded in the payment creation request rather than being separate API calls.
Key Features:
- Atomic operation - all or nothing
- Comprehensive validation
- Support for multiple allocation types
- Idempotency support via
Idempotency-Keyheader
Allocation Types:
bill: Apply refund to a specific billpayment: Refund a specific bill paymentcredit: Create a credit balance for future use
Idempotency:
Include an Idempotency-Key header to ensure the same request isn’t processed twice.
If the same key is used again, the original response will be returned.
Example Request:
{
"vendor_id": "uuid",
"total_amount_cents": 100000,
"payment_method": "bank_transfer",
"refund_date": "2025-01-15",
"allocations": [
{
"allocation_type": "bill",
"bill_id": "uuid",
"amount_cents": 60000,
"description": "Partial refund for Bill #123"
},
{
"allocation_type": "credit",
"amount_cents": 40000,
"description": "Credit for future purchases"
}
]
}
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.
Headers
Unique key for idempotent request processing
Path Parameters
Business UUID
Body
Serializer for creating vendor refund payments with embedded allocations.
This serializer handles the unified creation of vendor refunds, payments, and allocations in a single atomic operation.
UUID of the vendor issuing the refund
Total refund amount in cents (e.g., 100000 for £1000.00)
x >= 1List of allocations for the refund
External system ID for idempotency
255Type of refund
overpayment- Overpaymentbilling_error- Billing Errorgoods_return- Goods Returncredit_balance- Credit Balanceduplicate_payment- Duplicate Paymentother- Other
overpayment, billing_error, goods_return, credit_balance, duplicate_payment, other Date of the refund (defaults to today)
Currency code (defaults to vendor's currency)
1 - 3Refund description
Internal memo
Reason for the refund
500Additional structured data
Payment method used for the refund
bank_transfer- Bank Transferach- ACH Transferwire- Wire Transfercheck- Checkcredit_card- Credit Card Reversalcash- Cashother- Other
bank_transfer, ach, wire, check, credit_card, cash, other Payment processor used
stripe- Stripewise- Wise (TransferWise)paypal- PayPalbank_transfer- Direct Bank Transferinternal- Internal Processing
stripe, wise, paypal, bank_transfer, internal External payment reference number
100Processing fee in cents
x >= 0Response
Serializer for vendor refund payment create/update responses.
This serializer formats the response data for successful refund payment creation operations. Renamed from VendorRefundPaymentResponseSerializer to avoid naming conflict with vendor_refund_serializers.py.