Originate a payment
In this tutorial, you'll learn how to
✅ Originate a push payment
✅ Monitor status of the payment
✅ Handle notifications of change to the outbound payment (rejected, returned, NOC)
- If you are new to APIs and how the work we recommend you read the API Basics page before starting this tutorial.
The tutorial uses these API endpoints:
API | Description |
|---|---|
Originate the payment |
- Do not poll the APIs for status updates and reconciliation purposes
- Incorporate webhooks into the payment reconciliation process
Make sure you have:
- Partner ID
- Account Number
There are two types of ACH payments:
- Push payment When you transfer money to an account in another bank.
- Pull payment When you request funds from an account in another bank.
Use an ACH prenotification (prenote) to verify and validate account details. A prenote simply means originating a payment of $0.00. If you don't receive an error response, the details are correct.
This tutorial covers push payments. A push payment can result in:
- The recipient receives the payment
- CR or ACH rejects the payment
- The recipient FI returns the payment
- The recipient receives the payment but ACH sends a Notification of Change.
Let's send $100 to Bob Smith who has an account at another bank. Since we are transferring the money to Bob's account the transactionType attribute must be Push.
Call POST /ach/v1/payments.
The details of the push payment are defined by the call attributes, which can be seen here.
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 your originated payment.
The statusattribute in the response indicates that your payment was created. It does not indicate that your payment was successful.
After originating the payment, its status changes to Pending or Hold for up to several hours.
- A Pending status lets you know that the payment request is created but has not been batched for release to the Federal Reserve. The batching process occurs several times a day.
- A Hold status indicates that the payment request is in review and has not yet been approved for release to the Federal Reserve.
Next, the payment moves to Batched status. If the payment is originated close to a weekend or bank holiday it may take a few days for the status to transition to Batched.
When the Federal Reserve accepts the payment the status changes to processing, which triggers the Ach.Payment.Sent event.
The payment ID provided in the response body of the payment origination request (id) appears in the details object of the Ach.Payment.Sent event. In this case: b96b935a-4713-4aae-973b-aeee00f1a749.
There may be situations where a payment request is rejected. A payment request rejected after initially receiving a success response from POST /ach/v1/payments could be due to:
- Technical Rejection. The transaction was unable to post from the account being used for your request, and is covered in this tutorial. Example
- You originate a push payment for an amount greater than the balance of the originator account
- You originate a payment from an account with an active restriction
- Manual Rejection. The payment was rejected by the Cross River Operations or BSA/AML Teams. Contact Cross River directly for information on why the payment was rejected.
To simulate a technical rejection, originate a push payment for an amount that exceeds the originating account balance. Information on ACH simulation is found here.
Again, let's send $100 to Bob Smith who has an account at another bank. This time, the amount you are sending exceeds the amount in the originator account.
Call POST /ach/v1/payments.
Define the call attributes as above in To originate an ACH payment
The following JSON response is returned:
The Ach.Payment.Rejected event is triggered.
The details object in the Ach.Payment.Rejected event contains the payment ID from the response body (id). In this case: f868a125-22b8-4c7e-a8dd-aeee00f76ce7.
In the details object of the event, the postingCode tells you the rejection code , in this case RES (Account Restriction). If the payment needs to be reviewed manually, the rejectionReason gives you more information about the rejection.
Sometimes an ACH payment is returned by the receiving bank. See Return Codes for a complete list of why a payment might be returned.
Example
The receiving bank can't find the specified receiver account number.
Most returns occur within 2 business days, but may take longer.
A payment return creates a new payment record with the paymentType set as Return. The new payment record is connected to the original payment record with the previous.paymentId field.
IMPORTANT Once payment status transitions to Complete, the payment record is no longer updated, even if the payment is returned.
A payment returned from a receiving bank triggers the ACH.Return.Received webhook event.
Here's an example of an ACH return webhook event:
The event shows reasonCode R01 (Insufficient Funds). The originalPaymentId field shows the ID of the original outbound payment.
There are times when Cross River receives an ACH notification of change (NOC) related to an outbound payment. When you create an API call, a NOC is referred to as a Correction in the paymentType attribute. Unlike an ACH return, a NOC indicates that the payment you previously originated:
- Posted to the receiver account
- Contained an error (such as an incorrect routing number) See ACH correction codes for a complete list
Register for the Ach.Noc.Received webhook event to be notified of an inbound NOC.
Here's an example of a NOC webhook event:
The reasonCode attribute in the response is C02. This indicates an Incorrect Routing Number. The reasonData attribute is the correct receiver routing number.
If you receive a NOC notification, update your internal records with the information you receive in the reasonData attribute.
