API tutorials
ACH
Simulate inbound ACH
what you will learn ✅ how to simulate in sandbox for ach inbound originations returns corrections ( {{noc}} ) if you are new to apis and how the work we recommend you visit structure the tutorial uses these api endpoints api description post /v1/payments/simulated inbound originations simulates sending funds sent via ach to a cross river account from another bank this endpoint can also be used to fund an account in sandbox post /v1/payments/simulated inbound returns simulates return of a payment from outside cross river post /v1/payments/simulated inbound corrections simulates a notification of change (noc) before you begin make sure you have get api credentials for sandbox access cross river account number for returns and corrections, payment ids of completed payments simulate ach actions simulations allow you to test certain inbound payment flows in our sandbox environment you can trigger these flows explicitly using the api endpoints outlined below, or, in the case of returns and corrections, automatically once an outbound payment completes automatic simulations are triggered by convention using the payment purpose field important you can only simulate a return or noc for a payment once it has updated to a status of complete test outbound payments using the send payment the sandbox environment automatically takes the payment through the various statuses until it is complete typically this process takes up to several minutes from start to finish where's my simulated payment? it is important to note that simulation requests are queued and processed asynchronously on a schedule it typically takes a few minutes before they show up as new payment records \<the first major step in your tutorial> \<the first major step in your tutorial> \<a general description of what the first major step in your tutorial involves include (fake) values for required attributes and a link to the endpoint in the api section > \<a general description of what the first major step in your tutorial involves include (fake) values for required attributes and a link to the endpoint in the api section > to s imulate an inbound ach payment inbound originations are payments that originate at another financial institution and are sent to a cross river account these payments can have a transactiontype of either push (funds are being sent to your cross river account) or pull (funds are being taken from your cross river account) to simulate an inbound origination, manually trigger it using the simulated inbound originations endpoint call post /v1/payments/simulated inbound originations required fields attribute description value for simulation originatorroutingnumber routing number of a bank outside cross river 021000021 originatorname name of bank account holder tom smith originatoridentification identifier for the bank account 99999999 receiveraccountnumber account number of the sandbox account to receive the funds your sandbox account receiveraccounttype type of account receiving the funds one of checking savings generalledger loan the type of account your sandbox account is receivername name on the account receiving the funds the name on your sandbox account seccode sec codes (sec) code required by nacha for every ach transaction for the simulation we recommend using ppd description description of the payment maximum 10 characters for the simulation we recommend writing testing transactiontype sending or requesting funds push (originator is sending funds—debit) pull (originator is receiving funds—credit) see payment types use push if you are funding a sandbox account amount dollar amount of payment in positive integral cents for example, $1 00 appears as 100 servicetype either payment types or payment types see send an ach for additional information sample request curl location 'https //sandbox crbcos com/ach/v1/payments/simulated inbound originations' \\ \ header 'content type application/json' \\ \ header 'authorization bearer \<token>' \\ \ data '{ "originatorroutingnumber" "021000021", "originatorname" "tom smith", "originatoridentification" "99999999", "receiveraccountnumber" "2819503463", "receiveraccounttype" "checking", "receivername" "jerry penn", "receiveridentification" "inv123", "seccode" "ppd", "description" "testing", "transactiontype" "push", "amount" 1000, "servicetype" "sameday", }' a successful api call returns a json response with the details of the payment sample response { "originatorroutingnumber" "021000021", "originatorname" "tom smith", "originatoridentification" "99999999", "receiveraccountnumber" "2819503463", "receiveraccounttype" "checking", "receivername" "jerry penn", "receiveridentification" "inv123", "seccode" "ppd", "description" "testing", "transactiontype" "push", "amount" 1000, "servicetype" "sameday", "settlementdays" 0 } to simulate an ach return you can simulate an ach return with the simulation endpoint post /v1/payments/simulated inbound returns or with the send an ach docid\ hliqojnmhjwjri29z0ryt api to use the simulation endpoint have ready the id of the outbound payment you are simulating the return for (found in the response of the send an ach) and a request and response codes call post /v1/payments/simulated inbound returns post /v1/payments/simulated inbound returns request curl location 'https //sandbox crbcos com/ach/v1/payments/simulated inbound returns' \\ \ data '{ "returncode" "r02", "previouspaymentid" "1b228f4c 26d4 4da0 b813 b34300e84b4e" }' a successful api call returns a json response post /v1/payments/simulated inbound returns response { "returncode" "r02", "previouspaymentid" "1b228f4c 26d4 4da0 b813 b34300e84b4e" } to simulate a return automatically using the send an ach docid\ hliqojnmhjwjri29z0ryt api when you send the post /v1/payments call, populate the purpose field (row 18 below) with return rxx , where xx is the request and response codes you wish to test post /v1/payments return request curl location 'https //sandbox crbcos com/ach/v1/payments' \\ \ header 'idempotency key c10314ee e737 4681 8e8d f9cf547c9967' \\ \ header 'content type application/json' \\ \ header 'authorization bearer \<token>' \\ \ data '{ "accountnumber" "2203250853", "receiver" { "routingnumber" "021000021", "accountnumber" "2151546989", "accounttype" "checking", "name" "peter griffin" }, "seccode" "ppd", "description" "math tutor", "transactiontype" "push", "amount" 25000, "servicetype" "standard", "purpose" "return r01" } contested returns have to be anticipated or approved for acceptance in that case, only the initial return event is listed as returned, and a subsequent webhook is applied the dishonoring of the return relays the funds back to the returning source and no webhook launches for those or any other rejecting/dishonoring attempts without your direct consent, no returns of any kind occur while outside of the 24 hour (corporate return) or 60 day (consumer return) time frame transactions received outside of both scenarios are subject to review and processing for any claims issued to the cross river ach operations team, a notice is provided to the originating party for proof of authorization or any other corroborating documents that warrant the authorization of the debit entry your rm will also be advised of any matters for awareness to simulate a c orrection you can simulate an ach noc correction with the simulation endpoint post /v1/payments/simulated inbound corrections or with the send an ach docid\ hliqojnmhjwjri29z0ryt api to use the simulation endpoint have ready the id of the outbound payment you are simulating the correction for (found in the response of the send an ach), the correction and the request and response codes call post /v1/payments/simulated inbound corrections post /v1/payments/simulated inbound corrections request curl location 'https //sandbox crbcos com/ach/v1/payments/simulated inbound corrections' \\ \ header 'content type application/json' \\ \ header 'authorization bearer \<token>' \\ \ data '{ "changecode" "c04", "correcteddata" "peter g griffen", "previouspaymentid" "04228e9c 361e 4005 b68f b339008ae4dc" }' a successful api call returns a json response post /v1/payments/simulated inbound returns response { "changecode" "c04", "correcteddata" "peter g griffen", "previouspaymentid" "04228e9c 361e 4005 b68f b339008ae4dc" }' to simulate a noc correction automatically using the send an ach docid\ hliqojnmhjwjri29z0ryt api when you send the post /v1/payments call, populate the purpose field (row 18 below) with noc cxx , where xx is the request and response codes you wish to test our example shows an outbound pull payment where an incorrect dfi account number correction (c01) will be automatically generated by the cross river system after the outbound payment is complete post /v1/payments return request curl location 'https //sandbox crbcos com/ach/v1/payments' \\ \ header 'idempotency key c10314ee e737 4681 8e8d f9cf547c9967' \\ \ header 'content type application/json' \\ \ data '{ "accountnumber" "2203250853", "receiver" { "routingnumber" "021000021", "accountnumber" "2151546989", "accounttype" "checking", "name" "peter griffin" }, "seccode" "ppd", "description" "math tutor", "transactiontype" "push", "amount" 25000, "servicetype" "standard", "purpose" "noc c01", }' simulations explained since returns and nocs can only be simulated after an outbound payment reaches a status of complete , the outbound payment's service type will affect the timing of your simulations an outbound payment with a standard service type would only allow you to simulate a return the following day via the simulation endpoint if the simulation was done using the purpose field of the outbound payment, then you'd automatically receive the simulated inbound payment two business days after the payment is completed some sec codes will also encounter this timing scenario, such as iats which are restricted to a standard service type this is generally why you would encounter any scenarios where you’ve originated a payment but the status hasn’t changed to complete in over 24 business hours if you originated any payments yesterday, you can use the simulation endpoints to simulate any return code you want our ach domain in sandbox is configured to simulate the bank’s processes around ach origination, which means that generally no human intervention is needed to action a payment in order for it to be processed and moved to a status of complete we do not mark any payments as paid; once you originate a payment, assuming all systemic validations pass then sandbox will simulate the payment being sent to the fed and also simulate receiving an acknowledgment file from the fed when a payment request is submitted to cos, the bank can reject the payment for various reasons for example, a payment which was on hold for compliance reasons was rejected because the partner was unable to provide additional payment related information payments which are manually rejected by someone in cross river do not include any details for the rejection payments which are systemically rejected will contain the reason within the payment details for example, if a payment was rejected because the originator cross river account had insufficient funds then you would see nsf as the postingcode within the payment details