> ## 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 + authorize a scheduled payout > Validates the cadence (MONTHLY day-of-month 1–28, optional) and the per-run USD cap (defaults to $50k, rejected above the $250k admin ceiling), sanctions-screens every recipient in the payload, verifies the transaction PIN on the dashboard path (api-key exempt), stamps authorizedAt/By, and computes the first nextRunAt. Unattended runs execute without re-authorization, bounded by maxRunAmountUsd. ## OpenAPI ````yaml /openapi.json post /api/v1/business/payouts/schedules 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/schedules: post: tags: - Business Payout Schedules summary: Create + authorize a scheduled payout description: >- Validates the cadence (MONTHLY day-of-month 1–28, optional) and the per-run USD cap (defaults to $50k, rejected above the $250k admin ceiling), sanctions-screens every recipient in the payload, verifies the transaction PIN on the dashboard path (api-key exempt), stamps authorizedAt/By, and computes the first nextRunAt. Unattended runs execute without re-authorization, bounded by maxRunAmountUsd. operationId: SchedulePayoutsController_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/CreateScheduleDto' responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: '#/components/schemas/ScheduleResponseDto' 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: CreateScheduleDto: type: object properties: name: type: string minLength: 1 maxLength: 120 description: Human label, e.g. "Monthly payroll". cadence: type: string enum: - ONCE - WEEKLY - BIWEEKLY - MONTHLY description: ONCE | WEEKLY | BIWEEKLY | MONTHLY. dayOfMonth: type: number minimum: 1 maximum: 28 description: >- MONTHLY only: day-of-month (1–28) to fire on. Absent → the creation day-of-month. Ignored for other cadences. payloadKind: type: string enum: - SINGLE - BATCH description: SINGLE | BATCH. payload: description: The frozen payout spec. allOf: - $ref: '#/components/schemas/SchedulePayloadDto' maxRunAmountUsd: type: number example: 50000 description: >- Per-run USD cap (compliance). Defaults to SCHEDULE_RUN_USD_DEFAULT ($50k); rejected if above the SCHEDULE_RUN_USD_CEILING admin cap ($250k). endAt: type: string description: >- Optional natural end. After this instant the schedule auto-completes. pin: type: string description: >- Transaction PIN, required on the dashboard path to authorize the schedule (verified server-side). Not required on the api-key path. Future runs execute automatically. metadata: type: object description: Optional caller metadata persisted on the schedule. maxRunLocalCaps: description: >- Optional per-currency caps for locally-denominated runs. A currency listed here is checked against the run total in that currency and is immune to FX movement; every other currency still falls under maxRunAmountUsd. Omit for USD-only capping (the existing behaviour). type: array items: $ref: '#/components/schemas/ScheduleLocalCapDto' required: - name - cadence - payloadKind - payload ScheduleResponseDto: type: object properties: id: type: string businessId: type: string name: type: string description: Human label, e.g. "Monthly payroll". cadence: type: string enum: - ONCE - WEEKLY - BIWEEKLY - MONTHLY dayOfMonth: type: object nullable: true description: MONTHLY day-of-month (1–28). Null for other cadences. payloadKind: type: string enum: - SINGLE - BATCH status: type: string enum: - ACTIVE - PAUSED - COMPLETED - CANCELLED itemCount: type: number description: Number of payout specs in the frozen payload. nextRunAt: type: string description: When the next run fires (ISO-8601). lastRunAt: type: object nullable: true description: When the last run fired (ISO-8601). endAt: type: object nullable: true description: Optional natural end (ISO-8601). runCount: type: number description: How many times this schedule has run. maxRunAmountUsd: type: string description: Per-run USD cap (compliance). maxRunLocalCaps: nullable: true description: >- Per-currency run caps, or null for USD-only capping. A currency listed here is checked against the run total in that currency, so it does not breach on FX movement alone. type: array items: $ref: '#/components/schemas/ScheduleLocalCapDto' authorizedAt: type: string description: When PIN + screening were completed at creation (ISO-8601). createdAt: type: string updatedAt: type: string required: - id - businessId - name - cadence - payloadKind - status - itemCount - nextRunAt - runCount - maxRunAmountUsd - authorizedAt - createdAt - updatedAt HttpErrorEnvelopeDto: type: object properties: success: type: boolean example: false error: $ref: '#/components/schemas/HttpErrorBodyDto' required: - success - error SchedulePayloadDto: type: object properties: kind: type: string enum: - SINGLE - BATCH description: SINGLE | BATCH discriminator. items: description: >- Payout specs. SINGLE must carry exactly one item; BATCH carries up to BATCH_MAX_ITEMS. type: array items: $ref: '#/components/schemas/ScheduleItemSpecDto' required: - kind - items ScheduleLocalCapDto: type: object properties: currency: type: string example: NGN description: Destination currency this cap applies to. amount: type: string example: '20000000' description: >- Maximum total destination amount per run in `currency`. Compared against the sum of the run's destination amounts in that currency — never converted, so it does not move with FX. required: - currency - amount 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 ScheduleItemSpecDto: 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). Sanctions-screened and saved to your recipient book at schedule creation. 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 (e.g. "March salary"). maxLength: 140 required: - country - currency 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 ````