Originate a client batch
✅ Register the relevant webhooks
✅ Submit a client batch of payments
✅ Cancel the batch
If you are new to ACH we recommend you read the ACH overview before starting this tutorial.
The tutorial assumes you have a knowledge of APIs and how they work. For more information on sending API calls, see the API basics.
The tutorial uses these API endpoints.
API | Description |
|---|---|
Submits 2 or more payments from the same CR account number as a batch | |
Cancels all the payments in the batch that have not yet been completely processed |
IMPORTANT
- Do not poll the APIs for status updates and reconciliation purposes.
- Incorporate webhooks into the payment reconciliation process.
The tutorial uses these webhooks. See all ACH-related webhooks here.
Webhook | Description |
|---|---|
Ach.Batch.Imported | Notifies you that the client batch has been imported |
Ach.Batch.Canceled | Notifies you that all pending or on-hold payments in the client batch are canceled |
Make sure you have:
- Partner ID
- Account Number
To receive the webhook events for this tutorial both partner accounts need to register each specific webhook event type. Once you are registered, the event objects are sent to the registered URLs.
The event object contains a list of resource identifiers used to download details on each event.
Use a client batch when you have several transfers to or from the same account. For example, for payroll. In this tutorial the example account number is 2207975570. The following 5 different actions appear in the sample code.
Name | Account number | Transaction type | Service type | Amount | Routing number | Account type | Standard Entry Class (SEC) codes |
|---|---|---|---|---|---|---|---|
John Wick | 12345678 | Push | SameDay | 113 | 021000021 | Checking | PPD |
Cleveland Brown | 2342123458 | Pull | Standard | 243591 | 021000021 | Checking | PPD |
Matt Cauthon | 2342123458 | Pull | Standard | 50 | 021000021 | Checking | PPD |
Perrin Aybara | 2342123458 | Push | Standard | 2750 | 021000021 | Checking | PPD |
Elayne Trakand | 2342123458 | Pull | SameDay | 15000 | 021000021 | Checking | PPD |
Call POST ach/v1/client-batches. The details of each payment are defined by the call attributes, which can be seen here. Values for these attributes must be provided for each payment in the batch.
IMPORTANT We strongly recommend that you include an idempotency key in your request header to provide duplicate protection should the payment fail. Read more about idempotency keys here.
Money amounts in API calls and responses are written without a decimal point between the dollars and the cents.
A successful API call returns a JSON response with the details of the client batch record that contains the client batch ID (in our case, fcb7188f-e051-4f5b-addd-afaa00eadb3a) and individual paymentIdentifiers. The identifiers appear in the response in the order that the payments were listed in the request. So in our case, the payment to John Wick is assigned paymentIdentifier 04793f3-13d9-4d52-b57e-afaa00eb6c74, the payment from Cleveland Brown corresponds to dbe36253-06d1-462a-9117-afaa00eb6c74, and so on.
The status attribute in the response indicates that your batch is processing. It does not indicate that the batch was imported successfully.
The importCount attribute in the response indicates how many payments were imported (meaning originated) out of the total at the time of the response.
When the status of the client batch changes to imported the Ach.Batch.Imported webhook event fires.
The status in the webhook refers to the webhook status, not the client batch status.
After this, assuming you've registered for the relevant webhooks, each payment behaves like a single originated payment
For example, when the Federal Reserve accepts the payment the status changes to processing, which triggers the Ach.Payment.Sent event. Every status change from this point on triggers the event until the payment posts to the receiving account (status: complete).
Sometimes it's most efficient to cancel a client batch before all the payments have imported rather than try to cancel a large number of payments individually. Call the cancel batch API to cancel any pending or on-hold payments within a batch.
Call POST /v1/client-batches/{id}/cancel to cancel the batch. Use the client batch ID: the id value (in our case, fcb7188f-e051-4f5b-addd-afaa00eadb3a) received in the response to the POST ach/v1/client-batches call.
A successful API call returns a JSON response with the details of the client batch record that contains the individual payment identifiers of all payments that were canceled. (Payments with a Completed status cannot be canceled.) The status in the response is Canceling. As with the client batch request above, each identifier returned corresponds to the order in which the payments were presented in the request.
When the cancellation is complete, it triggers the Ach.Batch.Canceled webhook event. Note the client batch ID (in this case , fcb7188f-e051-4f5b-addd-afaa00eadb3a) corresponds to the client batch ID used in the cancellation request.
