Accept card payments
With Moov, you can build a checkout flow for accepting payments. For example, merchants selling goods or services through your platform may want to take card payments from their customers. In this guide, we cover the steps for setting up card acceptance.
For the purposes of this guide, we’ll assume the following key players:
- Your Moov account: A platform facilitating the card payments
- Merchant: The account taking card payments. This will be the
destination
for the Moov transfer. - Cardholder/Customer: The account being charged. This will be the
source
for the Moov transfer.
Install Moov.js
This guide covers using Moov Drops or Moov.js to onboard your merchants and cardholders, so you’ll need to get started by installing Moov.js. You can install Moov.js two different ways. You can do a script based installation, or initialize the package via npm.
Include the script tag
|
|
Install via npm
|
|
|
|
Get your access token
Assuming you’ve already completed a basic setup of your Moov account, you’ll need to create an access token using your API key, which you can get from the Moov Dashboard. You will include a new access token as the Moov Drop onboarding.token
whenever you onboard merchants or cardholders.
|
|
|
|
Onboard your merchants
Card payments are modeled as a transfer from a source to a destination. In the card acceptance use case, the source is a cardholder and the destination is a merchant.
As the platform, you are facilitating card payments on behalf of your merchants. You will start by setting up Moov accounts for your merchants. Your merchants will be subject to identity verification. You have three different options for doing this:
Option 1: Collect the necessary information from the merchants via a pre-built onboarding UI component.
Option 2: Collect the necessary information from your merchants using Moov.js and your own UI.
Option 3: Use the API directly via our Node SDK. Note that when using our server-side Node SDK to onboard a sender, you can use the same code as you would when using Moov.js because the method names are the same.
|
|
|
|
|
|
Onboard cardholders
Next, you’ll need to onboard your cardholders by:
- Creating a Moov account for the cardholder
- Making a server-side call to refresh the token with the new scopes for the accountID
- Passing the token to the card link Drop and submitting it
Create a Moov account for the cardholder
Once the customer is prompted to pay, you can onboard them with Moov.js and create an account that will automatically request the transfers
capability.
|
|
Generate the access token
Create an access token using your API key following the steps from above.
Link their card to the Moov account
To link the customer’s card to their Moov account, you can use the pre-built Card Link Moov Drop in an HTML document as shown below and include the token you generated in the previous step:
|
|
Once the information has been submitted, Moov verifies the card details with card networks. You will not be responsible for storing or handling any of the card data, since all PII goes directly to Moov.
Facilitate card payments
The customer’s card will be the source of funds, so we’ll need the card-payment
payment method that was created after they linked their card. You can obtain the paymentmethodID
from the payment methods endpoint by using the cardID as the sourceID
.
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 by listing payment methods and finding the moov-wallet payment method associated with the merchant account.
To facilitate a card payment, create a transfer from the cardholder (source) to the merchant (destination).
|
|
|
|
X-Wait-For
header in the request, you will get a synchronous response that includes full transfer and rail-specific details from the payment network. This is useful for when a user is clicking a button to make a payment and needs a synchronous response so they can get confirmation that it worked. If you omit the X-Wait-For
header, you will get an asynchronous response that only includes the transferID and the timestamp for when the transfer was created.
202
response from creating a transfer, do not consider the transfer as successful or failed. Instead, you should wait for the webhook notification to determine the status of the transfer, or subsequently look up the transfer status using the transferID
. Read more on our transfer responses guide.
Set statement descriptors
You can set the default statement descriptor for a merchant by using the account.settings.cardPayment.statementDescriptor
field in the PATCH
accounts endpoint.
Optionally, source.cardDetails.dynamicDescriptor
in the CREATE
transfer endpoint allows a merchant to pass information to the card issuer at the time of transaction. The card issuer will then use this information to generate a description of the cardholder’s statement.
Set fees
If you want to monetize your payment flows, you can collect facilitator fees on card transfers. The amount specified will be deducted from the payment so that the destination receives the transfer amount net of fees. The fee amount is credited to your Moov wallet once the transfer is completed.
The FacilitatorFee
field in the transfer request gives you the option to:
- Implement your own customer-facing fee structure
- Pass along your costs
For more information on facilitator fees and other fee structures, read our guide on fees here.
Track the status of a transfer
After creation, the overall transfer status will be pending
until the funds are disbursed to the destination moov-wallet
. The following business day, Moov receives settlement for the transactions from the card networks and then disburses the funds to the merchant’s wallet.
The X-Wait-For
header waits until the card network has approved or declined the response and will provide you with a synchronous response in real-time. When you use this header, it will return the whole transfer object in the response. The platform should then look at cardDetails.status to ascertain the status of the payment.
confirmed
= successfully authorizedfailed
= declined or failed for an unknown reason.
You can check on the status of the transfer at any time using the GET
transfers endpoint. You can view detailed information about card processing in the cardDetails
sub-object:
|
|
You can also check on the status of the transfer by subscribing to the transfer.updated
webhook.
For a sense of card-to-wallet transfer timing, see the diagram below.
What’s next
If you’re interested in other use cases, you can dive into our guides: