> ## Documentation Index > Fetch the complete documentation index at: https://docs.thredfi.com/llms.txt > Use this file to discover all available pages before exploring further. # 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-Key` header **Allocation Types:** - `bill`: Apply refund to a specific bill - `payment`: Refund a specific bill payment - `credit`: 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:** ```json { "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" } ] } ``` ## OpenAPI ````yaml POST /v1/platform/businesses/{business_id}/vendor-refunds/payments/ openapi: 3.0.3 info: title: Thredfi Accounting Platform API version: 1.0.0 description: >- Comprehensive API for accounting, invoice management, open banking, and intelligence services. servers: [] security: [] paths: /v1/platform/businesses/{business_id}/vendor-refunds/payments/: post: tags: - Vendor Refund Payments summary: Create vendor refund payment with allocations description: |2- 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-Key` header **Allocation Types:** - `bill`: Apply refund to a specific bill - `payment`: Refund a specific bill payment - `credit`: 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:** ```json { "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" } ] } ``` operationId: create_vendor_refund_payment_allocation parameters: - in: header name: Idempotency-Key schema: type: string description: Unique key for idempotent request processing - in: path name: business_id schema: type: string format: uuid description: Business UUID required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/VendorRefundPaymentCreateRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/VendorRefundPaymentCreateRequest' multipart/form-data: schema: $ref: '#/components/schemas/VendorRefundPaymentCreateRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/VendorRefundPaymentCreateResponse' description: '' '400': content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' description: Validation errors in request data '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication required - missing or invalid API key '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Permission denied - insufficient privileges '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Resource not found '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Conflict - resource already exists or invalid state transition '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unprocessable entity - business logic validation failed '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal server error security: - BusinessScopedJWT: [] - PartnerJWT: [] - BasicAuth: [] - BearerUnscoped: [] - BearerBusinessScoped: [] components: schemas: VendorRefundPaymentCreateRequest: type: object description: >- 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. properties: vendor_id: type: string format: uuid description: UUID of the vendor issuing the refund total_amount_cents: type: integer minimum: 1 description: Total refund amount in cents (e.g., 100000 for £1000.00) allocations: type: array items: $ref: '#/components/schemas/VendorRefundAllocationItemRequest' description: List of allocations for the refund external_id: type: string description: External system ID for idempotency maxLength: 255 refund_type: enum: - overpayment - billing_error - goods_return - credit_balance - duplicate_payment - other type: string x-spec-enum-id: 38f88e0c97de179b default: overpayment description: |- Type of refund * `overpayment` - Overpayment * `billing_error` - Billing Error * `goods_return` - Goods Return * `credit_balance` - Credit Balance * `duplicate_payment` - Duplicate Payment * `other` - Other refund_date: type: string format: date description: Date of the refund (defaults to today) currency: type: string minLength: 1 description: Currency code (defaults to vendor's currency) maxLength: 3 description: type: string description: Refund description memo: type: string description: Internal memo reason: type: string description: Reason for the refund maxLength: 500 metadata: nullable: true description: Additional structured data payment_method: enum: - bank_transfer - ach - wire - check - credit_card - cash - other type: string x-spec-enum-id: 1cd9444edaf0ad8b default: bank_transfer description: |- Payment method used for the refund * `bank_transfer` - Bank Transfer * `ach` - ACH Transfer * `wire` - Wire Transfer * `check` - Check * `credit_card` - Credit Card Reversal * `cash` - Cash * `other` - Other processor: enum: - stripe - wise - paypal - bank_transfer - internal type: string x-spec-enum-id: c841362fdd1cad7c default: bank_transfer description: |- Payment processor used * `stripe` - Stripe * `wise` - Wise (TransferWise) * `paypal` - PayPal * `bank_transfer` - Direct Bank Transfer * `internal` - Internal Processing payment_reference: type: string description: External payment reference number maxLength: 100 processing_fee_cents: type: integer minimum: 0 default: 0 description: Processing fee in cents required: - total_amount_cents - vendor_id VendorRefundPaymentCreateResponse: type: object description: |- 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. properties: refund: type: object additionalProperties: {} description: Complete refund information payment: type: object additionalProperties: {} nullable: true description: Payment information allocations: type: array items: type: object additionalProperties: {} description: List of allocations created required: - allocations - payment - refund ValidationErrorResponse: type: object description: Validation error response with field-specific errors properties: error_code: type: string description: Error code (e.g., 'validation_error') message: type: string nullable: true description: Human-readable error message detail: type: object additionalProperties: {} description: Contains field_errors and additional context request_id: type: string description: Request ID for tracing required: - detail - error_code - message ErrorResponse: type: object description: Standard error response format properties: error_code: type: string description: Error code for programmatic handling message: type: string nullable: true description: Human-readable error message detail: type: object additionalProperties: {} description: Additional error details including field_errors and debug info request_id: type: string description: Request ID for tracing required: - error_code - message VendorRefundAllocationItemRequest: type: object description: >- Serializer for individual allocation items in vendor refund payment creation. This serializer handles the validation and conversion of allocation data for bills, payments, or credit allocations. properties: allocation_type: enum: - bill - payment - credit type: string x-spec-enum-id: 22d8aab8e694331c description: >- Type of allocation: 'bill' (apply to bill), 'payment' (refund payment), or 'credit' (credit balance) * `bill` - bill * `payment` - payment * `credit` - credit amount_cents: type: integer minimum: 1 description: Allocation amount in cents (e.g., 50000 for £500.00) bill_id: type: string format: uuid nullable: true description: Bill ID (required for 'bill' allocation type) bill_payment_id: type: string format: uuid nullable: true description: Bill payment ID (required for 'payment' allocation type) description: type: string description: Description of the allocation maxLength: 500 metadata: nullable: true description: Additional metadata for the allocation required: - allocation_type - amount_cents securitySchemes: BusinessScopedJWT: type: http scheme: bearer bearerFormat: JWT description: >- Business-scoped JWT token. Token payload includes `business_id` to automatically scope requests. Format: `Bearer ` **Use this for**: Business-specific operations where the business context is embedded in the token. PartnerJWT: type: http scheme: bearer bearerFormat: JWT description: >- Partner-level JWT token (unscoped). Token payload includes `partner_id`. Business access is validated via partner ownership. Format: `Bearer ` **Use this for**: Multi-business operations where the business_id is specified in the URL and partner has access to multiple businesses. BasicAuth: type: http scheme: basic description: >- Basic authentication for OAuth2 token endpoint. Use partner_uuid:api_key as username:password. Example: Authorization: Basic base64(partner_uuid:api_key) BearerUnscoped: type: http scheme: bearer bearerFormat: JWT description: >- Partner (unscoped) JWT Bearer token. Obtain via POST /v1/platform/oauth2/token with Basic auth (partner_uuid:api_key). Use header: Authorization: Bearer {access_token} BearerBusinessScoped: type: http scheme: bearer bearerFormat: JWT description: >- Business-scoped JWT Bearer token. Obtain via POST /v1/platform/{business_id}/oauth2/token/ using a partner Bearer token. Only valid for endpoints whose URL contains that business_id. ````