Send card payments

what you will learn ✅ how to create a card token ✅ how to send a push payment (send funds to a card) ✅ how to send a pull payment (request funds from a card) ✅ how to test rejected scenarios if you are new to card payments, check out the card payments docid\ y 2uvmzgochmtepeo4ipy overview this tutorial assumes familiarity with apis for more information, visit api basics docid\ zg9cjgpbh9nmhcoit5w3a this tutorial uses these api endpoints api description card tokens docid\ cff80nphrpp3buz2ycqra creates a card token by validating the card with the card network send payments docid\ c6cjurm0nl noy4oej8gu sends a push or pull payment to or from a debit card payments by id docid 1xhjaplurdjmikktx29 g retrieves payment details before you begin make sure you have api credentials docid\ z mvwov p00 xx082nabk your partner id your product id an account number register docid\ gbutukmrauaj8doqt8t2o the following webhook events webhook description cardpayments card approved card token authorization approved by the card network cardpayments card rejected card token authorization rejected by the card network cardpayments payment cleared payment passed hold evaluations and is being processed cardpayments payment completed payment transaction successfully completed cardpayments payment rejected payment transaction rejected by the issuing bank or network cardpayments payment failed payment failed to submit (validation error or system issue) you should be familiar with these terms term definition card token a secure representation of a card number that can be used for transactions without storing the pan pan primary account number the full card number on the front of a debit card push payment sending funds from your account to a cardholder's debit card pull payment requesting funds from a cardholder's debit card to your account corresponding entity information about the sender (for push) or receiver (for pull) of funds create a card token before you can send a payment, you must create a card token card tokenization converts the cardholder's pan (card number) into a secure token cross river validates the card with the card network this confirms it can receive or send payments cross river does not store card numbers once tokenized, all future transactions use the token in this tutorial, you will tokenize a test card for alice johnson you can use sample cards for testing docid\ ojkin15ezztokxdlwb3dn in the sandbox environment call post /cardpayments/v1/cardtokens for this call, these attributes are required attribute description productid your unique product id in cos accountnumber the account number associated with this card token firstname cardholder's first name (1 35 characters) lastname cardholder's last name (1 35 characters) pan the full card number expirationmonth card expiration month (1 12) expirationyear card expiration year (4 digits) important we strongly recommend that you include an idempotency docid\ xqc2lrsg0xvv 9nmkqxkk in the request header to prevent duplicate card tokens in case of a failure the address object is optional but recommended when provided, the card network may perform address verification post /cardpayments/v1/cardtokens request post /cardpayments/v1/cardtokens { "productid" "31cae717 408e 4813 a6b1 ad6600e48632", "accountnumber" "2287979807", "clientidentifier" "token alice 001", "firstname" "alice", "lastname" "johnson", "address" { "street1" "456 oak avenue", "street2" "apt 12b", "city" "portland", "state" "or", "postalcode" "97201", "countrycode" "us" }, "phone" "5035551234", "emailaddress" "alice johnson\@example com", "pan" "5102589999999905", "expirationmonth" 12, "expirationyear" 2028, "cvv" "123" } a successful api call returns a json response containing the card token details key attributes in the response id the unique card token id token the tokenized representation of the card (use this for payments) authorizationstatus either approved or rejected capabilities shows what payment types the card supports post /cardpayments/v1/cardtokens response { "id" "26acd726 dade 4064 996a b42b00b634df", "partnerid" "82a1cfb9 de92 4cc2 8a74 ad6600e36d7a", "productid" "31cae717 408e 4813 a6b1 ad6600e48632", "accountnumber" "2287979807", "token" "11fb445c487140a9bea51457a796172a000000", "authorizationstatus" "approved", "statusreasoncode" "00", "statusreasondescription" "approved and completed successfully", "isauthorized" true, "firstname" "alice", "lastname" "johnson", "address" { "street1" "456 oak avenue", "street2" "apt 12b", "city" "portland", "state" "or", "postalcode" "97201", "countrycode" "us" }, "isaddressverified" false, "accountnameinquiryused" "used", "accountnameinquiryresult" "match", "phone" "5035551234", "emailaddress" "alice johnson\@example com", "binnumber" "510258", "panlastfour" "9905", "expirationmonth" 12, "expirationyear" 2028, "cardfingerprint" "7bleadlya+3nxdukox6wje0gkuhvenizuojffjvd0munyh4p3voov0w5lx3jw4h75omx50mirts6xnpcxlx/2w==", "isexpired" false, "cardbrand" "mastercard", "capabilities" { "fastfundssupported" true, "domesticpushenabled" true, "domesticpullenabled" true, "internationalpushenabled" false, "internationalpullenabled" false }, "issuercountrycode" "us", "clientidentifier" "token alice 001", "createdat" "2026 05 10t15 30 23 6206088 04 00", "isactive" true, "authorizedat" "2026 05 10t15 30 24 1757549 04 00", "lastmodifiedat" "2026 05 10t15 30 24 1757549 04 00" } the authorizationstatus of approved confirms that the card network validated this card you can use it for payments check the capabilities object to see which payment types are supported the cardpayments card approved webhook event is triggered when the card network approves the card token sample cardpayments card approved event { "id" "7af80bc3 4f1c 4842 b60e ad9400fb59db", "eventname" "cardpayments card approved", "status" "pending", "partnerid" "82a1cfb9 de92 4cc2 8a74 ad6600e36d7a", "createdat" "2026 05 10t15 30 24 623 04 00", "resources" \[ "cardpayments/v1/cardtokens/26acd726 dade 4064 996a b42b00b634df" ], "details" { "cardid" "26acd726 dade 4064 996a b42b00b634df", "clientidentifier" "token alice 001", "productid" "31cae717 408e 4813 a6b1 ad6600e48632", "cardbrand" "mastercard", "panlastfour" "9905", "authorizationstatus" "approved" } } send a push payment push payments send funds from your cross river account to a cardholder's debit card funds typically reach the cardholder within minutes timing depends on the card network and issuing bank in this example, you will send $25 00 from your account to alice johnson's card call post /cardpayments/v1/payments for this call, these attributes are required attribute description accountnumber your cross river account number (funds will be debited from this account) cardtoken the token from the card token creation response amount the amount in cents (e g , 2500 = $25 00) paymenttype set to push for sending funds to a card businesstype two character code indicating the transaction type (e g , p2p , b2c , b2b ) amounts are specified in cents without decimal points for example, $25 00 is written as 2500 post /cardpayments/v1/payments request (push) post /cardpayments/v1/payments { "productid" "31cae717 408e 4813 a6b1 ad6600e48632", "cardtoken" "11fb445c487140a9bea51457a796172a000000", "accountnumber" "2287979807", "amount" 2500, "paymenttype" "push", "correspondingentity" { "firstname" "alice", "lastname" "johnson", "externalaccountidentifier" " 9905", "address" { "street1" "456 oak avenue", "street2" "apt 12b", "city" "portland", "state" "or", "postalcode" "97201", "countrycode" "us" } }, "businesstype" "p2p", "clientidentifier" "payment push 001" } a successful api call returns a json response with the payment details the status attribute shows the current payment state for a newly created payment, the status is typically created post /cardpayments/v1/payments response (push) { "id" "d706c741 e556 4101 a849 b42b00bfd7e9", "clientidentifier" "payment push 001", "amount" 2500, "paymenttype" "push", "status" "created", "source" "api", "productid" "31cae717 408e 4813 a6b1 ad6600e48632", "partnerid" "82a1cfb9 de92 4cc2 8a74 ad6600e36d7a", "cardid" "26acd726 dade 4064 996a b42b00b634df", "cardtoken" "11fb445c487140a9bea51457a796172a000000", "cardbrand" "mastercard", "panlastfour" "9905", "issuercountrycode" "us", "correspondingentity" { "firstname" "alice", "lastname" "johnson", "externalaccountidentifier" " 9905", "address" { "street1" "456 oak avenue", "street2" "apt 12b", "city" "portland", "state" "or", "postalcode" "97201", "countrycode" "us" } }, "accountnumber" "2287979807", "businesstype" "p2p", "wasrefunded" false, "createdat" "2026 05 10t15 35 28 8271201 04 00", "limitseligibleon" "2026 05 10t15 35 28 8271201 04 00", "lastmodifiedat" "2026 05 10t15 35 28 9388613 04 00" } the status of created indicates the payment was accepted and is being processed the payment is not complete yet push payment webhook flow the payment goes through multiple stages, each triggering a webhook event payment cleared the cardpayments payment cleared event fires when the payment passes internal hold evaluations the system then submits it to the card network sample cardpayments payment cleared event { "id" "8c2a3b12 16c5 49db 84d8 b38a00fa1b2c", "eventname" "cardpayments payment cleared", "status" "pending", "partnerid" "82a1cfb9 de92 4cc2 8a74 ad6600e36d7a", "createdat" "2026 05 10t15 35 29 417 04 00", "resources" \[ "cardpayments/v1/payments/d706c741 e556 4101 a849 b42b00bfd7e9" ], "details" { "paymentid" "d706c741 e556 4101 a849 b42b00bfd7e9", "paymenttype" "push", "amount" "2500", "retrievalreferenceid" null, "tracenumber" null, "reasoncode" null, "reasondescription" null, "clientidentifier" "payment push 001", "coretransactionid" "18b8597a 393f 483d 9897 b42c00aa5788" } } payment completed the cardpayments payment completed event fires when the payment is approved this confirms the funds have been successfully transferred sample cardpayments payment completed event { "id" "9f3e5c67 9dd3 48e1 9488 b1720104c696", "eventname" "cardpayments payment completed", "status" "pending", "partnerid" "82a1cfb9 de92 4cc2 8a74 ad6600e36d7a", "createdat" "2026 05 10t15 35 32 150 04 00", "resources" \[ "cardpayments/v1/payments/d706c741 e556 4101 a849 b42b00bfd7e9" ], "details" { "paymentid" "d706c741 e556 4101 a849 b42b00bfd7e9", "paymenttype" "push", "amount" "2500", "retrievalreferenceid" "413715103005", "tracenumber" "103005", "reasoncode" "00", "reasondescription" "approved", "clientidentifier" "payment push 001", "coretransactionid" "18b8597a 393f 483d 9897 b42c00aa5788" } } the reasoncode of 00 and reasondescription of approved confirm the payment was successful send a pull payment pull payments request funds from a cardholder's debit card to your cross river account this is commonly used for collecting payments from customers in this example, you will request $15 50 from alice johnson's card call post /cardpayments/v1/payments the request is nearly identical to a push payment, except set paymenttype to pull the correspondingentity represents the payer (the person whose card is being charged) post /cardpayments/v1/payments request (pull) post /cardpayments/v1/payments { "productid" "31cae717 408e 4813 a6b1 ad6600e48632", "cardtoken" "11fb445c487140a9bea51457a796172a000000", "accountnumber" "2287979807", "amount" 1550, "paymenttype" "pull", "correspondingentity" { "firstname" "alice", "lastname" "johnson", "externalaccountidentifier" " 9905", "address" { "street1" "456 oak avenue", "street2" "apt 12b", "city" "portland", "state" "or", "postalcode" "97201", "countrycode" "us" } }, "businesstype" "p2p", "clientidentifier" "payment pull 001" } the response structure is the same as push payments, with paymenttype set to pull post /cardpayments/v1/payments response (pull) { "id" "f8c4d823 7a21 4956 b7e2 c93b01aef4d2", "clientidentifier" "payment pull 001", "amount" 1550, "paymenttype" "pull", "status" "created", "source" "api", "productid" "31cae717 408e 4813 a6b1 ad6600e48632", "partnerid" "82a1cfb9 de92 4cc2 8a74 ad6600e36d7a", "cardid" "26acd726 dade 4064 996a b42b00b634df", "cardtoken" "11fb445c487140a9bea51457a796172a000000", "cardbrand" "mastercard", "panlastfour" "9905", "issuercountrycode" "us", "correspondingentity" { "firstname" "alice", "lastname" "johnson", "externalaccountidentifier" " 9905", "address" { "street1" "456 oak avenue", "street2" "apt 12b", "city" "portland", "state" "or", "postalcode" "97201", "countrycode" "us" } }, "accountnumber" "2287979807", "businesstype" "p2p", "wasrefunded" false, "createdat" "2026 05 10t15 40 15 2134567 04 00", "limitseligibleon" "2026 05 10t15 40 15 2134567 04 00", "lastmodifiedat" "2026 05 10t15 40 15 3245678 04 00" } pull payments follow the same webhook flow as push payments (cleared → completed), with the same event structure test rejected scenarios you can test various rejection scenarios in the sandbox environment to understand how your application should handle failures simulate rejected card authorization to test a card token rejection, use a test card number that triggers a specific rejection response call post /cardpayments/v1/cardtokens using a test card that will be rejected use the visa test card 4000289999999906 which simulates a card that fails authorization checks post /cardpayments/v1/cardtokens request (rejected) post /cardpayments/v1/cardtokens { "productid" "31cae717 408e 4813 a6b1 ad6600e48632", "accountnumber" "2287979807", "firstname" "test", "lastname" "reject", "address" { "street1" "123 test street", "city" "new york", "state" "ny", "postalcode" "10001", "countrycode" "us" }, "pan" "4000289999999906", "expirationmonth" 12, "expirationyear" 2028, "cvv" "123" } the response shows authorizationstatus of rejected post /cardpayments/v1/cardtokens response (rejected) { "id" "ee7870ba 5ef7 4700 92ed bed8a77abe7c", "partnerid" "82a1cfb9 de92 4cc2 8a74 ad6600e36d7a", "productid" "31cae717 408e 4813 a6b1 ad6600e48632", "accountnumber" "2287979807", "token" null, "authorizationstatus" "rejected", "statusreasoncode" "14", "statusreasondescription" "invalid card number", "isauthorized" false, "firstname" "test", "lastname" "reject", "panlastfour" "9906", "cardbrand" "visa", "isactive" false, "createdat" "2026 05 10t15 45 23 6206088 04 00" } the cardpayments card rejected webhook event is triggered sample cardpayments card rejected event { "id" "3c8f6a21 dc90 48ea b642 b04a0126580f", "eventname" "cardpayments card rejected", "status" "pending", "partnerid" "82a1cfb9 de92 4cc2 8a74 ad6600e36d7a", "createdat" "2026 05 10t15 45 24 417 04 00", "resources" \[ "cardpayments/v1/cardtokens/ee7870ba 5ef7 4700 92ed bed8a77abe7c" ], "details" { "cardid" "ee7870ba 5ef7 4700 92ed bed8a77abe7c", "clientidentifier" null, "productid" "31cae717 408e 4813 a6b1 ad6600e48632", "cardbrand" "visa", "panlastfour" "9906", "authorizationstatus" "rejected" } } simulate rejected payment to test a payment rejection (after successful card tokenization), provide invalid or missing required data call post /cardpayments/v1/payments with missing required fields in the correspondingentity object post /cardpayments/v1/payments request (rejected) post /cardpayments/v1/payments { "productid" "31cae717 408e 4813 a6b1 ad6600e48632", "cardtoken" "11fb445c487140a9bea51457a796172a000000", "accountnumber" "2287979807", "amount" 1000, "paymenttype" "push", "correspondingentity" { "firstname" "alice", "lastname" "johnson" }, "businesstype" "p2p" } the cardpayments payment failed event fires when the payment fails validation sample cardpayments payment failed event { "id" "eb8f80f8 6e1c 428f be54 b1720103ea5d", "eventname" "cardpayments payment failed", "status" "pending", "partnerid" "82a1cfb9 de92 4cc2 8a74 ad6600e36d7a", "createdat" "2026 05 10t15 50 18 603 04 00", "resources" \[ "cardpayments/v1/payments/eb8f80f8 6e1c 428f be54 b1720103ea5d" ], "details" { "paymentid" "eb8f80f8 6e1c 428f be54 b1720103ea5d", "paymenttype" "push", "amount" "1000", "retrievalreferenceid" null, "tracenumber" null, "reasoncode" "1000", "reasondescription" "addressline1 for corresponding entity is required ", "clientidentifier" null, "coretransactionid" null } } the reasoncode and reasondescription provide details about why the payment failed verify payment status you can retrieve the current status of any payment at any time call get /cardpayments/v1/payments/{id} using the payment id from the response get /cardpayments/v1/payments/d706c741 e556 4101 a849 b42b00bfd7e9 the response includes the current payment status and all transaction details get /cardpayments/v1/payments/{id} response { "id" "d706c741 e556 4101 a849 b42b00bfd7e9", "clientidentifier" "payment push 001", "amount" 2500, "paymenttype" "push", "status" "completed", "source" "api", "productid" "31cae717 408e 4813 a6b1 ad6600e48632", "partnerid" "82a1cfb9 de92 4cc2 8a74 ad6600e36d7a", "cardid" "26acd726 dade 4064 996a b42b00b634df", "cardtoken" "11fb445c487140a9bea51457a796172a000000", "cardbrand" "mastercard", "panlastfour" "9905", "retrievalreferenceid" "413715103005", "tracenumber" "103005", "statusreasoncode" "00", "statusreasondescription" "approved", "issuercountrycode" "us", "correspondingentity" { "firstname" "alice", "lastname" "johnson", "externalaccountidentifier" " 9905", "address" { "street1" "456 oak avenue", "street2" "apt 12b", "city" "portland", "state" "or", "postalcode" "97201", "countrycode" "us" } }, "accountnumber" "2287979807", "businesstype" "p2p", "wasrefunded" false, "createdat" "2026 05 10t15 35 28 8271201 04 00", "completedat" "2026 05 10t15 35 32 4567890 04 00", "limitseligibleon" "2026 05 10t15 35 28 8271201 04 00", "lastmodifiedat" "2026 05 10t15 35 32 4567890 04 00" } the status of completed and completedat timestamp confirm the payment successfully processed