Add an External 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, min length: 1, max length: 100

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

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. Possible values are:

CUSTOMER Customer Account.
RECIPIENT Recipient Account.

subtype REQUIRED

string enum, values: DEBIT, CREDIT

Type of card.

defaultFlag

boolean, default: false

Whether this is the default Financial Account for transactions.

currency

string, min length: 3, max length: 3

Currency of the Financial Account. Must be an ISO 4217 alpha 3-character currency code.

card REQUIRED

object

Details for the card attached to the Financial Account.

firstName REQUIRED

string, min length: 1, max length: 40

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

middleName

string, min length: 1, max length: 40

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

lastName REQUIRED

string, min length: 1, max length: 40

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

cardNumber REQUIRED

string, min length: 11, max length: 19

Card number.

expiry REQUIRED

string, format: yyyy-MM

Expiry date for the card.

billingAddress

object

Billing address for the card.

addressLine1 REQUIRED

string, min length: 1, max length: 50

Address line 1.

addressLine2

string, min length: 1, max length: 50

Address line 2.

addressLine3

string, min length: 1, max length: 50

Address line 3.

city REQUIRED

string, min length: 1, max length: 25

City.

stateCode CONDITIONAL

string, min length: 2, max length: 3

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 and Ontario is ON.

countryCode REQUIRED

string, min length: 3, max length: 3

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

postalCode REQUIRED

string, min length: 1, max length: 10

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 with a maximum length of 10 characters.

Returns

Returns the External Card Financial Account object. This object contains the Financial Account details, including a unique ID for the account.

SAMPLE REQUEST

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

SAMPLE RESPONSE

				
					{
  "id": "6a017f06-83a3-44b7-be6f-5e5cae4a9ed7",
  "businessAccountId": "c937109c-6077-4b4e-8d28-c6768e3546c5",
  "name": "Debit Card",
  "category": "EXTERNAL",
  "type": "CARD",
  "subtype": "DEBIT",
  "defaultFlag": true,
  "currency": "USD",
  "accountHolderId": "8c8c5119-3abd-42e8-8b37-f8eaaa4afacb",
  "accountHolderType": "CUSTOMER",
  "state": "ACTIVE",
  "maskedAccountNumber": "******4242",
  "verificationStatus": "PENDING",
  "verificationMethod": "PRENOTE",
  "createdBy": {
    "id": "59dff46b-03d3-449b-89bf-b8010770864f",
    "type": "employee"
  },
  "createdAt": "2024-09-20T22:09:31.947Z",
  "updatedBy": {
    "id": "59dff46b-03d3-449b-89bf-b8010770864f",
    "type": "employee"
  },
  "updatedAt": "2024-10-20T22:09:31.947Z",
  "card": {
    "firstName": "Mark",
    "middleName": "David",
    "lastName": "Strong",
    "cardNumber": "123456784242",
    "cardNumberTail": "4242",
    "expiry": "2027-12",
    "billingAddress": {
      "addressLine1": "625 Queen St",
      "addressLine2": "Suite 201",
      "addressLine3": "South Building",
      "city": "Vancouver",
      "stateCode": "BC",
      "countryCode": "CAN",
      "postalCode": "V5K 0A1"
    }
  }
}