Link a card

Link a card to an existing Moov account.

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

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

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.

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.

merchantAccountID


        string<uuid>

<=36 characters

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.

Response

application/json

Describes a card on a Moov account.

billingAddress


        object

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.

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

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.

Show child attributes

accountName


              object

The results of submitting cardholder name to a card network for verification.

Show child attributes