Bulk Payments

Bulk payments allow you to initiate multiple payments in a single request using a CSV file. This approach is ideal for processing large volumes of payments efficiently and is commonly used for payroll, vendor payments, and other batch payment scenarios.

Benefits of Using Bulk Payments

• Efficiency: Process hundreds or thousands of payments in a single API call
• Reduced API overhead: Fewer HTTP requests compared to individual payment submissions
• Batch processing: All payments in a bulk are processed together with consistent timing
• Simplified reconciliation: Each bulk gets a unique paymentBulkId for easy tracking

Available Endpoints

Partial Bulk Processing

When a bulk file contains some payments with errors, the system distinguishes between different types of failures:

Soft Errors (Recoverable): Individual payment validation errors that don't prevent other payments from being processed. Examples include invalid dates, missing required fields, or formatting issues. When soft errors occur, you can choose to proceed with the valid payments.

Hard Errors (Non-recoverable): Critical issues that prevent the entire bulk from being processed, such as file format problems or authentication failures. In some cases, certain errors on an individual cause the system to question the integrity of the entire bulk file and result in the whole bulk being rejected. These errors require fixing the entire submission before reprocessing.

For error codes, see Bulk Payment Errors (file-level) and Payment Rejection Codes (individual payments).

Processing Options and Controls

When soft errors are detected, the system provides two key properties to control how you proceed:

canProceedWithErrors: Boolean in the error response. When false, the entire file is rejected. When true, you can choose to proceed with valid payments only.

ProceedWithErrors: Optional header parameter. Set to true when resubmitting the same file to process only valid payments and skip invalid ones.

You have two options when soft errors occur:

1. Fix all errors and resubmit - Correct all invalid payments and upload the entire file again
2. Proceed with valid payments - Use the ProceedWithErrors: true header to process only the valid payments while skipping the invalid ones

Example Error Response

When validation errors occur, you'll receive a response like:

{
  "type": "Csv",
  "errors": [
    {
      "fieldIndex": 7,
      "elementIndex": 1,
      "errorCode": "RequestedExecutionDateDaysInPastThresholdViolation",
      "errorDescription": "Requested Execution Date exceeds allowed number of days in the past."
    }
  ],
  "canProceedWithErrors": true
}

The canProceedWithErrors: true indicates this is a soft error and you can proceed with valid payments if desired.

Handling Invalid Payments

The invalid payments can be retrieved from:

• GET /api/v1/payments/singles and filter by bulkId
• GET /api/v1/reports/rejection-report

You can then correct and reinitiate the payments as singles, or upload another file including only the corrected payments.