GuidesChangelog
Guides

Debit Cards

Suggest Edits

Overview

Cards have 2 statuses: orderStatus and status, or card status.
The order status attribute is the current status of the order:

  • Order Pending - The order is pending fulfillment by the processor
  • Completed - The order has been fulfilled by the processor. For physical cards, the card is being printed and mailed to the cardholder
  • Failed - The order failed at the processor level

The status attribute is the activation status of the card and if the card can be used by the card holder:

  • Unactivated - The card has not been activated by the cardholder
  • Active - The card is active and ready for use
  • Suspended - The card is currently suspended
  • Closed - The card is closed
1203

Card Creation

To create a debit card, you must have a valid deposit account number and debit card specific information including the configuration ID. The configuration ID defines the specific instrument type you are creating for your customer.

POST /cardmanagement/v1/cards 
{
  "accountNumber": "1234567890",
  "customerId": "00000000-0000-0000-0000-000000000000",
  "configurationId": "00000000-0000-0000-0000-000000000000",
  "firstName": "John",
  "middleName": "J",
  "lastName": "Smith",
  "suffix": "Jr",  
  "nameOnCard": "John J Smith",
  "emailAddress": "[email protected]",
  "billingAddress": {
    "street1": "123 Maple Lane",
    "street2": "Apt. 1",
    "city": "New York",
    "state": "NY",
    "postalCode": "10025",
    "countryCode": "US"
  },
  "shippingAddress": {
    "street1": "123 Maple Lane",
    "street2": "Apt. 1",
    "city": "New York",
    "state": "NY",
    "postalCode": "10025",
    "countryCode": "US"
  },  
  "phone": {
    "phoneType": "Home",
    "phoneNumber": "5555555555"
  },
  "shippingType": "Normal"
}

A successful request will trigger a response similar to:

{
  "id": "e3c95c36-8719-461b-adc4-ae8a015343e2",
  "partnerId": "00000000-0000-0000-0000-000000000000",
  "productId": "00000000-0000-0000-0000-000000000000",
  "accountNumber": "1234567890",
  "status": "Unactivated",
  "statusReasonCode": "NotSet",
  "firstName": "John",
  "middleName": "J",
  "lastName": "Smith",
  "suffix": "Jr",
  "shippingAddress": {
    "street1": "123 Maple Lane",
    "street2": "Apt. 1",
    "city": "New York",
    "state": "NY",
    "postalCode": "10025",
    "countryCode": "US"
  },
  "billingAddress": {
    "street1": "123 Maple Lane",
    "street2": "Apt. 1",
    "city": "New York",
    "state": "NY",
    "postalCode": "10025",
    "countryCode": "US"
  },
  "phone": {
    "phoneType": "Home",
    "phoneNumber": "5555555555"
  },
  "emailAddress": "[email protected]",
  "nameOnCard": "John J Smith",
  "isPinSet": false,
  "adminBlocked": false,
  "fraudSuspect": false,
  "configurationId": "00000000-0000-0000-0000-000000000000",
  "category": "Debit",
  "paymentInstrument": "PhysicalMSR",
  "processor": "i2c",
  "shippingType": "Normal",
  "orderStatus": "OrderPending",
  "replacementStatus": "NotApplicable",
  "customerId": "00000000-0000-0000-0000-000000000000",
  "createdAt": "2022-05-03T16:35:17.9908544-05:00",
  "lastModifiedAt": "2022-05-03T16:35:18.0308575-05:00"
}

The status of a newly submitted card is Unactivated and the orderStatus is OrderPending. The orderStatus updates to Completed when the order is complete. For physical cards, this indicates that the card has been mailed to the customer.

Card Activation

Cards can only be used once they are activated. To activate the card, call the activate card endpoint.

POST /cardmanagement/v1/cards/{id}/activate

Cards can also be activated using the card number and CVV2 number. A common use case is to allow the cardholder to enter their card details into an online form to activate it.

POST /cardmanagement/v1/cards/activate
{
  "productId":"00000000-0000-0000-0000-000000000000"
  "pan": "9999999999999999",
  "cvv2": "123",
  "postalCode": "10025"
}

📘

The postal code in the above request refers to the card billing address postal code. You can view the shipping and billing addresses by calling GET /cardmanagement/v1/cards/{id} with the card ID.

Card Status Changes

Managing a card program may require you to update card statuses for specific scenarios. For example, you may want to offer your customers added security by allowing them to temporarily suspend a card that has been misplaced. Suspending a card temporarily inactivates it until you remove the suspension. To suspend a card, you call the suspend endpoint.

POST /cardmanagement/v1/cards/{id}/suspend

To revert the card status to Active, call the unsuspend endpoint:

POST /cardmanagement/v1/cards/{id}/unsuspend

Use the close endpoint to close a card. This is used when the customer no longer wishes to have a card and the card was not compromised.

POST /cardmanagement/v1/cards/{id}/close

❗️

Closing a Card

Once the card is closed, it cannot be reactivated.

Some scenarios require you to place an administrative block on a card.
For example, a suspected fraud where you want to prevent the card from further use and you don't want the cardholder to reactivate or replace their card.
The admin-block endpoint allows you to place an administrative block on the card.

POST /cardmanagement/v1/cards/{id}/admin-block

Card Profile

Card profile information such as the Card Name (cardholder name), Mailing Address, Phone and Email Address can be modified using the profile endpoint.

PUT /cardmanagement/v1/cards/{id}/profile 
{
  "firstName": "John",
  "middleName": "J",
  "lastName": "Smith",
  "suffix": "Jr",  
  "emailAddress": "[email protected]",
  "billingAddress": {
    "street1": "123 Maple Lane",
    "street2": "Apt. 1",
    "city": "New York",
    "state": "NY",
    "postalCode": "10025",
    "countryCode": "US"
  },
  "shippingAddress": {
    "street1": "123 Maple Lane",
    "street2": "Apt. 1",
    "city": "New York",
    "state": "NY",
    "postalCode": "10025",
    "countryCode": "US"
  },  
  "phone": {
    "phoneType": "Home",
    "phoneNumber": "5555555555"
  }
}

Card Replacement

Damaged, lost or stolen cards can be replaced using the replace endpoint. Damaged cards remain active until the cardholder activates the replacement card. Lost or stolen cards are immediately closed and a replacement card is issued.

POST /cardmanagement/v1/cards/{id}/replace 
{
  "replaceReason": "FraudCompromised",
  "nameOnCard": "John J Smith",
  "shippingType": "Normal" 
}

Set Card PIN

The personal identification number (PIN) can be set using the pin endpoint.

PUT /cardmanagement/v1/cards/{id}/pin
{
  "pin": "1234"
}

Updated 12 months ago