Accept card payments

Link card to Moov account

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 platform’s 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.

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

<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 or Node 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.

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

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.

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.

1
2
3

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

Name verification (optional)

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.

1
2
3
4
5
6
7
8

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

Submit the card payment

The customer’s card will be the source of funds, so Moov needs the card-payment payment method from their account. You can obtain the paymentmethodID from the payment methods GET endpoint. The sourceID should be the cardID, which you can get from the cards GETendpoint.

Since the merchant’s wallet will be the destination of the funds, we will need the moov-wallet payment method. You can obtain the paymentmethodID using the payment methods GET endpoint and finding the moov-wallet payment method associated with the merchant account.

To submit the card payment, create a transfer from the cardholder (source) to the merchant (destination).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

curl -X POST "https://api.moov.io/transfers" \
  -H "Authorization: Bearer {token}" \
  -H "X-Idempotency-Key: UUID" \
  -H "X-Wait-For: rail-response" \
  --data-raw '{
    "amount": {
      "value": 100,
      "currency": "USD"
    },
    "destination": {
      "paymentMethodID": "UUID"
    },
    "source": {
      "paymentMethodID": "UUID"
    },
    "description": "Optional transaction description."
  }'\

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

const moov = new Moov(credentialsObject);

const transfer = await moov.transfers.create({
  amount: {
    value: 100,
    currency: "USD"
  },
  destination: {
    paymentMethodID: "UUID"
  },
  source: {
    paymentMethodID: "UUID"
  },
  description: "Optional transaction description."
});

Card-based payments first settle in a Moov wallet. The funds can later be moved to an external bank account through a disbursement transfer.

Check status

After a transfer is created, it will be pending until the funds are disbursed to the destination moov-wallet. Funds typically settle and become available by the end of the next business day. You can check the status of the transfer anytime using the GET endpoint.

You can also see card specific status details in the response within the source.cardDetails object.

1
2
3
4
5
6
7
8

{
  "source": {
    "cardDetails": {
      "status": "confirmed",
      "confirmedOn": "2023-09-10T18:23:56Z"
    }
  }
}

Access funds

Once the payment has been processed and the funds are available, the funds can be moved out of the merchant moov-wallet using another transfer where that wallet is the source. Bank holidays may delay the availability of funds.