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:

Field

Notes

Action

Imported- 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

PaymentId

Internal COS payment identifier (GUID)

PaymentType

Origination, Return

TransactionType

Push - credit transaction
Pull - debit transaction

ServiceType

Standard
SameDay

Direction

Inbound
Outbound

TraceNumber

NACHA 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

SecCode

Standard entry class code

EffectiveDate

NACHA effective date in YYMMDD format

OriginatorName

NACHA batch company name

OriginatorRoutingNumber

NACHA batch originating DFI identification

OriginatorIdentification

NACHA batch company identification

ReceiverName

NACHA entry receiving entity name

ReceiverRoutingNumber

NACHA entry DFI identification number

ReceiverAccountNumber

NACHA entry DFI account number

ReceiverIdentification

NACHA entry individual identification number

Description

10 character short description for payment

Amount

Dollar amount of the payment in cents

Purpose

On 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

ClientBatchId

Unique identifier for batch (GUID)

ClientBatchSequence

Sequence number of payment in batch

FedBatchId

Unique identifier for Federal Reserve batch the payment went out on (or came in on for inbound payments)

FedBatchSequence

Sequence number of payment in batch

CreatedAt

Timestamp of when the payment record was created in COS. Timezone is EST.

ReasonCode

Return code or notification of change code, depending on the payment type

ReasonData

Supporting data for ReasonCode

PreviousPaymentId

Associated original payment for returns or notifications of change


Did this page help you?