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

/accounts/{accountID}/cards

Example API Requests

cURL Example

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

Go Example

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)

TypeScript Example

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();

PHP Example

declare(strict_types=1);

require 'vendor/autoload.php';

use Moov\