Initiate check return

Relevant webhooks

For this endpoint be sure you have registered for these webhooks:

Check.Payment.Received

Core.Transaction.Completed

Check.Payment.Sent

API reference

Initiates return of an inbound forward check. An inbound check payment can only be returned after it successfully posts to the Cross River account it was drawn on.

Return of an inbound forward payment is known as an outbound return payment, so the response includes a payment ID.

A Cross River Partner ID is associated with an inbound payment only after it has successfully posted to the receiver’s Cross River account. Therefore, you will not see inbound payments that fail to post for reasons such as an invalid routing number or an active account restriction.

Endpoint: /checks/v1/payments/{id}/returns

POST

https://sandbox.crbcos.com/checks/v1/payments/{id}/returns

Path Parameters

idstringrequired
Description
ID of the inbound check transaction, in GUID format. Find this ID in the Check.Payment.Received webhook paymentId field, raised after the inbound payment posts to the account.

Body Parameters

returnCodestringrequired
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.

Response

idstring
Description
Check payment ID. This ID is in GUID format.
accountNumberstring
Description
Number of the account receiving the check
referenceIdstring
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.
paymentTypestring
Description
The check paymentType indicates whether the check has been presented for payment or has been returned for some reason: - Forward (a check presented for payment, to be sent to the payer bank) - Return (A previous forward item that the payer bank returned)
checkTypestring
Description
Type of check being dealt with. There are several check types: - Standard - OnUs - Treasury - MoneyOrder - FedReserveBank - FedHomeLoan - StateLocalGovt - Certified - Unknown
direction string
Description
Check direction: - Inbound (A check drawn from a COS account, deposited at another bank. See Deposit.) - Outbound (A check deposited into a COS account, drawn from an account at another bank. See Withdrawal.)
statusstring
Description
Status of the check payment. There are several possible payment statuses: - Created - Pending - Hold - Batched - Processing - Completed - Rejected - Canceled
sourcestring
Description
Source of the payment request: - Api - PartnerPortal - OpsPortal - File - System - Lockbox
postingstring
Description
Posting status: - Pending - Posted - Failed - Canceled - Authorized - Authorizing
rejectionReasonstring
Description
Rejected because: - ImageAnalysisFailure - PostingException - AmountMismatch - MaxItemAmountExceeded - MaxDepositAmountExceeded - MaxItemsPerDayExceeded - Duplicate - PayerRoutingNumberInvalid - PayerAccountNumberInvalid - CheckNumberInvalid - AccountNotFound - DepositsNotEnabled - InvalidAccountType - NotSpecified
positivePayResultstring
Description
If Positive Pay is enabled, the positive pay status of the check: - Pending - Authorized - Unauthorized - Disabled
positivePayMatchIdstring
Description
If Positive Pay is enabled, ID of the positive pay record associated with the payment
postingCodestring
Description
Code related to the Cross River system transaction tied to the payment. Any value other than “OK” indicates a rejection.
clientBatchIdstring
Description
ID for the batch received from the Cross River lockbox vendor
clientBatchSequenceinteger
Description
Sequence number of the payment inside the batch received from the Cross River lockbox vendor
fedBatchIdstring
Description
ID of the distribution that the check was included in
fedBatchSequenceinteger
Description
Sequence number of the payment inside the distribution
coreTransactionIdstring
Description
Internal Cross River unique ID for the transaction
memoPostIdstring
Description
Unique identifier for the memo post. This ID is in GUID format.
originalPaymentIdstring
Description
The original payment ID, when a check has been returned or redeposited
customerIdstring
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. The ID is in GUID format.
payerRoutingNumberstring
Description
The payer’s routing number (printed on the check)
payerAccountNumberstring
Description
The payer’s account number (printed on the check)
payeeNamestring
Description
Name written on the pay to the order of line of the check
checkNumberstring
Description
The serial number that appears on the check
bofdRoutingNumberstring
Description
The routing number of the bank where the check was first deposited
sequenceNumberstring
Description
The check sequence number
amountinteger
Description
Money amount that appears on the check
currencystring
Description
Currency of the check. For example, USD (US dollars)
micrstring
Description
The magnetic ink character recognition line, consisting of the routing number, account number and check number
recognizedAmountinteger
Description
The check amount recognized from the check image via OCR
iqaPassedboolean
Description
True if the check has passed the Fed’s image quality assurance standards, otherwise false
returnCodestring
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.
hasFrontImageboolean
Description
True if the check image file includes the front of the check. Otherwise false.
hasBackImageboolean
Description
True if the check image file includes the back of the check. Otherwise false.
isRedepositboolean
Description
True if the check was deposited before. Otherwise false.
policy string
Description
The current availability policy type assigned to the deposit, defining the schedule for making funds available: - Standard - NewAccount - LargeDeposits - RedepositedCheck - RepeatedOverdrafts - OnUs - RCNoticeOfUnpaidReturn - RCSuspectFraud - RCFundingAccountOverdrafts - RCUnverifiedEndorsement - RCInconsistentInformation - RCErasuresOrAlterations - RCOutOfDateRoutingNumber - RCPostDatedOrStaleDate - RCPayingBankNotPaidIndication - RCLostOrDamaged - FiveDay - EmergencyConditions
schedulearray
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.
createdAtstring
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]
canceledAtstring
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]
rejectedAtstring
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]
processedAtstring
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]
completedAtstring
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]
postedAtstring
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]
wasReturnedboolean
Description
True if the check was returned. Otherwise false.
purposestring
Description
Purpose of the deposited check
clientIdentifierstring
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.
depositBusinessDatestring
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.
lockboxVendorIdstring
Description
ID of the lockbox service receiving the paper checks and sending them via ICL to Cross River
productIdstring
Description
ID in GUID format of your specific product type on which the Cross River account is based. Provided by Cross River.
partnerIdstring
Description
Your unique ID in the Cross River system. This ID is in GUID format.
lastModifiedAtstring
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]

curl

curl --location 'https://sandbox.crbcos.com/checks/v1/payments/d147462c-64c4-480a-b80a-b449006b04ff/returns' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "returnCode": "I"
}'

nodejs

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'POST',
  'hostname': 'sandbox.crbcos.com',
  'path': '/checks/v1/payments/d147462c-64c4-480a-b80a-b449006b04ff/returns',
  'headers': {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

var postData =  "{\r\n  \"returnCode\": \"I\"\r\n}";

req.write(postData);

req.end();

python

import http.client

conn = http.client.HTTPSConnection("sandbox.crbcos.com")
payload = "{\r\n  \"returnCode\": \"I\"\r\n}"
headers = {
  'Authorization': 'Bearer <token>',
  'Content-Type': 'application/json'
}
conn.request("POST", "/checks/v1/payments/d147462c-64c4-480a-b80a-b449006b04ff/returns", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

ruby

require "uri"
require "net/http"

url = URI("https://sandbox.crbcos.com/checks/v1/payments/d147462c-64c4-480a-b80a-b449006b04ff/returns")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer <token>"
request["Content-Type"] = "application/json"
request.body = "{\r\n  \"returnCode\": \"I\"\r\n}"

response = https.request(request)
puts response.read_body

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "https://sandbox.crbcos.com/checks/v1/payments/d147462c-64c4-480a-b80a-b449006b04ff/returns"
  method := "POST"

  payload := strings.NewReader(`{
  "returnCode": "I"
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer <token>")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := io.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

200

{
    "id": "f5a8f301-6508-4345-a570-b449006bb824",
    "accountNumber": "2846220461",
    "referenceId": "C133QA018017",
    "paymentType": "Return",
    "checkType": "Unknown",
    "direction": "Outbound",
    "status": "Created",
    "source": "Api",
    "posting": "Pending",
    "postingCode": "OK",
    "coreTransactionId": "70259003-10c1-4ae4-9cec-b449006bb824",
    "memoPostId": "e12d64be-9052-4145-b2a0-b449006bb824",
    "originalPaymentId": "d147462c-64c4-480a-b80a-b449006b04ff",
    "customerId": "05106466-9144-4f3f-8fb1-b345005d18ba",
    "payerRoutingNumber": "021214891",
    "payerAccountNumber": "2846220461",
    "payeeName": "string",
    "checkNumber": "2846220461",
    "bofdRoutingNumber": "021214891",
    "sequenceNumber": "5599498374",
    "amount": 5556,
    "currency": "usd",
    "recognizedAmount": 0,
    "iqaPassed": false,
    "returnCode": "I",
    "hasFrontImage": true,
    "hasBackImage": true,
    "isRedeposit": false,
    "policy": "Standard",
    "schedule": [],
    "createdAt": "2026-05-13T02:32:11.6396438-04:00",
    "wasReturned": false,
    "decisionRequired": false,
    "wasDecisioned": false,
    "productId": "83bed086-8182-4151-a1e3-af5b01362783",
    "partnerId": "cd9c12f4-7691-424a-b38b-af5b0134c611",
    "lastModifiedAt": "2026-05-13T02:32:11.6396701-04:00"
}

400

{
    "errors": [
        {
            "code": 2012,
            "message": "Payment must be status completed or rejected to be returned"
        }
    ]
}