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

File Support

As an alternative to the API, COS can create a batch from either a standard NACHA file or JSON file. Files can be used in conjunction with APIs and webhooks. JSON files should be submitted with the same request data the POST client batch API requires (illustrated above).

A maximum of 50,000 payments per file, and no more than 50 files per day are supported.

Acknowledgements will be communicated via CSV files. Most fields in this file are identical to those in the API payment record. See sample file layout below:

FieldNotes
ActionImported- outbound payment has been successfully imported into COS
Sent - outbound payment has been transmitted to the Federal Reserve
Received - inbound payment has been received from the Federal Reserve
PaymentIdInternal COS payment identifier (GUID)
PaymentTypeOrigination, Return
TransactionTypePush - credit transaction
Pull - debit transaction
ServiceTypeStandard
SameDay
DirectionInbound
Outbound
TraceNumberNACHA trace number. Note that COS will regenerate this number and ignore the number submitted in the source file. Original trace number will be preserved in the Purpose field below
SecCodeStandard entry class code
EffectiveDateNACHA effective date in YYMMDD format
OriginatorNameNACHA batch company name
OriginatorRoutingNumberNACHA batch originating DFI identification
OriginatorIdentificationNACHA batch company identification
ReceiverNameNACHA entry receiving entity name
ReceiverRoutingNumberNACHA entry DFI identification number
ReceiverAccountNumberNACHA entry DFI account number
ReceiverIdentificationNACHA entry individual identification number
Description10 character short description for payment
AmountDollar amount of the payment in cents
PurposeOn outbound payments this will contain the original batch number and trace number submitted in the source NACHA file in the following format:
batch.trace
For example:
1.021214890000001
ClientBatchIdUnique identifier for batch (GUID)
ClientBatchSequenceSequence number of payment in batch
FedBatchIdUnique identifier for Federal Reserve batch the payment went out on (or came in on for inbound payments)
FedBatchSequenceSequence number of payment in batch
CreatedAtTimestamp of when the payment record was created in COS. Timezone is EST.
ReasonCodeReturn code or notification of change code, depending on the payment type
ReasonDataSupporting data for ReasonCode
PreviousPaymentIdAssociated original payment for returns or notifications of change