> For the complete documentation index, see [llms.txt](https://docs.cashramp.co/cashramp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cashramp.co/cashramp/cashramp-api/virtual-cards.md).

# Virtual Cards

Issue and manage virtual USD cards for your customers. Cards are funded from your Cashramp balance and are scoped to your own customers, so you can only create and manage cards belonging to a customer you own.

{% hint style="info" %}
All virtual card mutations require a **secret** API key. See [Authentication](https://docs.cashramp.co/cashramp/introduction/authentication.md).
{% endhint %}

## Verify a Customer

Before you can issue a card, the customer must pass a selfie check. Send a photo of the customer's face and a photo of their ID with `verifyMerchantCustomer`. This is a photo check, not a live video check.

```graphql
mutation {
  verifyMerchantCustomer(
    merchantCustomer: "customer_id"
    selfie: "https://example.com/selfie.jpg"
    identificationDocument: "https://example.com/id.jpg"
  )
}
```

<table><thead><tr><th width="190">Argument</th><th width="150">Type</th><th width="94">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>merchantCustomer</code></td><td><code>ID!</code></td><td><strong>Yes</strong></td><td>The ID of the customer to verify.</td></tr><tr><td><code>selfie</code></td><td><code>String!</code></td><td><strong>Yes</strong></td><td>URL of a photo of the customer's face.</td></tr><tr><td><code>identificationDocument</code></td><td><code>String!</code></td><td><strong>Yes</strong></td><td>URL of a photo of the customer's government-issued ID.</td></tr></tbody></table>

Returns `true` once the photos are received, and the customer's `status` moves to `pending_verification`. The selfie is matched against the photo on the ID, and the name on the ID against the name you gave in [`createCustomer`](https://docs.cashramp.co/cashramp/cashramp-api/customers.md). A clear match is approved automatically, and anything unclear is reviewed by the Cashramp team.

Verification is not instant. Fetch the customer with [`merchantCustomer`](https://docs.cashramp.co/cashramp/cashramp-api/customers.md#fetch-a-single-customer) and wait for `status` to be `verified` before you request a card. If the check is declined, `status` goes back to `created` and you can send new photos.

### Uploading the photos

Both URLs must be downloadable by Cashramp. If you don't host the photos yourself, upload each one to the Cashramp upload endpoint with your API key and use the `url` it returns.

```bash
curl -X POST https://api.useaccrue.com/merchant/upload \
  -H "Authorization: Bearer CSHRMP-SECK_xxxxxxxxxxxxxxxxxxxxxx" \
  -F "image=@selfie.jpg"
```

```json
{ "url": "https://..." }
```

On staging, use `https://staging.api.useaccrue.com/merchant/upload`.

***

## Submit Customer KYC

Once the customer is verified, submit the identity details the card issuer needs with `submitCustomerKyc`. Send it after verification so the card issuer gets exactly the details you submit.

```graphql
mutation {
  submitCustomerKyc(
    customer: "customer_id"
    idType: national_id
    idNumber: "1234567890"
    phoneNumber: "+2348012345678"
    bvn: "22222222222"
    address: {
      address1: "12 Admiralty Way"
      city: "Lekki"
      state: "Lagos"
      zipcode: "106104"
    }
    dateOfBirth: "1990-04-21"
  ) {
    id
    phoneNumber
  }
}
```

<table><thead><tr><th width="150">Argument</th><th width="150">Type</th><th width="94">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>customer</code></td><td><code>ID!</code></td><td><strong>Yes</strong></td><td>The ID of the customer to submit KYC for.</td></tr><tr><td><code>idType</code></td><td><code>IdentificationDocument!</code></td><td><strong>Yes</strong></td><td>The type of ID document. One of <code>passport</code>, <code>national_id</code>, <code>voter_card</code>, <code>driver_license</code>, <code>nin</code>.</td></tr><tr><td><code>idNumber</code></td><td><code>String!</code></td><td><strong>Yes</strong></td><td>The ID document number.</td></tr><tr><td><code>phoneNumber</code></td><td><code>String!</code></td><td><strong>Yes</strong></td><td>The customer's phone number in international format (e.g. <code>+2348012345678</code>).</td></tr><tr><td><code>bvn</code></td><td><code>String</code></td><td>No</td><td>Bank Verification Number. <strong>Required for Nigerian customers.</strong></td></tr><tr><td><code>address</code></td><td><code>JSON</code></td><td><strong>Yes</strong></td><td>The customer's residential address. See <a href="#address">Address</a>.</td></tr><tr><td><code>dateOfBirth</code></td><td><code>ISO8601Date</code></td><td>Sometimes</td><td>The customer's date of birth (<code>YYYY-MM-DD</code>). Required when the customer's ID is a Nigerian NIN (<code>idType</code> <code>nin</code> or <code>national_id</code> without a valid BVN).</td></tr><tr><td><code>idFrontImage</code></td><td><code>String</code></td><td>Sometimes</td><td>The front of the customer's ID as a base64-encoded JPEG or PNG, without a <code>data:</code> prefix. See <a href="#id-image">ID image</a>.</td></tr><tr><td><code>idBackImage</code></td><td><code>String</code></td><td>Sometimes</td><td>The back of the customer's ID, in the same format as <code>idFrontImage</code>. Send it for an ID with two sides. See <a href="#id-image">ID image</a>.</td></tr></tbody></table>

### Address

`address` is an object with these keys. All are required except `country`.

<table><thead><tr><th width="150">Key</th><th>Description</th></tr></thead><tbody><tr><td><code>address1</code></td><td>Street address.</td></tr><tr><td><code>city</code></td><td>City.</td></tr><tr><td><code>state</code></td><td>State, region or province.</td></tr><tr><td><code>zipcode</code></td><td>Postal or ZIP code.</td></tr><tr><td><code>country</code></td><td>Optional ISO 3166 country code (e.g. <code>NG</code> or <code>NGA</code>). Defaults to the customer's country.</td></tr></tbody></table>

### ID image

The card issuer needs an image of the customer's ID unless the customer is Nigerian with a valid BVN, or their ID is a Nigerian NIN (then `dateOfBirth` is needed instead).

If the `identificationDocument` you sent to [`verifyMerchantCustomer`](#verify-a-customer) was uploaded through the Cashramp upload endpoint, it is used and you can leave `idFrontImage` out. Otherwise send `idFrontImage`.

If the ID has two sides, such as a national ID card, driver's license or voter's card, also send the back as `idBackImage`. A passport doesn't need it. The card issuer can turn down a two-sided ID that comes with only the front.

If you call `submitCustomerKyc` again with a different `idType` or `idNumber` and no `idBackImage`, the back you sent before is dropped.

### Existing customers

The card issuer now requires the address (and the date of birth or ID image above) before issuing a new card. For a customer who is already `verified`, call `submitCustomerKyc` again with their existing ID details plus the missing fields. The customer stays verified and you don't need to repeat [`verifyMerchantCustomer`](#verify-a-customer). The same goes for a customer with a two-sided ID who only had the front sent: call `submitCustomerKyc` again with `idBackImage`, then request the card again.

The identity number and BVN are stored encrypted. Call this before [`requestVirtualCard`](#request-a-virtual-card): issuance is rejected (before any charge) if the identity data, a usable phone number, the address, the date of birth or ID image, or, for a Nigerian customer, a valid BVN is missing.

***

## Request a Virtual Card

```graphql
mutation {
  requestVirtualCard(
    customer: "customer_id"
    label: "Groceries"
    amountUsd: 100
    reference: "your-unique-reference"
  ) {
    id
    status
    label
  }
}
```

<table><thead><tr><th width="150">Argument</th><th width="120">Type</th><th width="94">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>customer</code></td><td><code>ID!</code></td><td><strong>Yes</strong></td><td>The ID of the customer to issue the card for. <a href="https://docs.cashramp.co/cashramp/cashramp-api/customers.md">(Create a customer)</a>.</td></tr><tr><td><code>label</code></td><td><code>String!</code></td><td><strong>Yes</strong></td><td>A name to identify the card.</td></tr><tr><td><code>amountUsd</code></td><td><code>Decimal!</code></td><td><strong>Yes</strong></td><td>The initial amount (USD) to fund the card with.</td></tr><tr><td><code>reference</code></td><td><code>String!</code></td><td><strong>Yes</strong></td><td>Your unique idempotency reference. Retrying with the same reference returns the original card instead of issuing or charging again.</td></tr></tbody></table>

The mutation returns the new card’s global `id` and its `status` (which starts as `requested`). Issuance completes asynchronously, so listen for the `virtual_card.created` webhook (or `virtual_card.creation_failed` on failure).

The mutation fails if:

* The customer's `status` is not `verified`. See [Verify a Customer](#verify-a-customer).
* The customer's KYC details are missing: no identity data, no usable phone number, no address, no date of birth or ID image where one is needed, or (for a Nigerian customer) no valid BVN. Submit these first with [`submitCustomerKyc`](#submit-customer-kyc).
* Your Cashramp balance is insufficient to cover the funding amount plus fees.
* `amountUsd` is below the minimum or above the maximum funding amount (see [Virtual Card Info](#virtual-card-info)).
* Card creation is currently unavailable.

## Important Notes

* The card is issued in the **customer’s** name and requires the customer to be verified through [`verifyMerchantCustomer`](#verify-a-customer), with their identity details submitted via [`submitCustomerKyc`](#submit-customer-kyc).
* You are charged the **creation fee**, the **funding fee**, and the **funding amount** from your Cashramp balance. Fetch current fees and limits via [`virtualCardInfo`](#virtual-card-info).
* `reference` makes the request idempotent. Always send a unique reference per intended card so timeouts and retries never double-issue.

***

## Fund a Virtual Card

```graphql
mutation {
  fundVirtualCard(virtualCard: "virtual_card_id", amountUsd: 50, reference: "your-unique-reference")
}
```

<table><thead><tr><th width="150">Argument</th><th width="120">Type</th><th width="94">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>virtualCard</code></td><td><code>ID!</code></td><td><strong>Yes</strong></td><td>The ID of the card to fund.</td></tr><tr><td><code>amountUsd</code></td><td><code>Decimal!</code></td><td><strong>Yes</strong></td><td>The amount (USD) to add to the card.</td></tr><tr><td><code>reference</code></td><td><code>String!</code></td><td><strong>Yes</strong></td><td>Your unique idempotency reference. Retrying with the same reference will not fund the card twice.</td></tr></tbody></table>

Returns `true` when the top-up is accepted. The card is credited asynchronously; a `virtual_card.funded` webhook is delivered on completion. If the top-up fails, the amount and fee are refunded to your balance and a `virtual_card.funding_failed` webhook carries your `reference`.

The mutation fails if the card is not active, the amount is outside the allowed funding range, or your balance is insufficient.

***

## Withdraw from a Virtual Card

```graphql
mutation {
  withdrawFromVirtualCard(virtualCard: "virtual_card_id", amountUsd: 25, reference: "your-unique-reference")
}
```

<table><thead><tr><th width="150">Argument</th><th width="120">Type</th><th width="94">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>virtualCard</code></td><td><code>ID!</code></td><td><strong>Yes</strong></td><td>The ID of the card to withdraw from.</td></tr><tr><td><code>amountUsd</code></td><td><code>Decimal!</code></td><td><strong>Yes</strong></td><td>The amount (USD) to withdraw from the card back to your balance.</td></tr><tr><td><code>reference</code></td><td><code>String!</code></td><td><strong>Yes</strong></td><td>Your unique idempotency reference. Retrying with the same reference will not withdraw twice.</td></tr></tbody></table>

Returns `true` when the withdrawal request is accepted by the card issuer. This does **not** mean the funds have arrived: the withdrawal completes asynchronously, and your Cashramp balance is credited only once the issuer confirms it. Listen for the `virtual_card.withdrawal_completed` webhook before treating the funds as received.

***

## Reveal Card Details

```graphql
mutation {
  unmaskVirtualCard(virtualCard: "virtual_card_id") {
    cardNumber
    cvv
  }
}
```

<table><thead><tr><th width="150">Argument</th><th width="120">Type</th><th width="94">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>virtualCard</code></td><td><code>ID!</code></td><td><strong>Yes</strong></td><td>The ID of the card to unmask.</td></tr></tbody></table>

Returns the full **PAN** (`cardNumber`) and **CVV**. This is the only operation that returns unmasked card details. Every read (`virtualCard`, `virtualCards`) returns a masked number only.

{% hint style="danger" %}
Card secrets are sensitive. Never log or store the unmasked `cardNumber`/`cvv`; render them directly to the cardholder over a secure channel.
{% endhint %}

***

## Freeze or Unfreeze a Virtual Card

```graphql
mutation {
  toggleVirtualCardFreeze(virtualCard: "virtual_card_id")
}
```

<table><thead><tr><th width="150">Argument</th><th width="120">Type</th><th width="94">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>virtualCard</code></td><td><code>ID!</code></td><td><strong>Yes</strong></td><td>The ID of the card to freeze or unfreeze.</td></tr></tbody></table>

Toggles the card between active and frozen. Returns `true` on success. A `virtual_card.frozen` or `virtual_card.unfrozen` webhook is delivered, including when the card issuer freezes the card.

***

## Delete a Virtual Card

```graphql
mutation {
  deleteVirtualCard(virtualCard: "virtual_card_id")
}
```

<table><thead><tr><th width="150">Argument</th><th width="120">Type</th><th width="94">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>virtualCard</code></td><td><code>ID!</code></td><td><strong>Yes</strong></td><td>The ID of the card to delete.</td></tr></tbody></table>

Terminates the card and refunds any remaining balance to your Cashramp balance. Returns `true` on success. A `virtual_card.deleted` webhook is delivered on completion, with a `reason` (see [Webhooks](https://docs.cashramp.co/cashramp/introduction/webhooks.md#example-payloads)).

***

## Fetch a Customer’s Virtual Cards

```graphql
query {
  virtualCards(customer: "customer_id", status: active) {
    id
    label
    brand
    balance
    availableBalance
    cardNumber # masked
    cardholderName
    expirationMonth
    expirationYear
    status
  }
}
```

<table><thead><tr><th width="150">Argument</th><th width="120">Type</th><th width="94">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>customer</code></td><td><code>ID!</code></td><td><strong>Yes</strong></td><td>The ID of the customer whose cards to list.</td></tr><tr><td><code>status</code></td><td><code>VirtualCardStatus</code></td><td>No</td><td>Optionally filter by card status.</td></tr></tbody></table>

Returns the customer’s cards with masked details. `cardNumber` is masked, so use [`unmaskVirtualCard`](#reveal-card-details) for the full PAN and CVV.

***

## Fetch a Virtual Card

```graphql
query {
  virtualCard(virtualCard: "virtual_card_id") {
    id
    label
    brand
    balance
    availableBalance
    cardNumber # masked
    cardholderName
    expirationMonth
    expirationYear
    line1
    city
    state
    country
    postalCode
    status
  }
}
```

<table><thead><tr><th width="150">Argument</th><th width="120">Type</th><th width="94">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>virtualCard</code></td><td><code>ID!</code></td><td><strong>Yes</strong></td><td>The ID of the card to fetch.</td></tr></tbody></table>

Returns the full (masked) details of a card belonging to one of your customers, or `null` if the card is not yours.

***

## Fetch a Card's Transactions

A card's transactions are a paginated field on `virtualCard`, newest first.

```graphql
query {
  virtualCard(virtualCard: "virtual_card_id") {
    transactionHistory(first: 20, after: "cursor", filter: ALL) {
      pageInfo {
        hasNextPage
        endCursor
      }
      nodes {
        id
        txType # funding | withdrawal | spend | reversal
        paymentType # credit | debit
        amount
        fee
        balance # card balance after this transaction
        description
        merchantName
        reference
        createdAt
      }
    }
  }
}
```

<table><thead><tr><th width="150">Argument</th><th width="190">Type</th><th width="94">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>first</code></td><td><code>Int</code></td><td>No</td><td>Page size, up to <strong>50</strong>.</td></tr><tr><td><code>after</code></td><td><code>String</code></td><td>No</td><td>The <code>endCursor</code> of the previous page.</td></tr><tr><td><code>filter</code></td><td><code>VirtualCardTransactionFilter</code></td><td>No</td><td><code>ALL</code> (default), <code>ONE_OFF</code>, or <code>CYCLES</code> (recurring subscription charges).</td></tr></tbody></table>

Keep requesting with `after: endCursor` while `hasNextPage` is `true`. A transaction's `id` matches `transaction.id` in the `virtual_card.transaction` webhook. Declined authorizations are not transactions and are only delivered by webhook.

| `txType`     | `paymentType` | Description                         |
| ------------ | ------------- | ----------------------------------- |
| `funding`    | `credit`      | Card was topped up                  |
| `withdrawal` | `debit`       | Funds were moved off the card       |
| `spend`      | `debit`       | A purchase or card fee              |
| `reversal`   | `credit`      | A purchase was reversed or refunded |

## Virtual Card Statuses

| Status      | Description                                      |
| ----------- | ------------------------------------------------ |
| `requested` | Card has been requested; issuance is in progress |
| `pending`   | Card is being provisioned with the card issuer   |
| `active`    | Card is issued and ready to use                  |
| `freezing`  | Card is frozen or suspended                      |

***

## Virtual Card Info

```graphql
query {
  virtualCardInfo {
    creationFee
    fundingFee
    fundingFeeType
    minimumFundingAmount
    maximumFundingAmount
    maxCardsPerMerchant
    maintenanceFee
    bookBalance
    creationAvailable
  }
}
```

Returns the current fee schedule and limits that apply when issuing and funding cards:

* `creationFee` - Fee charged to issue a card.
* `fundingFee` / `fundingFeeType` - Fee charged when funding a card, and whether it is a flat or percentage fee.
* `minimumFundingAmount` / `maximumFundingAmount` - The allowed funding range per request.
* `maxCardsPerMerchant` - Maximum number of active cards you may hold (when enforced).
* `maintenanceFee` - Recurring maintenance fee, if any.
* `bookBalance` - The book balance (USD) configured for cards.
* `creationAvailable` - Whether card issuance is currently enabled.
