> ## Documentation Index > Fetch the complete documentation index at: https://docs.rc.cleverhub.co/llms.txt > Use this file to discover all available pages before exploring further. # Create Payout Batch via File > This API enables you to create a batch payout to PayID or NPP-enabled BSB accounts by uploading a file containing payout details, facilitating bulk payment processing to multiple recipients efficiently. If a payout cannot be processed due to insufficient funds and the `is_retry` flag is set to true, the system will continue to attempt processing until sufficient funds are available, either through a top-up or new incoming payments. Payment statuses: - **created**: Payout payment created and pending further processing. - **processing**: Payout has been topped up to the corresponding PayID and is currently being processed. - **scheduled**: Waiting for funds to be debited from the payer's account; the payout is scheduled but not yet executed. - **completed**: Payout payment has been completed successfully for the entire batch. Note that individual transaction failures do not affect the completion status of the overall batch. Important notes: - If using a phone number as the PayID, prefix it with the country code, separated by a dash. For example: `+61-412345678`. - PayIDs using email addresses must be in lowercase (e.g., `johnwick@gmail.com`). ## OpenAPI ````yaml /api/openapi/v1-reference.yaml post /v1/payouts/ openapi: 3.0.3 info: title: Payment APIs (AUD only) description: >- ## Introduction The Payment API Solution (AUD) offers developers a comprehensive suite of API services to build innovative AUD payment solutions efficiently. These APIs enable seamless transactions using various payment methods and functionalities, ensuring a robust, reliable, and scalable payment infrastructure tailored for the Australian market. ### Key Features - **Payment Methods**: - **Payment Link**: Supports payments via card and PayID. - **PayID**: Provides instant payments using a unique identifier. - **PayTo**: Enables scheduled or recurring payments. - **BSB/Account Number**: Allows direct bank transfers. - **Payout**: Manage payouts to designated accounts. - **Additional Functionalities**: - **Balance Management**: Real-time balance inquiries and updates. - **Reporting Services**: Generate detailed transaction and payment reports. This documentation provides detailed guidance for integrating these capabilities into your application. termsOfService: https://helloclever.co/terms contact: email: support@helloclever.co version: 1.0.11 servers: - url: https://api.cleverhub.co/api description: Sandbox Environment - url: https://api-merchant.helloclever.co/api description: Production Environment security: [] paths: /v1/payouts/: post: tags: - AUD Payout summary: Create Payout Batch via File description: > This API enables you to create a batch payout to PayID or NPP-enabled BSB accounts by uploading a file containing payout details, facilitating bulk payment processing to multiple recipients efficiently. If a payout cannot be processed due to insufficient funds and the `is_retry` flag is set to true, the system will continue to attempt processing until sufficient funds are available, either through a top-up or new incoming payments. Payment statuses: - **created**: Payout payment created and pending further processing. - **processing**: Payout has been topped up to the corresponding PayID and is currently being processed. - **scheduled**: Waiting for funds to be debited from the payer's account; the payout is scheduled but not yet executed. - **completed**: Payout payment has been completed successfully for the entire batch. Note that individual transaction failures do not affect the completion status of the overall batch. Important notes: - If using a phone number as the PayID, prefix it with the country code, separated by a dash. For example: `+61-412345678`. - PayIDs using email addresses must be in lowercase (e.g., `johnwick@gmail.com`). requestBody: required: true content: multipart/form-data: schema: type: object required: - file - scheduled_at - description - endpoint_url - authorization_header properties: file: type: string format: binary description: > The file containing payout details. Supported formats are `.csv` or `.xlsx`. You can download an example file at [this link](/assets/payout/Payout_valid.xlsx). scheduled_at: type: string format: date-time description: > The scheduled date and time for the payout transaction in UTC. Format should be `YYYY-MM-DDTHH:mm:ss`. example: '2024-01-01T10:00:00' description: type: string minLength: 5 maxLength: 140 description: Brief description of the payout purpose. example: Monthly salary payout for January is_retry: type: boolean default: false description: > If set to true, the system will attempt to retry the payout in case of insufficient funds, processing it once funds are available. Default is false. example: true external_id: type: string description: >- A custom identifier provided by the merchant for tracking purposes. example: custom-payout-id-123 endpoint_url: type: string format: uri description: > URL that Hello Clever will invoke when the status of the transaction changes. The client must expose a TLS 1.2-secured endpoint with a certificate from a well-known commercial certificate authority. Self-signed or internally signed certificates are not accepted. example: https://merchant.example.com/payout_status_callback authorization_header: type: string description: > The authorization header value that Hello Clever will include in the callback request for security. example: Bearer your_secret_token responses: '200': description: Payout batch created successfully. content: application/json: schema: $ref: '#/components/schemas/PayoutObject' '400': description: Bad Request '401': description: Unauthorized '404': description: Not Found '422': description: Unprocessable Entity callbacks: payoutCallback: '{$request.body#/endpoint_url}': post: requestBody: description: PayoutObject content: application/json: schema: $ref: '#/components/schemas/PayoutObject' responses: '200': description: Callback received successfully '400': description: Bad request '401': description: Unauthorized method: post type: path path: '{$request.body#/endpoint_url}' components: schemas: PayoutObject: type: object properties: id: type: integer description: > A unique identifier assigned to the payout payment, used for tracking and referencing purposes within the system. example: 12345 uuid: type: string description: > A unique UUID assigned to the payout payment, providing a globally unique reference for the transaction. example: 550e8400-e29b-41d4-a716-446655440000 description: type: string description: > A description of the payout payment, providing context or additional information such as the purpose of the payout. example: 'Payout for invoice #12345' payid: type: string description: > The PayID used for topping up the payout payment, allowing for easy routing of funds to the correct recipient. example: sample@payid.com total_amount: type: string description: > The total amount of all transactions included in the payout, providing the complete value being paid out. example: '1000.00' total_refund: type: string description: | The total amount that has been refunded to the payee, if applicable. example: '100.00' total_failed_transactions: type: string description: > The total number of transactions within the payout that failed to complete successfully. example: '2' scheduled_at: type: string format: date-time description: > The date and time when the payout transaction is scheduled to occur, expressed in UTC. example: '2024-12-31T23:59:59Z' status: type: string enum: - created - processing - scheduled - completed - expired description: | The current status of the payout payment. Possible values include: - `created`: The payout has been created but not yet processed. - `processing`: The payout is currently being processed. - `scheduled`: The payout is scheduled for a future date. - `completed`: The payout has been completed successfully. - `expired`: The payout has expired. example: processing export_url: type: string format: uri description: > A URL for downloading an attachment related to the payout payment, such as a receipt or transaction details. example: https://example.com/download/payout_attachment payout_notification: type: object description: > Details regarding the merchant callback settings for payout status updates, including the endpoint URL and authorization header. properties: endpoint_url: type: string format: uri description: > An internet-accessible URL that will be invoked when the status of the payout changes, allowing the merchant to receive real-time updates. example: https://merchant.com/payout_callback authorization_header: type: string description: > The authorization header value to be used in the callback request, helping ensure the request is authenticated. example: Bearer your_token error_code: type: string description: > An error code associated with the payout, indicating any issues that occurred during processing. example: HC_PAYOUT1 error_message: type: string description: > A description of the error encountered during the payout process, providing context for troubleshooting. example: >- Insufficient funds to payout. Please top up balance in the dashboard. is_retry: type: boolean description: > Indicates whether the payout is being retried after a previous failure. example: false external_id: type: string description: > A custom identifier for the payout, provided by the merchant for tracking and reference purposes. example: custom-payout-id-6789 payout_transactions: type: array description: > A list of individual transactions that are part of the payout, including details such as payee information and transaction status. items: type: object properties: id: type: integer description: > A unique identifier assigned to the payout transaction, used for tracking and referencing purposes. example: 123 balance_id: type: string description: > The UUID of the balance transaction associated with the payout, providing a reference to the specific balance movement. example: 550e8400-e29b-41d4-a716-446655441111 payee: type: string description: > The name of the payee receiving the payout, used to identify the recipient of the funds. example: John Doe payid: type: string description: > The PayID of the payee, used to route the payout to the correct recipient. example: payee@payid.com payid_type: type: string description: > The type of PayID being used by the payee. Valid values include: - `EMAIL`: An email address. - `PHONE`: A phone number. - `ABN`: An Australian Business Number. enum: - EMAIL - PHONE - ABN example: EMAIL bsb: type: string description: > The Bank-State-Branch (BSB) number of the payee's account, used to identify the bank and branch for the transaction. example: '123456' account_number: type: string description: > The account number of the payee, used to route the payout to the correct bank account. example: '987654321' amount: type: string description: > The amount being paid to the payee as part of the payout transaction. example: '500.00' status: type: string description: > The current status of the payout transaction. Possible values include: - `created`: The transaction has been created but not yet processed. - `processing`: The transaction is currently being processed. - `settled`: The transaction has been completed successfully. - `failed`: The transaction failed to complete successfully. enum: - created - processing - settled - failed example: settled error_message: type: string description: > An error message providing details about why the payout transaction failed, if applicable. example: Payment failed due to insufficient funds. created_at: type: string format: date-time description: > The date and time when the payout transaction was created, expressed in UTC. example: '2024-01-01T00:00:00Z' ```` ## Related topics - [Payment APIs for AUD (v1)](/api/v1/introduction.md) - [Create a Payout](/api/aud-payout/create-a-payout.md) - [Create KYC for Beneficiary](/api/aud-payout/create-kyc-for-beneficiary.md)