> ## Documentation Index > Fetch the complete documentation index at: https://docs.useaxra.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a draft batch payout (payroll) + preview > Validates up to BATCH_MAX_ITEMS line items, resolves each recipient (saved or inline — inline ones are sanctions-screened and saved), server-side quotes every item, and persists a DRAFT batch with child payouts in CREATED (not yet dispatched). Returns the per-item fee breakdown, summed totals, and an affordability flag. Idempotent on (business, idempotencyKey). ## OpenAPI ````yaml /openapi.json post /api/v1/business/payouts/batches openapi: 3.0.0 info: title: Axra Public API description: Merchant and third-party developer API surface version: '2026-04-15' contact: {} servers: - url: http://localhost:3001 description: Local development - url: https://staging-api.useaxra.com description: Staging - url: https://api.useaxra.com description: Production security: [] tags: [] paths: /api/v1/business/payouts/batches: post: tags: - Business Payout Batches summary: Create a draft batch payout (payroll) + preview description: >- Validates up to BATCH_MAX_ITEMS line items, resolves each recipient (saved or inline — inline ones are sanctions-screened and saved), server-side quotes every item, and persists a DRAFT batch with child payouts in CREATED (not yet dispatched). Returns the per-item fee breakdown, summed totals, and an affordability flag. Idempotent on (business, idempotencyKey). operationId: BatchPayoutsController_create parameters: - name: X-Axra-Business-Id in: header description: Active business context required: false schema: type: string - name: x-api-key in: header description: Merchant API key (alternative to dashboard JWT) required: false schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateBatchDto' responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: '#/components/schemas/BatchPreviewResponseDto' required: - success - data '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/HttpErrorEnvelopeDto' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/HttpErrorEnvelopeDto' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/HttpErrorEnvelopeDto' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/HttpErrorEnvelopeDto' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/HttpErrorEnvelopeDto' '422': description: Unprocessable content: application/json: schema: $ref: '#/components/schemas/HttpErrorEnvelopeDto' '429': description: Too many requests content: application/json: schema: $ref: '#/components/schemas/HttpErrorEnvelopeDto' '500': description: Server error content: application/json: schema: $ref: '#/components/schemas/HttpErrorEnvelopeDto' security: - bearer: [] components: schemas: CreateBatchDto: type: object properties: idempotencyKey: type: string minLength: 8 maxLength: 64 description: >- Idempotency key — unique per (business, key). A replay returns the same batch. source: type: string enum: - MANUAL - CSV - API - SCHEDULE - CHANNEL default: MANUAL description: How the batch was authored. Defaults to MANUAL. items: description: Line items (one per recipient). type: array items: $ref: '#/components/schemas/CreateBatchItemDto' metadata: type: object description: Optional caller metadata persisted on the batch. required: - idempotencyKey - items BatchPreviewResponseDto: type: object properties: id: type: string businessId: type: string source: type: string enum: - MANUAL - CSV - API - SCHEDULE - CHANNEL status: type: string enum: - DRAFT - QUEUED - PROCESSING - COMPLETED - PARTIALLY_COMPLETED - FAILED - CANCELLED totalItems: type: number description: Number of line items in the batch. totalsByCurrency: type: object additionalProperties: $ref: '#/components/schemas/BatchCurrencyTotalDto' description: Summed principal / fee / totalDebit, keyed by wallet currency. twoFaVerifiedAt: type: object nullable: true description: When the whole-batch 2FA was satisfied. createdAt: type: string updatedAt: type: string completedAt: type: object nullable: true items: type: array items: $ref: '#/components/schemas/BatchItemResponseDto' affordable: type: boolean description: >- True when the summed totalDebit (per currency) is covered by the available wallet balance. errorCount: type: number description: Count of items that failed to resolve/quote (have a failureReason). requiresTwoFactor: type: boolean description: >- True when the summed USD-equivalent meets the 2FA threshold (dashboard path). required: - id - businessId - source - status - totalItems - totalsByCurrency - createdAt - updatedAt - items - affordable - errorCount - requiresTwoFactor HttpErrorEnvelopeDto: type: object properties: success: type: boolean example: false error: $ref: '#/components/schemas/HttpErrorBodyDto' required: - success - error CreateBatchItemDto: type: object properties: recipientId: type: string description: >- Saved recipient id. Provide exactly one of recipientId or inline `recipient`. recipient: description: >- Inline recipient details (mutually exclusive with recipientId). The recipient is sanctions-screened and saved to your recipient book, then paid as part of the batch. allOf: - $ref: '#/components/schemas/CreateRecipientDto' country: type: string enum: - NG - KE - ZA - TZ - UG - RW - MW - ZM - BW - CM - BJ - BF - CD - CI - GA - ML - CG - SN - TG description: >- ISO 3166-1 alpha-2 corridor country (must match the recipient country). currency: type: string description: Local destination currency for the corridor (e.g. NGN, KES). srcAmount: type: string example: '50.00' description: >- Source amount in USDC (the principal to convert/deliver). Provide srcAmount OR dstAmount. dstAmount: type: string example: '50000' description: >- Destination amount in the local currency. Provide srcAmount OR dstAmount. reference: type: string description: >- Free-form per-item reference echoed back in the preview (e.g. "March salary"). maxLength: 140 required: - country - currency BatchCurrencyTotalDto: type: object properties: principal: type: string description: Summed principal (delivered amount) in this currency. fee: type: string description: Summed total fee in this currency. totalDebit: type: string description: Summed total debit (principal + fee) in this currency. required: - principal - fee - totalDebit BatchItemResponseDto: type: object properties: index: type: number description: Zero-based index of the item in the submitted batch. payoutId: type: object nullable: true description: Child BusinessPayout id (null on error). recipientId: type: object nullable: true description: Resolved saved recipient id. recipientLabel: type: object nullable: true description: Recipient label (merchant-supplied). rail: type: string enum: - CRYPTO - ACH - WIRE - SEPA - SWIFT - LOCAL_BANK - LOCAL_MOMO country: type: string description: Corridor country (ISO 3166-1 alpha-2). currency: type: string description: Local destination currency. status: type: string enum: - CREATED - SUBMITTED - PENDING_REVIEW - SETTLED - FAILED - CANCELLED nullable: true srcAmount: type: object nullable: true description: Principal in USDC (the amount delivered). dstAmount: type: object nullable: true description: Destination amount in the local currency. rate: type: object nullable: true description: FX rate used for the quote. networkFee: type: object nullable: true description: Network cost in USDC (on top). platformFee: type: object nullable: true description: Axra platform fee in USDC (on top). totalFee: type: object nullable: true description: Total fee in USDC = networkFee + platformFee. totalDebit: type: object nullable: true description: >- Total USDC debit for this item = principal + networkFee + platformFee. failureReason: type: object nullable: true description: Per-row failure reason when resolution failed. required: - index - rail - country - currency HttpErrorBodyDto: type: object properties: code: type: string example: VALIDATION_ERROR message: type: string example: email must be an email statusCode: type: number example: 400 errors: type: object description: >- Optional per-field validation messages (when present on the source exception) additionalProperties: type: array items: type: string required: - code - message - statusCode CreateRecipientDto: type: object properties: label: type: string maxLength: 120 rail: type: string enum: - CRYPTO - ACH - WIRE - SEPA - SWIFT - LOCAL_BANK - LOCAL_MOMO details: type: object description: Rail-specific destination (shape depends on rail) required: - label - rail - details securitySchemes: bearer: scheme: bearer bearerFormat: JWT type: http ````