Client Batches

Overview

COS supports the ability to send up to 5000 payments in a single request via the client batch API. A batch request is always the preferred method of originating multiple payments at a given time.

Once a batch is accepted, it will be broken into individual payment records which may go on hold or be sent to the Federal Reserve independently. Webhook events will be fired as usual on each of these individual payments. The overall payment workflow is identical to that of payments originated individually.

It is important to note that client batch origination requests are asynchronous and the associated payment records may not be available immediately. You can monitor the progress via the status and importCount fields of the batch object.

API Origination

Below is a sample request illustrating 2 payments being submitted as a batch. Note that each batch payment must be originated from the same COS account number. If originating from multiple COS accounts, then the payments from each account must be submitted as separate batches.

POST ach/v1/client-batches
{
  "payments": [
    {
      "accountNumber": "1234567890",
      "receiver": {
        "routingNumber": "021000021",
        "accountNumber": "456789000",
        "accountType": "Checking",
        "name": "Bob Smith",
        "identification": "XYZ123",
      },
      "secCode": "PPD",
      "description": "Payment",
      "transactionType": "Push",
      "amount": 10000,
      "serviceType": "Standard",
    },
    {
      "accountNumber": "1234567890",
      "receiver": {
        "routingNumber": "021000021",
        "accountNumber": "123787777",
        "accountType": "Checking",
        "name": "Alice Smith",
        "identification": "ABC456",
      },
      "secCode": "PPD",
      "description": "Payment",
      "transactionType": "Push",
      "amount": 20000,
      "serviceType": "Standard",
    },    
  ]
}

Upon success, a client batch record will be returned which contains the individual payment identifiers which will be created. Each identifier returned correlates to the object index of the payments array in the request.

{
    "id": "00000000-0000-0000-0000-000000000001",
    "referenceId": "CB123456789",
    "status": "Processing",
    "accountNumber": "1234567890",
    "paymentCount": 2,
    "debitTotal": 0,
    "creditTotal": 30000,
    "importCount": 0,
    "productId": "00000000-0000-0000-0000-000000000000",
    "partnerId": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2020-09-08T17:10:20.359Z",
    "importedAt": "2020-09-08T17:10:20.359Z",
    "lastModifiedAt": "2020-09-08T17:10:20.359Z",
    "paymentIdentifiers": [
        "00000000-0000-0000-0000-000000000001",
        "00000000-0000-0000-0000-000000000002"
    ]
}

API Cancellation

While still possible to individually cancel payments within a batch, there are times where it may be more efficient to call the cancel batch API in order to cancel any pending or on-hold payments within that batch.

POST /v1/client-batches/00000000-0000-0000-0000-000000000001/cancel