Card payments

Card management

13min

Use Cross River card management APIs to sign up a new payee card, find out details about a payee card, and to activate or deactivate a card.

Get started with Cross River APIs.

The endpoints listed in this table are described in detail in the sections below.

Action

API Call

Description

Add a card

POST /api/Card

Signs up a new payee card

Sign up a card via an iFrame

POST /api/iFrameConfiguration BuildSignupCardUrl

Renders an iFrame into your website. Then, you can add the payee's card details into the frame.

Generate an iFrame OTC signup card

POST /api/iFrameConfiguration GenerateOtcSignupCard

Returns the parameters you need to build an iFrame web address (URL).

Get card information

GET /api/Card

Returns details about payees' cards

Get card details by card token

GET /api/Card/{cardToken}

Returns a payee's card details

Activate and deactivate cards

PUT /api/Card

Turn a payee's card on or off

Validate wallet account

POST /api/PaymentInstrument

Signs up a wallet account

Add a card

Signs up a new consumer payment card to the merchant's account.

When you call this endpoint, the card payments API stores the card number and returns a token. The API uses the token to identify the card, in place of the actual card number. Tokens provide a security measure to help prevent criminals from accessing card numbers.

This API call triggers Account name inquiry (ANI) and Address verification (AVS). These are fraud and risk detection services supported by Cross River.

POST
Request
Response
Body Parameters
requestId
required
String
The GUID that enables the application to link request with response
firstName
required
String
Cardholder first name
lastName
required
String
Cardholder last name
sourceSenderId
required
String
The GUID that identifies the merchant partner
ownerExternalId
optional
String
A 4-digit code, assigned by the merchant, to identify the cardholder
address1
optional
String
Primary location details of cardholder. For instance, street name, house or building number, and PO box. Maximum 255 characters.
address2
optional
String
Secondary location details of cardholder. For instance, number of apartment or floor. Maximum 255 characters.
city
optional
String
Name of the cardholder's city
countryCode
optional
String
2-letter country code
state
optional
String
2-letter code of the cardholder's state
zipCode
optional
String
Cardholder's 5-digit US postal code
phoneNumber
optional
String
Cardholder's phone number; 10 digits, for instance, 2015551234 (no dashes)
email
optional
String
A valid cardholder email address, for example, [email protected]
creditCardNumber
required
String
The 15- or 16-digit number found on the front or back of a credit card
expirationMonth
required
String
Card expiration month, 2-digits, numeric
expirationYear
required
String
Card expiration year, 2-digits, numeric
cvv
required
String
The personal customer code on the card. Add the CVV to a function call only when you add a card (POST /api/Card). The API never returns the CVV when you perform a GET or PUT call.


Set up an iFrame on a merchant site

Makes an iFrame display on your merchant website. Once the iFrame is added, you can enter payee card information directly into the iFrame.

IMPORTANT This function will be deprecated. See the template-based way of generating iFrame code.

POST
Request
Response
Body Parameters
requestId
required
String
The GUID that enables the application to link request with response
customerReferenceNumber
required
String
4-digit code the merchant assigns
domain
required
String
The name of a valid top-level internet domain where consumers will use the iFrame. For example, myfintech.com. This domain must appear in the Cross River allowlist.
successContinueNavigationPoint
optional
String
The landing page you are directed to if the sign up was successful
failureContinueNavigationPoint
optional
String
The landing page you are directed if the sign-up wasn't succeessful
sourceSenderId
optional
String
The GUID that identifies the merchant partner
firstName
optional
String
Cardholder first name
lastName
optional
String
Cardholder last name
address1
optional
String
Primary location details of cardholder. For instance, street name, house or building number, and PO box. Maximum 255 characters.
address2
optional
String
Secondary location details of cardholder. For instance, number of apartment or floor. Maximum 255 characters.
city
optional
String
Name of the cardholder's city
state
optional
String
2-letter code of the cardholder's state
countryCode
optional
String
2-letter country code
zipCode
optional
String
Cardholder's 5-digit US postal code.
email
optional
String
A valid cardholder email address, for example, [email protected]
phoneNumber
optional
String
Cardholder's phone number; 10 digits, for instance, 2015551234 (no dashes)
showOptionalFields
optional
Boolean
True if optional fields will appear in the iFrame, otherwise false


Generate an iFrame OTC signup card

Returns the parameters you need to build an iFrame web address (URL). This endpoint generates the iFrame code snippet dynamically. It does this based on a merchant's specific template and card payments environment. The OTC is a one-time code.

For details on how to customize and embed an iFrame into your merchant website, see the iFrame instructions .

POST
Request
Response
Body Parameters
templateId
required
String
The GUID that identifies the template
domain
required
String
The name of a valid top-level internet domain where consumers will use the iFrame. For example, myfintech.com. This domain must appear in the Cross River allowlist.


Get card information

Returns information about payment cards of consumers signed up to the merchant's account.

Add query parameters to filter the response the API returns to all GET calls.

Use pagination to control presentation of your results.

GET
Request
Body Parameters
dateAddedFrom
optional
String
Date and time from which cards were added (for the beginning of a date range query). Format: YYYY-MM-DDThh:mm:ss, for example, 2022-10-01T01:30:00.
dateAddedTo
optional
String
Date and time up to which cards were added (for the end of a date range query). Format: YYYY-MM-DDThh:mm:ss, for example, 2022-10-01T01:30:00.
sourceSenderId
optional
String
The GUID that identifies the merchant partner
firstName
optional
String
Cardholder first name
lastName
optional
String
Cardholder last name
isActive
optional
Boolean
True if the card is active, otherwise false
cardCompany
optional
String
Name of the payment card network: - Visa - Mastercard


Response attributes

The response attributes for this call are the same as for Add a card.

Get card details by card token

Returns the parameter values defining a card authorized for transactions with a merchant partner. You get card details using the cardToken attribute.

Get a card details by cardToken
GET
Request
Body Parameters
cardToken
required
String
A randomly generated character string that relates to the consumer's payment card (15 to 38 alphanumeric characters). Matches the creditCardToken in the response.


Response attributes

The response attributes for this call are the same as for Add a card.

Deactivate or reactivate a card

Deactivates a consumer's payment card, for instance, if the card is lost or stolen. Reactivates the card, for example, if the card is found.

PUT
Request
Body Parameters
requestId
required
String
The GUID that enables the application to link request with response
sourceSenderId
optional
String
The GUID that identifies the merchant partner
cardToken
required
String
A randomly generated character string that relates to the consumer's payment card (15 to 38 alphanumeric characters). Matches the creditCardToken in the response.
isActive
required
Boolean
True if it is active, otherwise false


Response attributes

The response attributes for this call are the same as for Add a card.

Add a payAlias

Signs up a wallet account for the service. Also, checks whether a wallet account phone number matches a potential recipient or not.

POST
Request
Response
Body Parameters
requestId
required
String
The GUID that enables the application to link request with response
network
required
String
Name of the payment card network: - Visa
payAlias
required
String
A string that represents a consumer wallet account without providing information such as a PAN or phone number. Between 4-50 alphanumeric characters in the format:+firstnamelastname.walletName Currently walletName can be either PayPal or Venmo.
deviceLast4
required
String
Last 4 digits of the consumer phone number. Always 4 numbers.


Related topics

Card payments overview

OFAC screening overview

Foreign exchange rates

API References

Transaction management APIs

OFAC screening APIs

Foreign exchange rates APIs

Request and response codes

Error codes

Tutorials

How to originate a Push to Card transaction

How to originate an Account Funding Transaction (AFT)

🤔
Have a question?
Our super-smart AI, knowledgeable support team and an awesome community will get you an answer in a flash.
To ask a question or participate in discussions, you'll need to authenticate first.



Updated 25 Sep 2024
Doc contributor
Doc contributor
Doc contributor
Did this page help you?
PREVIOUS
Response headers
NEXT
Transaction management
Docs powered by Archbee