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 Go 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: payment-method" \
  --data-raw '{
    "billingAddress": {
      "addressLine1": "123 Main Street",
      "city": "Denver",
      "stateOrProvince": "CO",
      "postalCode": "80301",
      "country": "US"
    },
    "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
22


mc, _ := moov.NewClient()

var accountID string

cardPayload := moov.CreateCard{
  BillingAddress: moov.Address{
    AddressLine1:    "123 Main Street",
    City:            "Denver",
    StateOrProvince: "CO",
    PostalCode:      "80301",
    Country:         "US",
  },
  CardNumber: "4111111111111111",
  CardCvv:    "123",
  Expiration: moov.Expiration{
    Month: "01",
    Year:  "28",
},
  HolderName: "Jules Jackson",
}

mc.CreateCard(ctx, accountID, cardPayload)

 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",
    stateOrProvince: "CO",
    postalCode: "80301",
    country: "US"
  },
  cardCvv: "123",
  cardNumber: "4111111111111111",
  expiration: {
    month: "01",
    year: "27",
  },
  holderName: "Jules Jackson"
};

const card = await moov.cards.link(accountID, cardPayload);

200 400 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-1234",
    "stateOrProvince": "CO"
  },
  "bin": "123456",
  "brand": "Discover",
  "cardAccountUpdater": {
    "updateType": "number-update",
    "updatedOn": "2019-08-24T14:15:22Z"
  },
  "cardCategory": "CLASSIC",
  "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"
  },
  "commercial": true,
  "domesticPullFromCard": "supported",
  "domesticPushToCard": "fast-funds",
  "expiration": {
    "month": "01",
    "year": "21"
  },
  "fingerprint": "9948962d92a1ce40c9f918cd9ece3a22bde62fb325a2f1fe2e833969de672ba3",
  "holderName": "Jules Jackson",
  "issuer": "GRINGOTTS BANK",
  "issuerCountry": "US",
  "issuerPhone": "8185551212",
  "issuerURL": "HTTPS://WWW.EXAMPLE.COM/",
  "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"
    }
  ],
  "regulated": true
}

The request was invalid.

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"
}

{
  "cardCvv": "must contain digits only",
  "cardNumber": "must be a valid card number"
}

Request was refused due to rate limiting.

Retry-After


      number

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

[1 to 10] 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.

e2ee


        object

Optional and only used if planning to use End to End Encryption to pass PCI data through an intermediary. This is the output of using compact serialization of a JWE token that wraps an AES key and uses the public key returned from /end-to-end-keys. Examples of how to create this token can be found on our GitHub. Body for a JWE token following RFC.

Show child attributes

token


        string<JWE>

holderName


        string

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

merchantAccountID


        string<uuid>

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. Only Visa cards are eligible for cardholder name verification.

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

[1 to 10] characters required

stateOrProvince


        string

<=2 characters required

addressLine2


        string

<=32 characters

bin


        string

The first six to eight digits of the card number, which identifies the financial institution that issued the card.

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

cardCategory


        string

The category or level of the card defined by the issuer. Examples include, but not limited to “REWARDS”, “TRADITIONAL REWARDS”, “CLASSIC”, and “CORPORATE PURCHASING”.

cardID


        string<uuid>

<=36 characters

UUID

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