API Reference

Virtual USD Debit Cards for Individuals and Businesses

With Graph, you can effortlessly create virtual USD cards tailored to suit your business customers or employees. Whether you're issuing cards for individual users or entire organizations, these endpoints empower you to control the card lifecycle and ensure a smooth experience for your customers.

Before You Begin

Graph offers a comprehensive suite of card-related functionalities, each designed to provide flexible solutions to your unique financial needs. Before diving into the endpoint details, let's cover some key insights:

Funding Your USD Master Wallet

Before initiating card creation or funding, it's important to ensure that your organization's USD master wallet is sufficiently funded. Charges for card creation are deducted directly from the master USD wallet, and cards can only be funded from this source. When closing a card, the remaining balance is unloaded back to the organization's USD master wallet. No need to create unique wallets for each card; the organization's wallet serves as the liquidity reserve for both card creation and funding, streamlining operations efficiently.

To fund your organization's USD master wallet for card creation, access the funding account details by calling the list account endpoint under the bank accounts section in the documentation. Look for the account labeled "Wallet funding account" with a settlement_currency of USD. Make a bank transfer to the provided account details, which will be settled to your USD wallet. You may also get your wallet funding account info by logging in to your dashboard, switch to your USD master wallet, and click to view the funding information. In the sandbox environment, utilize the mock deposit endpoint to simulate a deposit to the wallet funding account for testing purposes.

🚧

Point of note

Note that mock deposits are solely for sandbox testing, and actual bank transfers should be used in the production environment.

Card Status

When working with Graph's card issuance and management, it's essential to understand the various card statuses that can occur throughout the card's lifecycle:

Issuance Status

Card issuance on Graph can has one of three statuses: successful, pending, or failed. While card creation is not instantaneous, our system ensures a swift provisioning process. Typically, it takes around 2 seconds but may extend to a few minutes.

PendingSuccessfulFailed
After initiating card creation, the card may initially be in a "Pending" status. This status indicates that the card provisioning process is underway but has not yet been completed.Once the card provisioning process is completed, the card status transitions to "Successful." At this point, the card is ready for use.In some cases, card provisioning may encounter issues, resulting in a "Failed" status. When this occurs, further investigation is required to determine the cause of the failure.

Post-Issuance Status

After issuance, a card may be active, frozen, or closed.

ActiveFrozenClosed
A card that is ready for use and has been successfully funded is considered "Active."In this status, the card cannot be funded or used for any other transactions until it is unfrozen and adequately funded. You may freeze cards considered to be suspicious or compromised using the freeze card endpoint. Also, If the card's balance falls below the set threshold, it may enter a "Frozen" state.This status indicates that the card has been completely deactivated. Cards that consistently fail to meet the monthly maintenance fee or other requirements may be automatically closed (deactivated) on a scheduled basis.

Card Fees

Here, we provide insights into the various fees associated with Graph cards. Understanding these fee structures is crucial for the effective management of your Graph card account and for ensuring a smooth financial experience

Fee TypeDescription
Card Creation FeeThe Card Creation Fee is a one-time charge applied when creating a new card. This fee is deducted from the organization's pool account, simplifying the process for users.
Monthly Maintenance FeeThis is a recurring charge applied to keep a card active and functioning optimally. This fee is deducted from the card's position balance. It's essential to maintain sufficient funds to cover this fee to avoid card deactivation. Monthly fees for Graph cards are charged on the anniversary of the card's creation. For example, if a card was created on the 21st of July, the monthly fee will be charged on the 21st of every subsequent month. Graph offers a grace period of 4 days. During this time, deductions for the monthly maintenance fee are attempted once a day. After this grace period, the card may be closed (deactivated) if it cannot be charged.
Insufficient Funds FeeThe insufficient funds fee is only charged when a transaction fails due to insufficient funds while the card remains active. It's deducted from the card's position.
Transaction FeesThis fee is typically a percentage of the transaction amount. Organizations and users should be aware of this fee when making transactions.

🚧

Point of note

Please note that the fees mentioned in this section are provided for informational purposes and may be subject to change based on Graph's policies and agreements with partner financial institutions. It is essential to review the specific terms and conditions related to your card program with Graph to obtain accurate and up-to-date fee information.

Currency Denomination

When sending an amount, it must be in subunits of the currency, which means multiplying the base amount by 100. For example, if the payment amount is USD 10, you should send 1000 (i.e 10 times 100) in your request.