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

Payment Status

Individual payments within a bulk follow the regular payment lifecycle. The bulk file itself has an additional status, representing the aggregated status of all payments in the bulk:

• PendingProcessing: Bulk is being validated and processed
• Processed: At least 51% of payments in the bulk have been successfully processed
• Rejected: Bulk has been rejected due to validation errors
• Cancelled: Bulk has been cancelled (either partially or completely)

Checking Bulk Status

You have multiple options for monitoring bulk payment progress:

1. Get overall status using GET /api/v1/payments/bulks/{payment-bulk-id}/status - Returns an aggregated status where "Processed" means at least 51% of payments are processed.

2. Get detailed statistics using GET /api/v1/payments/bulks/{payment-bulk-id} - Provides:

   • Overall bulk status
   • Payment statistics including counts for each status
   • Total number of payments
   • Aggregated amount

3. Check individual payments using GET /api/v1/payments/singles with a filter on PaymentBulkId - Allows you to track the status of specific payments within the bulk submission.

Bulk Payment Cancellation

For bulk payments, use the PUT /api/v1/payments/bulks/{payment-bulk-id}/cancel endpoint.

When you initiate a cancellation, the system will attempt to cancel each individual payment in the bulk, applying the same cancellation rules as for single payments.

If some payments have already been processed, partial cancellation is allowed. After processing, the system returns a summary indicating which payments were successfully cancelled.

Duplicate Check

The system keeps a hash of submitted bulk payment files for 100 days to prevent duplicate processing:

• Identical files are rejected - Same content will be rejected even with different filenames
• Modified content is accepted - Changing any character in the file will pass the duplicate check
• Renaming files doesn't work - Simply changing the filename with identical content will be rejected

Error message: Duplicate submissions return "DuplicateFileUpload"

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.