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/V2/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.

SIgn up card request
POST
Request
Response
Body Parameters
requestId
String
required
The GUID that enables the application to link request with response
firstName
String
required
Cardholder first name
lastName
String
required
Cardholder last name
sourceSenderId
String
required
The GUID that identifies the merchant partner
ownerExternalId
String
optional
A 4-digit code, assigned by the merchant, to identify the cardholder
address1
String
optional
Primary location details of cardholder. For instance, street name, house or building number, and PO box. Maximum 255 characters.
address2
String
optional
Secondary location details of cardholder. For instance, number of apartment or floor. Maximum 255 characters.
city
String
optional
Name of the cardholder's city
countryCode
String
optional
2-letter country code
state
String
optional
2-letter code of the cardholder's state
zipCode
String
optional
Cardholder's 5-digit US postal code
phoneNumber
String
optional
Cardholder's phone number; 10 digits, for instance, 2015551234 (no dashes)
email
String
optional
A valid cardholder email address, for example, [email protected]
creditCardNumber
String
required
The 15- or 16-digit number found on the front or back of a credit card
expirationMonth
String
required
Card expiration month, 2-digits, numeric
expirationYear
String
required
Card expiration year, 2-digits, numeric
cvv
String
required
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
String
required
The GUID that enables the application to link request with response
customerReferenceNumber
String
required
4-digit code the merchant assigns
domain
String
required
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
String
optional
The landing page you are directed to if the sign up was successful
failureContinueNavigationPoint
String
optional
The landing page you are directed if the sign-up wasn't succeessful
sourceSenderId
String
optional
The GUID that identifies the merchant partner
firstName
String
optional
Cardholder first name
lastName
String
optional
Cardholder last name
address1
String
optional
Primary location details of cardholder. For instance, street name, house or building number, and PO box. Maximum 255 characters.
address2
String
optional
Secondary location details of cardholder. For instance, number of apartment or floor. Maximum 255 characters.
city
String
optional
Name of the cardholder's city
state
String
optional
2-letter code of the cardholder's state
countryCode
String
optional
2-letter country code
zipCode
String
optional
Cardholder's 5-digit US postal code.
email
String
optional
A valid cardholder email address, for example, [email protected]
phoneNumber
String
optional
Cardholder's phone number; 10 digits, for instance, 2015551234 (no dashes)
showOptionalFields
Boolean
optional
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
String
required
The GUID that identifies the template
domain
String
required
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
String
optional
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
String
optional
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
String
optional
The GUID that identifies the merchant partner
firstName
String
optional
Cardholder first name
lastName
String
optional
Cardholder last name
isActive
Boolean
optional
True if the card is active, otherwise false
cardCompany
String
optional
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
String
required
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
String
required
The GUID that enables the application to link request with response
sourceSenderId
String
optional
The GUID that identifies the merchant partner
cardToken
String
required
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
Boolean
required
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
String
required
The GUID that enables the application to link request with response
network
String
required
Name of the payment card network: - Visa
payAlias
String
required
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
String
required
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)

Updated 10 Feb 2025
Did this page help you?
PREVIOUS
Error Codes
NEXT
Transaction management
Docs powered by Archbee