Guides API reference Use cases Changelog

Accept card payments

Link a customer's credit or debit card to their Moov account, then charge it with a transfer to the merchant's Moov wallet. Use this for ecommerce, SaaS, and subscription checkouts.

Before you start

  • A payer account and a merchant account. See create accounts or hosted onboarding.
  • The merchant needs the collect-funds.card-payments and wallet.balance capabilities. The payer needs transfers.
  • To link cards through the API instead of the card link Drop, an attestation of PCI compliance submitted to Moov.
  • In test mode, use the test cards.

Endpoints used: link a card, list payment methods, create a transfer, and retrieve a transfer.

Linking a card verifies it with the card network, including Address Verification Service (AVS) and Card Verification Value (CVV) checks. For the whole flow end to end, from onboarding the merchant to the webhooks, follow the accept a card payment recipe.

You can use the pre-built card link Drop, or if you've submitted an attestation of PCI compliance to Moov, you can link cards directly through the API. If you opt for the API method, you'll be responsible for storing and handling card data.

Save a card for future use

Before you link a card, consider whether the card should be saved on file to use Moov's card account updater service. This can be done by setting cardOnFile to true when linking a card. If nothing is passed to cardOnFile, or you set it to false, the card will not automatically update card number and expiration date information. If a card becomes out of date, it will not work for future payments.

If you set the cardOnFile flag to true, the merchantAccountID (Moov account ID of a merchant on your platform) provided should signify which merchant the cardholder has consented to save their information. The account associated with the merchantAccountID will incur fees for successful card updates using Moov's card account updater.

If you leave the merchantAccountID field blank while saving a card on file, the system will default to your partner account ID, indicating the cardholder's relationship with your platform's brand. You can update the merchantAccountID at any time using the update card PATCH endpoint.

Accounts must be approved for card account updater. Contact Moov for more information.

Drop

The simplest way to securely collect sensitive card details is by using the card link Drop, a prebuilt UI component for embedding card-based payments. By using the card link Moov Drop, you’ll send card data directly to Moov’s PCI-compliant card vault, and the information will not touch your servers.

Once the information has been submitted via the Drop, Moov verifies the card details with card networks.

<moov-card-link class="card-link"></moov-card-link>

<script>
  let moovCardLink = document.querySelector("moov-card-link");
  moovCardLink.accountID = "accountID";
  moovCardLink.oauthToken = "oauthToken";
  moovCardLink.onSuccess = (card) => {
    console.log("Card linked");
    // now show a success screen
  }
  moovCardLink.onError = (error) => {
    console.log("Error linking card");
    // now show an error screen
  }

  // call submit when button is pressed
  moovCardLink.submit();
</script>

API & SDKs

Link a card using our API or Go SDKs. If you set the optional X-Wait-For header to payment-method, the response will include any payment methods that were created for the newly linked card in the paymentMethods field.

curl -X POST "https://api.moov.io/accounts/{accountID}/cards" \
  -H "Authorization: Bearer {token}" \
  -H "X-Wait-For: payment-method" \
  -H "x-moov-version: v2026.07.00" \
  --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"
  }'

Card verification

When a card is linked, Moov performs a verification with the relevant card network to confirm that the card account is open and valid. Additionally, the verification checks if the CVV and address match the information on file with the card issuer.

The merchantAccountID is used to pass merchant information during card verification. Although these verification transactions are rarely visible to cardholders, when they are, it's crucial that cardholders recognize the merchant associated with the verification so they know it's not fraudulent.

Although it's best practice to always include the merchantAccountID during card verification, it's not mandatory. If you omit this field, the system defaults to your partner account ID.

It is possible the verification request will be declined by the card issuer. Decline information is provided in the response body of the 422 error. Errors could be validation errors, such as an invalid card number, or actual declines from the card issuer. Below is an example of a card issuer decline.

{
  "error": "card verification failure: card-not-activated"
}

Verify the cardholder name

Optionally, Moov supports Visa’s Account Name Inquiry (ANI). ANI ensures that the name provided on the linked card matches the name held on file with the issuer. This tool is optional and serves to enhance cardholder verification.

The card link POST endpoint and PATCH endpoint offer an optional verifyName field. To submit a name to Visa for verification, supply the holderName and set verifyName to true. Pull from card requires name verification.

{
  "cardVerification": {
    "fullName": "match",
    "firstName": "match",
    "middleName": "noMatch",
    "lastName": "match"
  }
}

Each name field returns match, partialMatch, noMatch, or notChecked.

Charge the card

Create a transfer from the card's card-payment payment method (the source) to the merchant's moov-wallet payment method (the destination). Get both with the list payment methods endpoint.

curl -X POST "https://api.moov.io/accounts/{accountID}/transfers" \
  -H "Authorization: Bearer {token}" \
  -H "x-idempotency-key: UUID" \
  -H "X-Wait-For: rail-response" \
  -H "x-moov-version: v2026.07.00" \
  --data-raw '{
    "amount": {
      "value": 100,
      "currency": "USD"
    },
    "destination": {
      "paymentMethodID": "string"
    },
    "source": {
      "paymentMethodID": "string"
    },
    "description": "Optional transaction description."
  }'

Send X-Wait-For: rail-response when a customer is waiting on a checkout screen: the response includes the card network's answer, and source.cardDetails.status of confirmed means the issuer approved the charge. Without it, you get the transfer ID right away and follow transfer.updated. A 202 means the network hasn't answered yet; see create transfer responses.

When the funds arrive

The transfer stays pending until the funds reach the merchant's wallet, then moves to completed. From the wallet, pay them out with another transfer or a daily sweep.

Open in the payment modeler, with webhooks

Reverify a card

Moov will only perform a new verification request if a new CVV is provided.

You can use the update a card PATCH endpoint to update and re-verify certain information about the card. The cardID is the ID of the card you want to update, and the accountID represents the Moov account that the card is linked to.

{
  "cardCvv": "123"
}

Optional request data:

Field Type Description
expiration object The card's expiration month and year
cardCvv string The card's CVV number
billingAddress object The billing address associated with the card

Note that when performing a PATCH on an existing card, Moov will perform another CVV verification request to the card networks using the new information provided. If the new verification is declined by the card issuer, the previously linked card will not be affected. If the verification succeeds, the card record will be updated with the new information.

Refer to the cardVerification{} object in the response to see if the new CVV information is correct.

{
  "cardVerification": {
    "cvv": "match",
    "addressLine1": "match",
    "postalCode": "match"
  }
}

Improve approval rates

Some card issuers display alerts or notifications about card verifications to cardholders. Being transparent and recognizable prevents accidental suspicion.

Include as much complete and accurate data as possible to comply with card brand rules and mandates, optimize card authorization rates, prevent interchange downgrades, and increase defensibility against chargebacks. Consider the following best practices:

  • Street address: Send the optional addressLine1 in billingAddress. For most situations, Moov recommends sending the address so that full address verification can take place. Not including addressLine1 may impact approval rates, cause interchange downgrades, and impact chargeback win rate.
  • Card verification: Always include merchantAccountID when performing a card verification. This provides context to the cardholder if the verification transaction becomes visible.
  • Save a card on file: If you're saving a card for future use, specify merchantAccountID and set the cardOnFile flag to true. This indicates the cardholder's relationship with the merchant, and their consent to save their card details for future transactions.

Next steps