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 access this endpoint using an access token you'll need to specify the /accounts/{accountID}/cards.write scope.

POST

curl -X POST "https://api.moov.io/accounts/{accountID}/cards" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.04.00" \
  -d '{
  "cardNumber": "4111111111111111",
  "cardCvv": "123",
  "expiration": {
    "month": "01",
    "year": "21"
  },
  "holderName": "Jules Jackson",
  "billingAddress": {
    "postalCode": "80301"
  }
}'

Ask (Go)

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)

Ask (TypeScript)

import { Moov } from "@moovio/sdk";

const moov = new Moov({
  security: {
    username: "",
    password: "",
  },
});

async function run() {
  const result = await moov.cards.link({
    xWaitFor: "payment-method",
    accountID: "5593e46f-7936-474b-a52b-96f1da46867b",
    linkCard: {
      cardNumber: "4111111111111111",
      cardCvv: "123",
      expiration: {
        month: "01",
        year: "21",
      },
      holderName: "Jules Jackson",
      billingAddress: {
        postalCode: "80301",
      },
    },
  });

console.log(result);
}

run();

Ask (PHP)

declare(strict_types=1);

require 'vendor/autoload.php';

use Moov\