Add a Card Account

Add an external card account for a Customer or Recipient.

Endpoint

POST /v1/external-cards

Authorization Header

Authorization: Bearer <access_token>

Request Body

name REQUIRED

string, max length: 100, min length: 1

Name for the Financial Account. This is an informal name used for the account in RocketKOR.

defaultFlag

boolean

default: false

Whether this is the default Financial Account for transactions. If set to true, defaultFlag will be set to false for the previous default Financial Account.

currency

string, max length: 3, min length: 3

default: USD

Currency of the Financial Account. Must be an ISO 4217 alpha 3-character currency code. RocketKOR supports USD and CAD currencies.

accountHolderId REQUIRED

string (UUID)

ID of the entity that owns the Financial Account. The account holder can be a Customer or Recipient.

accountHolderType REQUIRED

string enum, values: CUSTOMER, RECIPIENT

Type of entity referenced by the accountHolderId field.

subtype REQUIRED

string enum, values: DEBIT, CREDIT, PREPAID

Financial Account subtype. CARD accounts can have a subtype of DEBIT, CREDIT, or PREPAID.

card REQUIRED

object

Details for the card attached to the Financial Account.

firstName

string, max length: 40, min length: 1

Customer’s first name as it appears on the card.

middleName

string, max length: 40, min length: 1

Customer’s middle name as it appears on the card.

lastName

string, max length: 40, min length: 1

Customer’s last name as it appears on the card.

cardNumber REQUIRED

string, max length: 19, min length: 11, pattern: [\d]{11,19}

Card number.

expiry REQUIRED

string, required format: YYYY-MM

Expiry date for the card.

billingAddress REQUIRED

object

Billing address for the card.

addressLine1 REQUIRED

string, max length: 50, min length: 1

Address line 1.

addressLine2

string, max length: 50, min length: 1

Address line 2.

addressLine3

string, max length: 50, min length: 1

Address line 3.

city REQUIRED

string, max length: 25, min length: 1

City.

state CONDITIONAL

string, max length: 3, min length: 2

State, province, or territory. Required if country is USA or CAN. Must be an ISO 3166-2 uppercase alpha 2-character or 3-character country subdivision code. For example, Missouri is MO.

country

string, max length: 3, min length: 3

Country. Must be an ISO 3166-1 uppercase alpha 3-character country code. For example, United States is USA.

postalCode REQUIRED

string, max length: 10, min length: 1

ZIP code or postal code. For US addresses, must be a valid value of 5 digits (example: 63368) or 5 digits-4 digits (example: 63368-5555). Can be alphanumeric for other countries.

Returns

Returns the Customer Financial Account details, including a unique ID for the account. For details, see the Card Financial Account object.

SAMPLE REQUEST

				
					{
  "name": "Debit Card",
  "defaultFlag": true,
  "currency": "USD",
  "accountHolderId": "91365a4a-c040-4c37-bb8a-50f46edde48b",
  "accountHolderType": "CUSTOMER",
  "subtype": "DEBIT",
  "card": {
    "firstName": "Mark",
    "middleName": "David",
    "lastName": "Strong",
    "cardNumber": "84563876999",
    "expiry": "2027-12",
    "billingAddress": {
      "addressLine1": "625 Queen St",
      "addressLine2": "",
      "addressLine3": "",
      "city": "Vancouver",
      "state": "BC",
      "country": "Canada",
      "postalCode": "V5K 0A1"
    }
  }
}

SAMPLE RESPONSE

				
					{
  "id": "6a017f06-83a3-44b7-be6f-5e5cae4a9ed7",
  "parentId": "",
  "businessAccountId": "c937109c-6077-4b4e-8d28-c6768e3546c5",
  "name": "Debit Card",
  "defaultFlag": true,
  "state": "ACTIVE",
  "currency": "USD",
  "category": "EXTERNAL",
  "type": "CARD",
  "subtype": "DEBIT",
  "maskedAccountNumber": "******4242",
  "accountHolderId": "91365a4a-c040-4c37-bb8a-50f46edde48b",
  "accountHolderType": "CUSTOMER",
  "createdAt": "2021-07-08T21:10:51.610Z",
  "updatedAt": "2021-07-08T21:10:51.610Z",
  "card": {
    "firstName": "Mark",
    "middleName": "David",
    "lastName": "Strong",
    "cardNumberTail": "6999",
    "expiry": "2027-12",
    "billingAddress": {
      "addressLine1": "625 Queen St",
      "addressLine2": "",
      "addressLine3": "",
      "city": "Vancouver",
      "state": "BC",
      "country": "Canada",
      "postalCode": "V5K 0A1"
    }
  }
}