Link a card

Link a card to an existing Moov account.

Read our accept card payments guide to learn more.

Only use this endpoint if you have provided Moov with a copy of your PCI attestation of compliance.

During card linking, the provided data will be verified by submitting a $0 authorization (account verification) request. If merchantAccountID is provided, the authorization request will contain that account’s statement descriptor and address. Otherwise, the platform account’s profile will be used. If no statement descriptor has been set, the authorization will use the account’s name instead.

It is strongly recommended that callers include the X-Wait-For header, set to payment-method, if the newly linked card is intended to be used right away. If this header is not included, the caller will need to poll the List Payment Methods endpoint to wait for the new payment methods to be available for use.

To use this endpoint from the browser, you’ll need to specify the /accounts/{accountID}/cards.write scope when generating a token.

POST
/accounts/{accountID}/cards
cURL JavaScript
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
curl -X POST "https://api.moov.io/accounts/{accountID}/cards" \
  -H "Authorization: Bearer {token}" \
  -H "X-Wait-For: rail-response" \
  --data-raw '{
    "billingAddress": {
      "addressLine1": "123 Main Street",
      "city": "Denver",
      "country": "US",
      "postalCode": "80301",
      "stateOrProvince": "CO"
    },
    "cardCvv": "123",
    "cardNumber": "4111111111111111",
    "expiration": {
      "month": "01",
      "year": "28"
    },
    "holderName": "Jules Jackson"
  }'\
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
const moov = new Moov(credentialsObject);

const accountID = "accountID";
const cardPayload = {
  billingAddress: {
    addressLine1: "123 Main Street",
    city: "Denver",
    country: "US",
    postalCode: "80301",
    stateOrProvince: "CO"
  },
  cardCvv: "123",
  cardNumber: "4111111111111111",
  expiration: {
    month: "01",
    year: "27",
  },
  holderName: "Jules Jackson"
};

const card = await moov.cards.link(accountID, cardPayload);
200 404 409 422 429
The card was successfully linked.
Describes a card on a Moov account.
{
  "billingAddress": {
    "addressLine1": "123 Main Street",
    "addressLine2": "Apt 302",
    "city": "Boulder",
    "country": "US",
    "postalCode": "80301",
    "stateOrProvince": "CO"
  },
  "bin": "123456",
  "brand": "Discover",
  "cardAccountUpdater": {
    "updateType": "number-update",
    "updatedOn": "2019-08-24T14:15:22Z"
  },
  "cardID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
  "cardOnFile": true,
  "cardType": "debit",
  "cardVerification": {
    "accountName": {
      "firstName": "match",
      "fullName": "match",
      "lastName": "match",
      "middleName": "match"
    },
    "addressLine1": "match",
    "cvv": "match",
    "postalCode": "match"
  },
  "domesticPullFromCard": "supported",
  "domesticPushToCard": "fast-funds",
  "expiration": {
    "month": "01",
    "year": "21"
  },
  "fingerprint": "9948962d92a1ce40c9f918cd9ece3a22bde62fb325a2f1fe2e833969de672ba3",
  "holderName": "Jules Jackson",
  "issuer": "GRINGOTTS BANK",
  "issuerCountry": "US",
  "lastFourCardNumber": "1234",
  "merchantAccountID": "50469144-f859-46dc-bdbd-9587c2fa7b42",
  "paymentMethods": [
    {
      "paymentMethodID": "9506dbf6-4208-44c3-ad8a-e4431660e1f2",
      "paymentMethodType": "card-payment"
    },
    {
      "paymentMethodID": "3f9969cf-a1f3-4d83-8ddc-229a506651cf",
      "paymentMethodType": "push-to-card"
    }
  ]
}
No account with the specified accountID was found.
Attempted to link card that already exists on the account.
The supplied card data appeared invalid or was declined by the issuer.
{
  "error": "card verification failure: card-not-activated"
}
Request was refused due to rate limiting.

X-Retry-In

string <duration>
How long (in milliseconds) to wait until able to retry the request.

Headers

X-Wait-For

string

Optional header to wait for certain events, such as the creation of a payment method, to occur before returning a response.

When this header is set to payment-method, the response will include any payment methods that were created for the newly linked card in the paymentMethods field. Otherwise, the paymentMethods field will be omitted from the response.

Possible values: payment-method

Path parameters

accountID

string <uuid> required
ID of the Moov account representing the cardholder.

Body

application/json
Describes the card to link to the Moov account.

billingAddress

object required
right_key Show child attributes

postalCode

string <=5 characters required

addressLine1

string <=60 characters

addressLine2

string <=32 characters

city

string <=24 characters

country

string <=2 characters

stateOrProvince

string <=2 characters

cardCvv

string [3 to 4] characters required
The card’s Card Verification Value (CVV). This value is known by a few different names - such as CVV2, CVC, or CID - depending on the card brand. Visa, Mastercard, and Discover typically assign 3 digit CVVs, while American Express assigns a 4 digit value.

cardNumber

string required Pattern
The card’s Primary Account Number (PAN). Typical PANs are 15 or 16 digits, though it’s possible to have a PAN as short as 13 digits or as long as 19 digits.

expiration

object required
The expiration date of the card or token.
right_key Show child attributes

month

string 2 characters

year

string 2 characters

cardOnFile

boolean
Indicates cardholder has authorized card to be stored for future payments. Only cards marked as card-on-file are eligible for automatic updates via card account updater.

holderName

string
The name of the cardholder as it appears on the card. Required when field ‘verifyName’ is set.

merchantAccountID

string<uuid> <=36 characters Pattern
ID of the Moov account acting as a merchant or other entity authorized to store the card. Defaults to your platform account ID if cardOnFile is set to true and no other account is provided.

verifyName

boolean
Indicates whether to submit the cardholder name to a card network for verification. Field ‘holderName’ is required when set.

Response

application/json
Describes a card on a Moov account.

billingAddress

object
right_key Show child attributes

addressLine1

string <=60 characters required

city

string <=24 characters required

country

string <=2 characters required

postalCode

string <=5 characters required

stateOrProvince

string <=2 characters required

addressLine2

string <=32 characters

bin

string

brand

string
The card brand.
Possible values: American Express, Discover, Mastercard, Visa

cardAccountUpdater

object
The results of the most recent card update request.
right_key Show child attributes

updateType

string<enum>
The results of the card update request.
Possible values: unspecified, account-closed, contact-cardholder, expiration-update, no-change, no-match, number-update

updatedOn

string<date-time> <=24 characters

cardID

string<uuid> <=36 characters Pattern
UUID v4

cardOnFile

boolean
Indicates cardholder has authorized card to be stored for future payments.

cardType

string<enum>
The type of the card.
Possible values: debit, credit, prepaid, unknown

cardVerification

object
The results of submitting cardholder data to a card network for verification.
right_key Show child attributes

accountName

object
The results of submitting cardholder name to a card network for verification.
right_key Show child attributes

firstName

string
Possible values: noMatch, match, notChecked, unavailable, partialMatch

fullName

string
Possible values: noMatch, match, notChecked, unavailable, partialMatch

lastName

string
Possible values: noMatch, match, notChecked, unavailable, partialMatch

middleName

string
Possible values: noMatch, match, notChecked, unavailable, partialMatch

addressLine1

string
Possible values: noMatch, match, notChecked, unavailable, partialMatch

cvv

string
Possible values: noMatch, match, notChecked, unavailable, partialMatch

postalCode

string
Possible values: noMatch, match, notChecked, unavailable, partialMatch

domesticPullFromCard

string
Indicates if the card supports domestic pull-from-card transfer.
Possible values: not-supported, supported, unknown

domesticPushToCard

string
Indicates which level of domestic push-to-card transfer is supported by the card, if any.
Possible values: not-supported, standard, fast-funds, unknown

expiration

object
The expiration date of the card or token.
right_key Show child attributes

month

string 2 characters

year

string 2 characters

fingerprint

string <=100 characters
Uniquely identifies a linked payment card or token. For Apple Pay, the fingerprint is based on the tokenized card number and may vary based on the user’s device. This field can be used to identify specific payment methods across multiple accounts on your platform.

holderName

string

issuer

string

issuerCountry

string

lastFourCardNumber

string

merchantAccountID

string<uuid> <=36 characters Pattern
ID of the Moov account acting as a merchant or other entity authorized to store the card. Defaults to your platform account ID if cardOnFile is set to true and no other account is provided.

paymentMethods

array

Includes any payment methods generated for a newly linked card, removing the need to call the List Payment Methods endpoint following a successful Link Card request.

NOTE: This field is only populated for Link Card requests made with the X-Wait-For header.

right_key Show child attributes

paymentMethodID

string<uuid> <=36 characters Pattern
UUID v4

paymentMethodType

string<enum>
The payment method type that represents a payment rail and directionality
Possible values: moov-wallet, ach-debit-fund, ach-debit-collect, ach-credit-standard, ach-credit-same-day, rtp-credit, card-payment, apple-pay, push-to-card, pull-from-card