Card payments
P2C is the Cross River payment-to-card solution for disbursement of funds. P2C allows merchants to transfer money to and from debit card accounts. These transfers happen through participating card networks.
As a Cross River merchant partner, you can use these P2C APIs:
-
Cards
-
iFrame
-
Transactions
-
FX rates
-
OFAC
-
Webhooks
When accessing card payments APIs, specify the following scope: crbapi.
Card authorization and compliance
P2C processing complies with PCI standards. Cross River uses only encrypted token information throughout our system. Any card number we use to transfer funds is meant for temporary access only during a transaction request.
Using a card token to call APIs
Cross River is careful about securing debit card numbers. This section describes how keep cards secure by using tokens.
Tokens are a security measure. Stored by the merchant, a token identifies a payment card in place of an actual card number.
Sign up
When you sign up a card in P2C, the API response includes a card token. We recommend that you use that token in your API calls to identify the debit card. Meaning, the card token is the identifier that you use between your system and Cross River. This helps ensure the safe transfer of funds to the cardholder.
Receiving a card token
When you call POST /api/Card to sign up a card, P2C stores the debit card number and returns a token to you.
Using a card token to perform transactions
When you POST a pull or push transaction, send the cardToken, amount, and RequestId in the request body.
When P2C receives the POST request, it uses the token to retrieve the debit card number and performs the transaction. The API response includes the card token, amount transferred, and a transaction status that indicates success/failure.
Verifying a token
To confirm that communication with an application and the API is working, call GET /api/SignupCard/TestOauth. This verifies that there aren't any allowlist or network issues between systems. If it is working, the API returns a simple message.
Webhook events
When an event happens, P2C triggers a webhook. Webhooks contain real-time notifications. Webhooks update you on the status of your cards. Register the callback URL once for all webhook events. The API sends these updates, which include full event details, to your system. This eliminates the need to poll the API to discover changes.
Status updates
Go to our status page and subscribe to alerts, which lets you:
-
Monitor current API status
-
View incident reports
-
Get notified about scheduled maintenance.
Access our sandbox
|
URL |
Description |
|---|---|
|
https://pushtopaystaging.crbnj.net/swagger/ui/index#/ |
Push APIs |
|
https://pullfromcardapistg.crbnj.net/swagger/ui/index#/ |
Pull APIs |
To access the sandbox, see the Get started page and follow the instructions to register, authenticate, and start working.
Production environment (base) URLs
|
URL |
Description |
|---|---|
| https://pushtopay.crbnj.net |
Push APIs |
| https://pullfromcardapi.crbnj.net |
Pull APIs |
Card network response codes
Card networks return response codes to approve or decline a transaction. They follow the standards set by the International Organization for Standardization (ISO) 8583. This standard defines a specific message format so that different systems can communicate. Every network can adapt the standard for its own use.
Have the funds been transferred?
The following response codes determine if funds were transferred at the end of the transaction.
-
00 - a successful funds transfer
-
91 - this error while processing the transaction means the transaction status is unknown. The issue is on the side of the issuer. If this happens, do not attempt to retry the transaction. Instead, wait until the next day and check the status in the daily settlement file. Contact p2p.support@crossriver.com.
Pull transaction retried too often
To promote good user behavior, Visa and MasterCard run integrity programs. These prevent negative impact on cardholders and processing systems caused by bad authorizations. Before you retry a pull transaction, check the table below.
Card issuer response codes table
| Reason code | Description |
Suggested Action |
|---|---|---|
|
00 |
Approved |
|
|
01 |
Refer to card issuer |
|
|
02 |
Refer to card issuers special conditions |
|
|
03 |
Invalid merchant |
Do not try the transaction again immediately. Contact: p2p.support@crossriver.com. |
|
04 |
Pickup |
Trying again is not permitted with the same PAN or token. Ask for an alternate payment method from the customer and/or advise the cardholder to contact their issuer. |
|
05 |
Do not honor |
Advise the cardholder to contact their issuer. |
|
06 |
General error |
|
|
07 |
Pickup card, special conditions |
|
|
08 |
Honor with identification |
|
|
09 |
Request in progress |
|
|
10 |
Partial amount approved |
|
|
11 |
VIP approval |
|
|
12 |
Invalid transaction |
Trying again is not permitted. Check for potential fraud or issues with the merchant terminal.
|
|
13 |
Invalid amount (currency conversion field overflow) or amount exceeds maximum for card program |
|
|
14 |
Invalid account number (no such number) |
Trying again is not permitted with the same PAN or token.
|
|
15 |
No such issuer |
|
|
16 |
Approved, update track 3 |
|
|
17 |
Customer cancellation |
|
|
18 |
Customer dispute |
|
|
19 |
Re-enter transaction |
|
|
20 |
Invalid response |
|
|
21 |
No action taken |
|
|
22 |
Suspected malfunction |
|
|
23 |
Unacceptable transaction fee |
|
|
24 |
File update not supported by receiver |
|
|
25 |
Unable to locate record on file |
|
|
26 |
Duplicate file update record, old record replaced |
|
|
27 |
File update field edit error |
|
|
28 |
File is temporarily unavailable |
|
|
29 |
File update not successful, contact acquirer |
|
|
30 |
Format error |
Contact: p2p.support@crossriver.com. |
|
31 |
Bank not supported |
Contact: p2p.support@crossriver.com. |
|
32 |
Completed partially |
|
|
33 |
Expired card |
|
|
34 |
Suspected fraud |
|
|
35 |
Card acceptor, contact acquirer |
|
|
36 |
Restricted card |
|
|
37 |
Card acceptor, call acquirer security |
|
|
38 |
Allowed PIN - tries exceeded |
|
|
39 |
No credit account |
|
|
40 |
Requested function not supported |
Contact: p2p.support@crossriver.com. |
|
41 |
Merchant should retain card (card reported lost) |
|
|
42 |
No universal account |
|
|
43 |
Merchant should retain card (card reported stolen) |
Trying again is not permitted with the same PAN or token. Ask for an alternate payment method from the customer and/or advise the cardholder to contact their issuer. |
|
51 |
Insufficient funds |
Merchant can try again for a lesser amount, or they can try again later. This allows the cardholder to fund their debit account or pay down their credit account.
Note
Merchants can reduce NSF declines by implementing the Partial Authorization service. |
|
52 |
No checking account |
Advise the cardholder to contact their issuer. |
|
53 |
No savings account |
|
|
54 |
Expired card |
|
|
55 |
Incorrect PIN |
|
|
56 |
No card record |
|
|
57 |
Transaction not permitted for cardholder |
Trying again is not permitted with the same PAN or token. Ask for an alternate payment method from the customer and/or advise the cardholder to contact their issuer. |
|
58 |
Transaction not allowed at terminal |
Contact: p2p.support@crossriver.com. |
|
59 |
Suspected fraud |
Advise the cardholder to contact their issuer. Try again with the same PAN or token after the cardholder confirms. |
|
61 |
Activity amount limit exceeded |
To allow the limits to reset, don't retry the transaction the same day. Advise the cardholder to call their issuing bank to find out the limit and reason for the decline. |
|
62 |
Restricted card - for example, in country exclusion table |
We don't recommend trying again immediately with the same PAN or token. Try again after the customer confirms the restriction has been removed. |
|
63 |
Security violation |
|
|
65 |
Activity count limit exceeded |
To allow the limits to reset, don't try the transaction again the same day. Advise the cardholder to contact their issuer. |
|
68 |
Response received too late |
|
|
75 |
Allowable number of PIN entry tries exceeded |
|
|
76 |
Unable to locate previous message (no match on retrieval reference) |
|
|
77 |
Previous message located for a repeat or reversal, but data is inconsistent with original message |
|
|
78 |
"Blocked, first used" (transaction is from a new card and the card wasn't properly unblocked) |
If the cardholder confirms that the card has been activated or reactivated, the merchant can try the transaction again. |
|
80 |
Visa transactions: credit issuer unavailable - private label and check acceptance: invalid date |
|
|
81 |
PIN cryptographic error found (error found by VIC security module during PIN decryption) |
|
|
82 |
Negative CAM, dCVV, iCVV, or CVV results |
Track attempts for potential fraud and check verification values. Focus on CVV. |
|
83 |
Unable to verify PIN |
|
|
85 |
No reason to decline a request for account number verification, address verification, CVV2 verification or a credit voucher or merchandise return |
|
|
91 |
Issuer unavailable or switch inoperative (STIP not applicable or available for this transaction) |
In these cases, don't attempt to retry the transaction. Instead, wait until the next day and check the status in the daily settlement file. Contact: p2p.support@crossriver.com. |
|
92 |
Destination can't be found for routing |
Trying again immediately with the same PAN or token is not allowed. Try again after the customer confirms the restriction has been removed. |
|
93 |
Transaction can't be completed, violation of law |
|
|
94 |
Duplicate transmission |
|
|
95 |
Reconcile error |
|
|
96 |
System malfunction, or certain field error conditions |
Contact: p2p.support@crossriver.com. |
|
B1 |
Surcharge amount not permitted on Visa cards (US acquirers only) |
|
|
N0 |
Force STIP |
|
|
N3 |
Cash service not available |
|
|
N4 |
Cashback request exceeds issuer limit |
|
|
N7 |
Decline for CVV2 failure |
|
|
P2 |
Invalid biller information |
|
|
P5 |
PIN change/unblock request declined |
|
|
P6 |
Unsafe PIN |
|
|
Q1 |
Card authentication failed |
|
|
R0 |
Stop payment order |
|
|
R1 |
Revocation of authorization order |
|
|
R3 |
Revocation of all authorization orders |
|
|
XA |
Forward to issuer |
|
|
XD |
Forward to issuer |
|
|
Z3 |
Unable to go online |
|
Error codes
| Error code | Description |
|---|---|
| 1000 validation | A field in the message didn't pass validation. See the description for more information. |
| 2000 application | The message format is incorrect. |
| 3000 security | A security issue occurred. |
| 9999 system | An internal server system error occurred. |
