Accept card payments
Linking a card to a Moov account automatically verifies the card details with the card networks. This process verifies the existence of the card account and returns information about the Address Verification Service (AVS) and Card Verification Value (CVV) checks that occur.
Link a card
Before a card can be linked, a Moov account must be created. Once the account is created, use the POST /accounts/{accountID}/cards
endpoint to link a card to the Moov account representing the cardholder. All cards must be linked to a Moov account before they can be charged using a transfer.
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.
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
(Moov account ID of a merchant on your platform) 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.
merchantAccountID
during card verification, it is not mandatory. If you omit this field, the system defaults to your platform’s 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.
|
|
Save a card for future use
The link card POST
endpoint allows you to save a card for future payments by setting cardOnFile
to true. If nothing is passed to cardOnFile
, or you set it to false, the payment method will not be used for future payments.
If you set the cardOnFile
flag to true, the merchantAccountID
should signify the merchant which the cardholder has consented to have their information saved. You must set cardOnFile
to true to use Moov’s card account updater service, as the account associated with the merchantAccountID
will incur fees for successful card updates. Accounts must be approved for card account updater. Reach out to your relationship manager, or contact support and select submit a support ticket for card payment acceptance issues to request access.
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.
Best practices
Some card issuers might display alerts or notifications about card verifications. Being transparent and recognizable to cardholders can prevent accidental suspicion. Consider the following best practices:
- Street address & postal code: Sending the
postalCode
is required when adding a card, butaddressLine1
is optional. For most situations, Moov recommends sending the addrress so that full address verification can take place. Not includingaddressLine1
may impact approval rates, cause interchange downgrades, and impact chargeback win rate. - Card verification: Always include the
merchantAccountID
when performing a card verification. This provides context to the cardholder if the verification transaction becomes visible. - Saving a card-on-file: If you’re saving a card for future use, specify the
merchantAccountID
and set thecardOnFile
flag to true. This indicates the cardholder’s relationship with the merchant, and their consent to save their card details for future transactions.
Optimizations
Follow best practices and include as much complete and accurate data as possible to optimize card authorization rates, prevent interchange downgrades, and increase defensibility against chargebacks.
Field | Authorization | Interchange | Chargebacks |
---|---|---|---|
cardCvv |
𐌗 | 𐌗 | 𐌗 |
addressLine1 |
𐌗 | 𐌗 | |
postalCode |
𐌗 | 𐌗 | 𐌗 |
Reverify a card
You can use the accounts 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.
|
|
Optional request data:
Field | Type | Required | 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.
|
|
Payment methods
Payment method | Description | Capability |
---|---|---|
card-payment |
Can be the source of a card payment | transfers |
moov-wallet |
Can be the destination of a card payment | collect-funds |