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
String
required
Cardholder deposit account number
customerId
String
required
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
String
required
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
String
required
Cardholder first name
60 characters maximum
middleName
String
optional
Cardholder middle name
60 characters maximum
lastName
String
required
Cardholder last name

60 characters maximum
suffix
String
optional
Cardholder name suffix

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

23 characters maximum
companyNameOnCard
String
optional
If the card is connected to a business account, the company name
23 characters maximum
shippingType
String
required
How the card is shipped:
- Normal
- Expedited
clientIdentifier
String
optional
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
String
required
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
String
required
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
String
required
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
String
required
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
String
optional
Date/time to return results from.
to
String
optional
Date/time to return results to
partnerId
String
optional
Your ID in the CR system. This ID is in GUID format.
productId
String
optional
Product ID of the cardholder deposit account. This ID is in the GUID format.
accountNumber
String
optional
Deposit account number associated with the card
minAmount
Integer
optional
Minimum transaction dollar amount to return
maxAmount
String
optional
Maximum transaction dollar amount to return
retrievalReferenceNumber
String
optional
Automatically generated reference (alphanumeric)
outboundResponseCode
String
optional
Code describing outbound response. List of codes.
isDebit
Boolean
optional
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

Subledgers

Request and response codes