Card issuing

10min

Cross River card issuing lets you offer customers different types of debit card products. These products, known as instrument types, include contact-less and virtual cards. CR card issuing in COS uses i2c as the payment processor, with the ability to adapt to other card processors.
Find these APIs in the cardmanagement module of our COS sandbox.
﻿Get started﻿ with Cross River APIs.
This table presents APIs that we describe in detail.
Action
API Call
Description
﻿Create a new card﻿ 
POST /cardmanagement/v1/cards
Requests creation of a new card
﻿Activate a card by card ID  ﻿ 
POST /cardmanagement/v1/cards/{id}/activate
Activates a card for a customer. This is the preferred way to activate a card.
﻿Set an initial card personal identification number (PIN)﻿ 
PUT /cardmanagement/v1/cards/{id}/pin
Sets the customer PIN
﻿Get card details by ID  ﻿ 
GET /cardmanagement/v1/cards/{id}
Returns the details of a specific debit card based on its ID
﻿List card transactions﻿ 
GET /cardmanagement/v1/transactions
Returns information about card transactions based on various query criteria such as payment date or a range of dates, card type or account number
Create a new card
To create a card, you must supply a valid deposit account number along with other card-specific information. The initial card status of a newly submitted card is unactivated. When the card is successfully created the order status is OrderPending.
POST
Request
Response
Body Parameters
accountNumber
required
String
Cardholder deposit account number
customerId
required
String
The unique ID assigned to a customer when the customer record is created (POST /core/v1/cm/customers). 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.
configurationId
required
String
Unique ID for the card configuration profile the card is based on. You get this ID from CR. This ID is in GUID format.
firstName
required
String
Cardholder first name
60 characters maximum
middleName
optional
String
Cardholder middle name
60 characters maximum
lastName
required
String
Cardholder last name

60 characters maximum
suffix
optional
String
Cardholder name suffix

60 characters maximum
phone
optional
Object
Details of the cardholder phone contact information
emailAddress
optional
String
Cardholder email address
60 characters maximum
shippingAddress
required
Object
Address to which a physical card is shipped
billingAddress
required
Object
Address to send credit card bills
nameOnCard
required
String
Cardholder name as it appears on the card

23 characters maximum
companyNameOnCard
optional
String
If the card is connected to a business account, the company name
23 characters maximum
shippingType
required
String
How the card is shipped:
- Normal
- Expedited
clientIdentifier
optional
String
Use this attribute to add your own unique identifying string to a payment call or COS record. This attribute is useful for idempotency purposes.

50 characters maximum.
﻿
Activate a card by card ID
Cards can only be used once they are activated. After creation, the card status is Unactivated. Once you are ready to activate the card for use, call the Activate Card ID endpoint. This is the preferred way to activate a card.
Activate a card by card ID
POST
Request
Path Params
id
required
String
GUID format card ID in the CR system, which is the id attribute value of the response to Create a card. This is not the number that appears on the card
﻿
Response attributes
The response attributes for this call are the same as for Create a new card.
Set initial card PIN
Set an initial debit card personal identification number (PIN) number for withdrawing funds from an ATM and other uses.
To set a card PIN number, the card cannot already have a PIN number set. This means that the card's isPinSet must have a value of false.
PUT
Request
Body Parameters
id
required
String
GUID format card ID in the CR system, which is the id attribute value of the response to Create a card. This is not the number that appears on the card.
pin
required
String
4-digit personal identification number associated with the card for verification purposes during purchase or cash withdrawal transactions.
﻿
Response attributes
The response attributes for this call are the same as for Create a new card.
Get card details by ID
Returns the details of a specific debit card based on its ID.
Get card details by ID
GET
Request
Path Params
id
required
String
GUID format card ID in the CR system, which is the id attribute value of the response to Create a card. This is not the number that appears on the card.

﻿
Response attributes
The response attributes for this call are the same as for Create a new card.
Get transaction details
Returns details about card transactions. The response values below are repeated for each transaction.
Add query parameters to filter the response the API returns to all GET calls.
Use pagination﻿ to control presentation of your results.
GET
Request
Response
Query Parameters
from
optional
String
Date/time to return results from.
to
optional
String
Date/time to return results to
partnerId
optional
String
Your ID in the CR system. This ID is in GUID format.
productId
optional
String
Product ID of the cardholder deposit account. This ID is in the GUID format.
accountNumber
optional
String
Deposit account number associated with the card
minAmount
optional
Integer
Minimum transaction dollar amount to return
maxAmount
optional
String
Maximum transaction dollar amount to return
retrievalReferenceNumber
optional
String
Automatically generated reference (alphanumeric)
outboundResponseCode
optional
String
Code describing outbound response. List of codes.
isDebit
optional
Boolean
True if the card is a debit card, otherwise false.
﻿
Associated webhook events
Event Name
Description
Cards.Card.Activated
Debit card activated
Cards.Card.Closed
Debit card closed
Cards.Card.Created
Debit card created
Cards.Card.Failed
Debit card creation failed
Cards.Card.Pin.Set
PIN set for debit card
Cards.Card.Profile.Changed
Profiled of cardholder changed
Cards.Card.Replaced
New card created to replace an existing card
Cards.Card.Suspended
Debit card use temporarily suspended
Cards.Card.Unsuspended
Suspension removed from debit card
Cards.Transaction.Cleared
Card transaction successfully completed
Cards.Transaction.Authorized
Card transaction approved
Cards.Transaction.Declined
Card transaction not approved
Cards.Transaction.Failed
Card transaction did not succeed
Cards.Transaction.Reversed
Payment credited to the originating account
Cards.Card.Status.Changed
Card state has changed
Related topics
﻿Card issuing management overview﻿ 
﻿Request and response codes﻿ 
﻿Error codes﻿ 
﻿Credit BIN sponsorship﻿ 
﻿Credit Risk Data Reports﻿ 
Tutorials
﻿How to create a card﻿ 
﻿How to activate a card with the card ID﻿ 
﻿How to simulate card management﻿ 

Action	API Call	Description
Create a new card	POST /cardmanagement/v1/cards	Requests creation of a new card
Activate a card by card ID	POST /cardmanagement/v1/cards/{id}/activate	Activates a card for a customer. This is the preferred way to activate a card.
Set an initial card personal identification number (PIN)	PUT /cardmanagement/v1/cards/{id}/pin	Sets the customer PIN
Get card details by ID	GET /cardmanagement/v1/cards/{id}	Returns the details of a specific debit card based on its ID
List card transactions	GET /cardmanagement/v1/transactions	Returns information about card transactions based on various query criteria such as payment date or a range of dates, card type or account number

Event Name	Description
Cards.Card.Activated	Debit card activated
Cards.Card.Closed	Debit card closed
Cards.Card.Created	Debit card created
Cards.Card.Failed	Debit card creation failed
Cards.Card.Pin.Set	PIN set for debit card
Cards.Card.Profile.Changed	Profiled of cardholder changed
Cards.Card.Replaced	New card created to replace an existing card
Cards.Card.Suspended	Debit card use temporarily suspended
Cards.Card.Unsuspended	Suspension removed from debit card
Cards.Transaction.Cleared	Card transaction successfully completed
Cards.Transaction.Authorized	Card transaction approved
Cards.Transaction.Declined	Card transaction not approved
Cards.Transaction.Failed	Card transaction did not succeed
Cards.Transaction.Reversed	Payment credited to the originating account
Cards.Card.Status.Changed	Card state has changed

🤔

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 24 Sep 2024

Did this page help you?

Subledgers

Request and response codes