Ask Moov Beta
Generative AI is experimental and can make mistakes.
Guides Use cases API Changelog
  1. Guides
  2. Issue cards

Card issuing tutorial

Follow this step by step guide to issue cards using our API or SDKs.
*Card issuing is currently in a closed beta. Contact us for more information.

Moov enables you to instantly issue virtual cards on the Visa network, empowering a broad range of embedded spending and expense management solutions such as:

  • Replacing traditional checks for bill payments
  • Providing rapid access to funds from merchant processing
  • Facilitating immediate payments to vendors

Key players

For the purposes of this guide, we’ll assume you are a developer building a platform with the following players:

  • Your Moov account: Your platform that enables your customers to accept payments and use those funds for business-related purchases
  • Customer: Any business that will utilize the virtual card to make payments using funds from its Moov wallet

Prerequisites

This guide assumes that you have onboarded your business customers. To learn more about onboarding, read our hosted onboarding guide.

We also assume that your customer’s Moov wallet has already been funded with a balance. This can be accomplished through:

  • A bank-to-wallet transfer
  • Funds that have accumulated in your wallet from accepting card payments

Read our wallets guide for more information on funding a wallet.

Your customer’s Moov wallet will be used as the funds source for the issued card.

Request a virtual card

After successfully onboarding and verifying your customer’s business, you can proceed to request a virtual card through the Moov API. This card can then be used by the customer for various business transactions.

Request parameters

To issue a virtual card, you will need to submit the following parameters:

Parameter Description
fundingWalletID The unique identifier for the Moov wallet associated with the customer account, ensuring the card is correctly linked to the funds source.
formFactor Currently, Moov supports only “virtual” cards. This parameter specifies the type of card being issued.
authorizedUser Moov requires the first and last names of the card user to comply with regulatory requirements. Optionally, include the user’s birthdate to enhance the accuracy of identity verification and reduce potential false positives during regulatory screenings.
expiration (optional) Set the card’s expiration date (1 to 24 months in the future). If not provided, it defaults to 24 months from the date of issuance.
controls (optional) Indicate that the card should be single use or apply a maximum per-transaction amount limit. 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

curl -X POST "https://api.moov.io/issuing/{accountID}/issued-cards" \
  -H "Authorization: Bearer {token}" \
  --data-raw '{
    "authorizedUser": {
      "firstName": "George",
      "lastName": "Glass",
      "birthDate": {
        "day": 29,
        "month": 4,
        "year": 1958
      }
    },
    "fundingWalletID": "string",
    "formFactor": "virtual",
    "memo": "supplies purchase",
    "expiration": {
        "month": "01",
        "year": "25"
    },
    "controls": {
      "singleUse": false,
      "velocityLimits" : [
        {
          "amount": 1000,
          "interval": "per-transaction"
        }
      ]
    }
  }'\

Once the virtual card has been issued, the customer can then use the card to make purchases within the amount of their wallet balance.

Optional card controls

You can limit the usage of an issued card by setting controls in the card creation request. Controls can only be applied during the initial card creation. The following controls are currently supported:

  • singleUse: If true, the card closes after the first successful authorization.
  • velocityLimits: Sets spending limits per time interval. Currently, only per-transaction limits are supported.

The following example demonstrates a card configured to close after the first successful authorization (singleUse) and enforces a per-transaction spending limit of $50.00.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "controls": {
    "singleUse": true,
    "velocityLimits": [
      {
        "amount": 5000, // $50.00
        "interval": "per-transaction"
      }
    ]
  }
}

Authorized user screening

To comply with anti-money laundering (AML) regulations, Moov conducts regulatory screenings as part of the card issuing process. If the screening flags a potential match on regulatory watch lists, the card will enter the pending-verification state in the response from the initial create a spending card POST endpoint.

To address this, you can submit the authorizedUser.birthDate through the update a spending card PATCH endpoint if not initially provided, to help clear any discrepancies.

View and use card details

Once an issued card is in an active state, your customer can securely access the full PCI-compliant card details for making transactions through the Issued card Drop, a secure interface for displaying sensitive card information.

1
2
3
4
5
6
7
8

// Card issuing Moov Drop
const issuedCard = document.querySelector("moov-issued-card");
// After generating a token, set it on the issued card element
issuedCard.oauthToken = "some-generated-token";

// Include the accountID of the Moov account to which the card was issued and the ID of the issued card to display
issuedCard.accountID = "account-id";
issuedCard.issuedCardID = "card-id";

View issued card authorizations

Each time a card is used to make a purchase from a merchant, Moov processes the authorization request in real time. The outcomes of these requests can be tracked through the card authorization API.

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

curl -X GET "https://api.moov.io/issuing/{accountID}/authorizations" \
  -H "Authorization: Bearer {token}" \
  --data-raw '{
    "issuedCardID": "string",
    "startDateTime": "string",
    "endDateTime": "string",
    "statuses": 
      {"pending", "cleared"},
    "count": "string",
    "skip": "integer"
    }
  }'\

Below we show an example of the card authorization LIST response:

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

[
  {
    "authorizationID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
    "authorizedAmount": "-14.89",
    "cardTransactions": [],
    "createdOn": "2024-08-24T14:15:22Z",
    "fundingWalletID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
    "issuedCardID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
    "merchantData": {
      "city": "San Francisco",
      "country": "US",
      "mcc": "7298",
      "name": "Whole Body Fitness",
      "networkID": "1234567890",
      "postalCode": "94107",
      "state": "CA"
    },
    "network": "visa",
    "status": "pending"
  }
]

View completed card transactions

When a pending authorization is successfully captured and funds have settled, a card transaction resource is created. This indicates that the funds related to that transaction have been moved. We retain details from the original authorization for reconciliation and tracking purposes.

You can list all card transactions associated with a particular Moov account by using the list card transactions GET endpoint as shown below:

1
2

curl -X GET "https://api.moov.io/issuing/{accountID}/card-transactions" \
  -H "Authorization: Bearer {token}" \

Here’s an example of a completed card transaction:

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

[
  {
    "amount": "-14.89",
    "authorizationID": "f5f47bfa-fa5a-41f4-99eb-8671c1875b3f",
    "authorizedOn": "2024-08-24T14:15:22Z",
    "cardTransactionID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
    "createdOn": "2024-08-24T14:15:22Z",
    "fundingWalletID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
    "issuedCardID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
    "merchantData": {
      "city": "San Francisco",
      "country": "US",
      "mcc": "7298",
      "name": "Whole Body Fitness",
      "networkID": "1234567890",
      "postalCode": "94107",
      "state": "CA"
    }
  }
]
Summary Beta