Simulate inbound ACH payments

simulations allow testing certain inbound payment flows in our sandbox environment they can either be triggered 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 you can test outbound payments using the payment origination api endpoint 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 inbound originations inbound originations are payments that are originated at another financial institution and sent to your 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, you would manually trigger it using the simulated inbound originations endpoint a sample of this request is displayed below post /v1/payments/simulated inbound originations { "originatorroutingnumber" "021000021", "originatorname" "tom smith", "originatoridentification" "99999999", "receiveraccountnumber" "1234567890", "receiveraccounttype" "checking", "receivername" "john smith", "receiveridentification" "inv123", "seccode" "ppd", "description" "testing", "transactiontype" "push", "amount" 1000, "servicetype" "sameday", } the receiveraccountnumber is the number of the cross river account receiving the payment see send an ach payment for additional information returns you can simulate ach returns manually using the simulation endpoint post /v1/payments/simulated inbound returns populate the desired request and response codes along with the id of the outbound payment that you're trying to simulate a return for a sample of this request is displayed below post /v1/payments/simulated inbound returns { "returncode" "r01", "previouspaymentid" "00000000 0000 0000 0000 000000000000" } alternatively, simulate a return automatically when originating an outbound payment to do this, you'll need to use the purpose field of the payment request populate the purpose field with return rxx , where xx is the return code you wish to test a sample of this request is displayed below post /v1/payments { "accountnumber" "2342123458", "receiver" { "routingnumber" "021200339", "accountnumber" "654321987", "accounttype" "checking", "name" "glenn quagmire", "identification" "xyz123" }, "seccode" "ppd", "description" "membfee", "transactiontype" "pull", "amount" 4999, "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 corrections corrections (notifications of change) can be simulated manually using the simulation endpoint you'll need to populate the desired correction code along with the id of the outbound payment that you're truing to simulate a correction for a sample of this request is displayed below post /v1/payments/simulated inbound corrections { "changecode" "c01", "correcteddata" "12345", "previouspaymentid" "00000000 0000 0000 0000 000000000000" } alternatively, corrections can be simulated automatically when originating an outbound payment to do this, you'll need to use the purpose field of the payment request populate the purpose field with noc cxx , where xx is the correction code you wish to test a sample of this request is displayed below post /v1/payments { "accountnumber" "2342123458", "receiver" { "routingnumber" "021200339", "accountnumber" "654321987", "accounttype" "checking", "name" "glenn quagmire", "identification" "xyz123" }, "seccode" "ppd", "description" "membfee", "transactiontype" "pull", "amount" 4999, "servicetype" "standard" }, "purpose" "noc c01" } the example above illustrates 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 additional information 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