--- title: Simulate inbound check return slug: apis/simulate-inbound-check-return icon: {"apiMethod":"POST"} docTags: createdAt: 2026-05-13T07:04:19.224Z --- ## Relevant webhooks For this endpoint be sure you have [registered](docId\:BN5XtgkJogBe-CtwomCbS) for this webhook: - [Core.Transaction.Completed](docId\:cWUBvaS0BDIfokyxu5LhQ) ## API reference Simulates the return of a check deposited into a Cross River account that the issuing bank does not honor. In Cross River this is referred to as an *inbound return* item because the Federal Reserve sends the check (*in*) to Cross River to have the deposited funds returned to the check payor's account. :::hint{type="info"} This API can only be run in the Cross River [Sandbox](docId:_KAqyVqVNUAGQnekFKCUy). ::: :::ApiMethodV2 ```json { "name": "Endpoint: /checks/v1/payments/simulated-inbound-returns", "method": "POST", "url": "https://sandbox.crbcos.com/checks/v1/payments/simulated-inbound-returns", "description": "", "tab": "examples", "examples": { "languages": [ { "id": "flw3I6YAlYAch_R3p6UGW", "language": "curl", "code": "curl --location 'https://sandbox.crbcos.com/checks/v1/payments/simulated-inbound-returns' \\\n--data '{\n \"originalPaymentId\": \"3d70fc63-672e-4c3b-9e66-b48700b5db14\",\n \"returnCode\": \"A\"\n}'", "customLabel": "" }, { "id": "CYgeJvWZTSkXfwN-zcMWw", "language": "nodejs", "code": "var https = require('follow-redirects').https;\nvar fs = require('fs');\n\nvar options = {\n 'method': 'POST',\n 'hostname': 'sandbox.crbcos.com',\n 'path': '/checks/v1/payments/simulated-inbound-returns',\n 'headers': {\n },\n 'maxRedirects': 20\n};\n\nvar req = https.request(options, function (res) {\n var chunks = [];\n\n res.on(\"data\", function (chunk) {\n chunks.push(chunk);\n });\n\n res.on(\"end\", function (chunk) {\n var body = Buffer.concat(chunks);\n console.log(body.toString());\n });\n\n res.on(\"error\", function (error) {\n console.error(error);\n });\n});\n\nvar postData = \"{\\r\\n \\\"originalPaymentId\\\": \\\"3d70fc63-672e-4c3b-9e66-b48700b5db14\\\",\\r\\n \\\"returnCode\\\": \\\"A\\\"\\r\\n}\";\n\nreq.write(postData);\n\nreq.end();", "customLabel": "" }, { "id": "xaYu_cGuXJWdlnlKFafTe", "language": "python", "code": "import requests\n\nurl = \"https://sandbox.crbcos.com/checks/v1/payments/simulated-inbound-returns\"\n\npayload = \"{\\r\\n \\\"originalPaymentId\\\": \\\"3d70fc63-672e-4c3b-9e66-b48700b5db14\\\",\\r\\n \\\"returnCode\\\": \\\"A\\\"\\r\\n}\"\nheaders = {}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n", "customLabel": "" }, { "id": "xf_QW7WMg_SLYQn8g9GUD", "language": "ruby", "code": "require \"uri\"\nrequire \"net/http\"\n\nurl = URI(\"https://sandbox.crbcos.com/checks/v1/payments/simulated-inbound-returns\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest.body = \"{\\r\\n \\\"originalPaymentId\\\": \\\"3d70fc63-672e-4c3b-9e66-b48700b5db14\\\",\\r\\n \\\"returnCode\\\": \\\"A\\\"\\r\\n}\"\n\nresponse = https.request(request)\nputs response.read_body\n", "customLabel": "" }, { "id": "09kqCFa4VeWcg6MviC2d2", "language": "go", "code": "package main\n\nimport (\n \"fmt\"\n \"strings\"\n \"net/http\"\n \"io\"\n)\n\nfunc main() {\n\n url := \"https://sandbox.crbcos.com/checks/v1/payments/simulated-inbound-returns\"\n method := \"POST\"\n\n payload := strings.NewReader(`{`+\"\n\"+`\n \"originalPaymentId\": \"3d70fc63-672e-4c3b-9e66-b48700b5db14\",`+\"\n\"+`\n \"returnCode\": \"A\"`+\"\n\"+`\n}`)\n\n client := &http.Client {\n }\n req, err := http.NewRequest(method, url, payload)\n\n if err != nil {\n fmt.Println(err)\n return\n }\n res, err := client.Do(req)\n if err != nil {\n fmt.Println(err)\n return\n }\n defer res.Body.Close()\n\n body, err := io.ReadAll(res.Body)\n if err != nil {\n fmt.Println(err)\n return\n }\n fmt.Println(string(body))\n}", "customLabel": "" } ], "selectedLanguageId": "flw3I6YAlYAch_R3p6UGW" }, "results": { "languages": [ { "id": "uv43Jrbeg_9MgyANe5ty4", "language": "200", "code": "{\n \"id\": \"3366874c-b887-4532-aec7-b48c006d4d1f\",\n \"accountNumber\": \"2203250853\",\n \"referenceId\": \"C200R1684TDQ\",\n \"paymentType\": \"Return\",\n \"checkType\": \"Standard\",\n \"direction\": \"Inbound\",\n \"status\": \"Created\",\n \"source\": \"Api\",\n \"posting\": \"Pending\",\n \"postingCode\": \"OK\",\n \"fedBatchId\": \"0cfb50f6-afdd-4033-a1c2-b48c006d4d1f\",\n \"fedBatchSequence\": 0,\n \"coreTransactionId\": \"7153b673-bf50-4b9b-b097-b48c006d4d1f\",\n \"originalPaymentId\": \"3d70fc63-672e-4c3b-9e66-b48700b5db14\",\n \"customerId\": \"861261af-1251-49e8-966f-b2ff00d627bd\",\n \"payerRoutingNumber\": \"314074269\",\n \"payerAccountNumber\": \"28293886\",\n \"payeeName\": \"\",\n \"checkNumber\": \"1237\",\n \"bofdRoutingNumber\": \"021214891\",\n \"sequenceNumber\": \"3918624417\",\n \"amount\": 10000,\n \"currency\": \"usd\",\n \"recognizedAmount\": 0,\n \"iqaPassed\": false,\n \"returnCode\": \"A\",\n \"hasFrontImage\": true,\n \"hasBackImage\": true,\n \"isRedeposit\": false,\n \"policy\": \"Standard\",\n \"schedule\": [],\n \"createdAt\": \"2026-07-19T02:37:57.2241546-04:00\",\n \"wasReturned\": false,\n \"purpose\": \"TESTING\",\n \"decisionRequired\": false,\n \"wasDecisioned\": false,\n \"productId\": \"83bed086-8182-4151-a1e3-af5b01362783\",\n \"partnerId\": \"cd9c12f4-7691-424a-b38b-af5b0134c611\",\n \"lastModifiedAt\": \"2026-07-19T02:37:57.2241826-04:00\"\n}", "customLabel": "" }, { "id": "2aJP3W72d5MsKlvJqkQLj", "language": "400", "code": "{\n \"errors\": [\n {\n \"code\": 2012,\n \"message\": \"Payment must be status completed or rejected to be returned\"\n }\n ]\n}" } ], "selectedLanguageId": "uv43Jrbeg_9MgyANe5ty4" }, "request": { "pathParameters": [], "queryParameters": [], "headerParameters": [], "bodyDataParameters": [ { "name": "originalPaymentId", "kind": "required", "type": "string", "description": "The original payment ID, when a check has been returned or redeposited. This is the ID returned in the response to the Deposit check endpoint.", "": "The original payment ID, when a check has been returned or redeposited. This is the ID returned in the response to the Deposit check endpoint." }, { "name": "returnCode", "kind": "required", "type": "string", "description": "The 1-character code indicating the reason for the check return. See the checks request and response codes page for a complete list of values.", "": "The 1-character code indicating the reason for the check return. See the checks request and response codes page for a complete list of values." } ], "formDataParameters": [] }, "currentNewParameter": { "label": "Body Parameter", "value": "bodyDataParameters" }, "response": [ { "name": "id", "kind": "optional", "type": "string", "description": "Check payment ID" }, { "name": "accountNumber", "kind": "optional", "type": "string", "description": "Number of the account the check is drawn on", "children": [] }, { "name": "referenceId", "kind": "optional", "type": "string", "description": "The reference ID of the check payment, indicating the rail type in the first element of the string. In this case it is C. This is an internal Cross River attribute.", "children": [] }, { "name": "paymentType", "kind": "optional", "type": "string", "description": "The check paymentType indicates whether the check has been presented for payment or has been returned for some reason:\n\n- Forward (a check presented for payment, to be sent to the payer bank)\n- Return (A previous forward item that the payer bank returned)", "children": [] }, { "name": "checkType", "kind": "optional", "type": "string", "description": "Type of check being dealt with. There are several check types:\n- Standard\n- OnUs\n- Treasury\n- MoneyOrder\n- FedReserveBank\n- FedHomeLoan\n- StateLocalGovt\n- Certified\n- Unknown", "children": [] }, { "name": "direction ", "kind": "optional", "type": "string", "description": "Check direction:\n- Inbound (A check drawn from a COS account, deposited at another bank)\n- Outbound (A check deposited into a COS account, drawn from an account at another bank)", "children": [] }, { "name": "status", "kind": "optional", "type": "string", "description": "Status of the check payment. There are several possible payment statuses:\n- Created\n- Pending\n- Hold\n- Batched\n- Processing\n- Completed\n- Rejected\n- Canceled", "children": [] }, { "name": "source", "kind": "optional", "type": "string", "description": "Source of the payment request:\n- Api\n- PartnerPortal\n- OpsPortal\n- File\n- System\n- Lockbox", "children": [] }, { "name": "posting", "kind": "optional", "type": "string", "description": "Posting status:\n- Pending\n- Posted\n- Failed\n- Canceled\n- Authorized\n- Authorizing", "children": [] }, { "name": "rejectionReason", "kind": "optional", "type": "string", "description": "Rejected because:\n- ImageAnalysisFailure\n- PostingException\n- AmountMismatch\n- MaxItemAmountExceeded\n- MaxDepositAmountExceeded\n- MaxItemsPerDayExceeded\n- Duplicate\n- PayerRoutingNumberInvalid\n- PayerAccountNumberInvalid\n- CheckNumberInvalid\n- AccountNotFound\n- DepositsNotEnabled\n- InvalidAccountType\n- NotSpecified", "children": [] }, { "name": "positivePayResult", "kind": "optional", "type": "string", "description": "If Positive Pay is enabled, the positive pay status of the check:\n- Pending\n- Authorized\n- Unauthorized\n- Disabled", "children": [] }, { "name": "positivePayMatchId", "kind": "optional", "type": "string", "description": "If Positive Pay is enabled, ID of the positive pay record associated with the payment", "children": [] }, { "name": "postingCode", "kind": "optional", "type": "string", "description": "Code related to the Cross River system transaction tied to the payment. Any value other than “OK” indicates a rejection.", "children": [] }, { "name": "clientBatchId", "kind": "optional", "type": "string", "description": "ID for the batch received from the Cross River lockbox vendor", "children": [] }, { "name": "clientBatchSequence", "kind": "optional", "type": "integer", "description": "Sequence number of the payment inside the batch received from the Cross River lockbox vendor", "children": [] }, { "name": "fedBatchId", "kind": "optional", "type": "string", "description": "ID of the distribution that the check was included in", "children": [] }, { "name": "fedBatchSequence", "kind": "optional", "type": "integer", "description": "Sequence number of the payment inside the distribution", "children": [] }, { "name": "coreTransactionId", "kind": "optional", "type": "string", "description": "Internal Cross River unique ID for the transaction", "children": [] }, { "name": "memoPostId", "kind": "optional", "type": "string", "description": "Unique identifier for the memo post. This ID is in GUID format.", "children": [] }, { "name": "originalPaymentId", "kind": "optional", "type": "string", "description": "The original payment ID, when a check has been returned or redeposited", "children": [] }, { "name": "customerId", "kind": "optional", "type": "string", "description": "The unique ID assigned to a customer when the customer record is created. You need this ID to take action for a specific customer. For example, when opening an account or adding an address to a customer record.\n\nThe ID is in GUID format.", "children": [] }, { "name": "payerRoutingNumber", "kind": "optional", "type": "string", "description": "The payer’s routing number (printed on the check)", "children": [] }, { "name": "payerAccountNumber", "kind": "optional", "type": "string", "description": "The payer’s account number (printed on the check)", "children": [] }, { "name": "payeeName", "kind": "optional", "type": "string", "description": "Name written on the pay to the order of line of the check", "children": [] }, { "name": "checkNumber", "kind": "optional", "type": "string", "description": "The serial number that appears on the check", "children": [] }, { "name": "bofdRoutingNumber", "kind": "optional", "type": "string", "description": "The routing number of the bank where the check was first deposited", "children": [] }, { "name": "sequenceNumber", "kind": "optional", "type": "string", "description": "The check sequence number", "children": [] }, { "name": "amount", "kind": "optional", "type": "Integer", "description": "Money amount that appears on the check", "children": [] }, { "name": "currency", "kind": "optional", "type": "string", "description": "Currency of the check. For example, USD (US dollars)", "children": [] }, { "name": "micr", "kind": "optional", "type": "string", "description": "The magnetic ink character recognition line, consisting of the routing number, account number and check number", "children": [] }, { "name": "recognizedAmount", "kind": "optional", "type": "Integer", "description": "The check amount recognized from the check image via OCR", "children": [] }, { "name": "iqaPassed", "kind": "optional", "type": "Boolean", "description": "True if the check has passed the Fed’s image quality assurance standards, otherwise false", "children": [] }, { "name": "returnCode", "kind": "optional", "type": "string", "description": "The 1-character code indicating the reason for the check return. See the checks request and response codes page for a complete list of values.", "children": [] }, { "name": "hasFrontImage", "kind": "optional", "type": "boolean", "description": "True if the check image file includes the front of the check. Otherwise false.", "children": [] }, { "name": "hasBackImage", "kind": "optional", "type": "boolean", "description": "True if the check image file includes the back of the check. Otherwise false.", "children": [] }, { "name": "isRedeposit", "kind": "optional", "type": "boolean", "description": "True if the check was deposited before. Otherwise false.", "children": [] }, { "name": "policy ", "kind": "optional", "type": "string", "description": "The current availability policy type assigned to the deposit, defining the schedule for making funds available:\n- Standard\n- NewAccount\n- LargeDeposits\n- RedepositedCheck\n- RepeatedOverdrafts\n- OnUs\n- RCNoticeOfUnpaidReturn\n- RCSuspectFraud\n- RCFundingAccountOverdrafts\n- RCUnverifiedEndorsement\n- RCInconsistentInformation\n- RCErasuresOrAlterations\n- RCOutOfDateRoutingNumber\n- RCPostDatedOrStaleDate\n- RCPayingBankNotPaidIndication\n- RCLostOrDamaged\n- FiveDay\n- EmergencyConditions", "children": [] }, { "name": "schedule", "kind": "optional", "type": "array", "description": "Funds availability schedule, determined by the policy, and based on whenever the check was released to the Fed in a distribution. Consists of a day-by-day breakdown based on calendar day, with each day’s availability amount displayed.", "children": [] }, { "name": "createdAt", "kind": "optional", "type": "string", "description": "Date and time the check payment was created. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]", "children": [] }, { "name": "canceledAt", "kind": "optional", "type": "string", "description": "Date and time the check payment was canceled. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]", "children": [] }, { "name": "rejectedAt", "kind": "optional", "type": "string", "description": "Date and time the check payment was rejected. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]", "children": [] }, { "name": "processedAt", "kind": "optional", "type": "string", "description": "Date and time the check payment was processed. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]", "children": [] }, { "name": "completedAt", "kind": "optional", "type": "string", "description": "Date and time the check payment was completed. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]", "children": [] }, { "name": "postedAt", "kind": "optional", "type": "string", "description": "Date and time the check payment was posted In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]", "children": [] }, { "name": "wasReturned", "kind": "optional", "type": "Boolean", "description": "True if the check was returned. Otherwise false.", "children": [] }, { "name": "purpose", "kind": "optional", "type": "string", "description": "Purpose of the deposited check", "children": [] }, { "name": "clientIdentifier", "kind": "optional", "type": "string", "description": "Use this attribute to add your own unique identifying string to a payment call or COS record. This attribute is useful for idempotency purposes.", "children": [] }, { "name": "depositBusinessDate", "kind": "optional", "type": "string", "description": "The business date of the deposit in the format of yymmdd. This date is usually Day 1 of the schedule for making the funds available. If the check is deposited after the day's deposit cut-off time, Day 1 might be a different date. In that case, the processedAt date is Day 1.", "children": [] }, { "name": "lockboxVendorId", "kind": "optional", "type": "string", "description": "ID of the lockbox service receiving the paper checks and sending them via ICL to Cross River", "children": [] }, { "name": "productId", "kind": "optional", "type": "string", "description": "ID in GUID format of your specific product type on which the Cross River account is based. Provided by Cross River. ", "children": [] }, { "name": "partnerId", "kind": "optional", "type": "string", "description": "Your unique ID in the Cross River system. This ID is in GUID format.", "children": [] }, { "name": "lastModifiedAt", "kind": "optional", "type": "string", "description": "Internal Cross River value. Date and time the database entry was last modified. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]", "children": [] } ], "hasTryItOut": false, "autoGeneratedAnchorSlug": "endpoint-checksv1paymentssimulated-inbound-returns", "legacyHash": "PBzz4s3FwLCp5OdQctPdg" } ``` :::