Card acceptance

This guide covers how to initiate card transfers with Moov. Learn how to link debit and credit cards to Moov accounts, and use the card of your choice as the source of a payment transfer.

We’ll walk you through the step-by-step process of initiating a card payment, how to check a card’s status, and finally, how to access funds. This guide assumes you have a Moov wallet.

You can simulate card transfers in test mode. See our guide on testing card numbers.

Accept card payments

Once your platform’s Moov account is configured for card payments, you can start capturing your customers’ card information and use the tokenized details to initiate card payment transfers.

You can process payments directly from your account or on behalf of any connected Moov accounts that have the collect-funds and wallet capabilities enabled. See our guide on requesting capabilities to learn about each capability’s information requirements.

Card funds flow diagram

Card payments on Moov’s platform have a source and destination:

Source: paymentMethodID of the card you want to charge. The payment method is associated with the cardholder’s Moov account.

Destination: paymentMethodID of the Moov wallet where funds will settle. This wallet belongs to the business or “merchant” accepting the payment.

Initiate a card payment

  1. Create a Moov account for the cardholder with the transfers capability and set the accountType to individual. Moov requires name and phone or email of the cardholder before transfers is enabled and will automatically enable the capability once received.
Each cardholder phone number or email needs to be unique when linking a card. Reusing or sharing a phone number or email may result in a failed card status (declined).
  1. Link a card to the Moov account using the card input Moov Drop to safely collect sensitive card information.

  2. Obtain the paymentMethodID for the payment method type card-payment associated with the card that should be charged. This can be found using the payment methods GET endpoint, or the transfer options POST endpoint

  3. Obtain the paymentMethodID for the payment method type moov-wallet of the merchant or transfer destination. This can be found using the same methods above.

  4. Create a transfer with source payment method type card-payment and destination payment method type moov-wallet.

  • If you need a synchronous response with full transfer and rail-specific details from the payment network, make sure to include the X-Wait-For header in the request.
  • If you are creating a non-first time recurring payment and prefer an asynchronous response, omit the X-Wait-For header. By omitting the header, you’ll receive asynchronous response that only includes the transferID and timestamp for when the transfer was created.
  • Be sure to check the cardDetails object of the transfer response for the status of the card payment. Don’t consider the payment successful until the status is at least confirmed.
  • Read more on our transfer responses for context on what the different HTTP status codes mean and why you may or may not be receiving full transfer details.
A synchronous response is useful for when a user is clicking a button to make a payment and needs an immediate response so they can get confirmation that it worked. An asynchronous response is useful in cases where you are facilitating multiple payments outside the band of user experience and you just need confirmation that the transfers were accepted to be processed.

After the transfer is created

  • After creation, the transfer will be pending until the funds are disbursed to the destination moov-wallet. After creating the transfer, funds typically settle and become available by the end of the next business day.
  • You can check on the status of the transfer at any time using the GET endpoint. You can view detailed information about card processing in the cardDetails sub-object:
  "source": {
    "cardDetails": {
      "status": "confirmed"

Card statuses

Status Description
initiated The card transfer was successfully started
confirmed The payment request was approved by the cardholder’s bank and the funds are eligible for settlement
failed The payment has failed due to a decline or network error. See the failureReason field to see a specific reason for the failure.
settled Funds have settled and are in the disbursement process
completed Funds have been credited to the destination and are available for use

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.


How does Moov report cardholder disputes?
Moov notifies you about incoming disputes using the dispute.updated webhook. Read our webhooks guide for more information. Please note that as the main account holder, you are responsible for notifying impacted merchants of any incoming disputes.

Articles in this section