Payout Details

Overview

Payout details store a vendor's bank account information for ACH payments. Each vendor can have at most one payout detail record. Payout details must be authorized before payouts can be processed.

How It Works

Create payout details — Add bank account information for a vendor
Authorize — Approve the payout details for use in payments
Process payouts — Once authorized, the vendor is payout-ready
Revoke if needed — Revoke authorization to pause payouts

Example: Add bank account details for "Content Provider Inc.", then authorize the payout details. Once is_payout_ready is true, the vendor can receive ACH payments through payment batches.

API Endpoints

Method	Endpoint	Description
`GET`	`/api/v1/core/vendors/{id}/payout-details`	List vendor payout details
`POST`	`/api/v1/core/vendors/payout-details`	Create payout detail
`GET`	`/api/v1/core/vendors/payout-details/{id}`	Get payout detail
`PUT`	`/api/v1/core/vendors/payout-details/{id}`	Update payout detail
`DELETE`	`/api/v1/core/vendors/payout-details/{id}`	Delete payout detail
`POST`	`/api/v1/core/vendors/payout-details/{id}/authorize`	Authorize payout detail
`POST`	`/api/v1/core/vendors/payout-details/{id}/revoke`	Revoke payout detail

Payout Detail Object

Attribute	Type	Description
`id`	integer	Payout detail ID
`vendor_id`	integer	Internal vendor record ID
`account_id`	integer	Account ID
`account_holder_name`	string	Name on the bank account
`bank_name`	string	Name of the bank
`routing_number`	string	Masked ABA routing number (`****` + last 4 digits)
`account_number`	string	Masked bank account number (`****` + last 4 digits)
`account_type`	string	`checking` or `savings`
`currency`	string	3-letter currency code (e.g. `usd`)
`country`	string	2-letter country code (e.g. `US`)
`payout_method_status`	string	`enabled` or `disabled`
`vendor_internal_identifier`	string	Internal identifier (format: `V` + zero-padded vendor ID)
`transaction_type`	string	Always `credit`
`authorization_status`	string	`pending`, `authorized`, or `revoked`
`authorization_timestamp`	integer	Unix timestamp of when authorization was granted
`authorization_method`	string	`written`, `electronic`, or `null`
`authorized_by`	integer	User ID of who authorized the payout detail
`is_payout_ready`	boolean	`true` when `payout_method_status` is `enabled` AND `authorization_status` is `authorized`
`created_at`	integer	Unix timestamp of creation
`updated_at`	integer	Unix timestamp of last update

Important Behaviors

One per vendor: Each vendor can have only one payout detail. Creating a second returns 409 Conflict.
Sensitive data is masked: Routing and account numbers are returned as **** + last 4 digits. Full numbers are never exposed in API responses.
ABA routing validation: Routing numbers must be exactly 9 digits and pass ABA checksum validation.
Authorization workflow: New payout details start with authorization_status: pending. They must be explicitly authorized before payouts can be processed.
Revoke preserves history: Revoking authorization sets status to revoked but preserves authorized_by and authorization_timestamp for audit trail.
Soft delete: Deleting a payout detail is a soft delete — the record is marked as deleted but retained in the database.
Audit logging: All create, update, delete, authorize, and revoke actions are recorded in the audit log.
Webhook events: Actions trigger webhook events: vendor_payout_detail.created, vendor_payout_detail.updated, vendor_payout_detail.deleted, vendor_payout_detail.authorized, vendor_payout_detail.revoked.