Virtual Card

The Virtual Card API is used specifically with a VCN integration. It occurs after the contract has been authorized, as described by The VCN Flow section, and works on both Pi4 and EMP configurations.

The VCN Flow

  1. The customer completes the CA Flow and their contract is created. Merchant gets a Successful/Completed response from PayBright via Call Back URL (x_url_callback) or Complete URL (x_url_complete).

  2. PB requests Marqeta to create a Virtual Visa Card specifically for this contract.

  3. Merchant requests the virtual card details from PB in order to start processing this transaction. This is where the new GET Virtual API is called, and can be called to grab information for this transaction as many times after as they would like to continue order management.

  4. Merchant gets paid by processing a capture on the Virtual Card through their existing payment processor at time of shipment. Merchant can also process a refund on the card and return funds to PB.

  5. Marqeta notifies PB of any transaction event on the Virtual Card, and PB captures/adjusts the contract as needed


When to Call the GET Virtual Card API

As discussed, Merchants will need to get the virtual card details from PayBright for order management, including Capture and Refund of a VCN transaction. This information can be pulled using the GET Virtual Card API.

This call can only be made after the initial transaction was successfully completed. You can make the Get Card API call as many times as you want.

Running the Virtual Card API

In the body of the call, you will need the Order, or Contract Number your received as a response to Auth / AutoCapture API call

The format of the endpoint in sandbox is:{{InsertMerchantKey}}&orderNumber={{InsertContractNumber}}

The format of the endpoint in production is:{{InsertMerchantKey}}&orderNumber={{InsertContractNumber}}


Security Token

Authorization Key will be a Base 64 encoding of APIKey:APIToken string e.g.

If API Key == Z9s7Yt0Txsqbbx and API Token == W5wWvctuk3mjs9WW5A4VgW5wrtR

You need to create a Base 64 Encoding of Z9s7Yt0Txsqbbx:W5wWvctuk3mjs9WW5A4VgW5wrtR

Use for testing the Base64 encoding you create

curl --location --request GET '' \
--header 'Authorization: Basic UGF5QnJpZ2h0RGV2OlBhc3N3b3JkMTIz'

You should receive a reponse that looks like this:

    "card_token": "d2d8d574-04e7-442d-a85f-3092fe5f0a58",
    "created": "2021-05-18T17:34:15Z",
    "expiration": "0621",
    "cvv": "987",
    "pan": "1111222233334444",
    "cardholder_name": "PayBright PayBright",
    "billing_address": {
        "address1": "150 Wellington Street West",
        "city": "Toronto",
        "state": "ON",
        "postal_code": "M5J 2M4",
        "country": "CAN"

Response Body

Parameter NameParameter Contents
card token (e.g. 9eb5ac83-7567-4ee6-b2a5-d04ad7a7b1ac)
date and time of call (e.g. 2020-04-07T13:15:12Z)
card expiration date (e.g. 0323 for Mar 2023)
CVV code of the card (e.g. 999)
Primary Account Number of the card
Static parameter - will stay the same for every transaction
Cardholder’s Name (PB)
Static parameter - will stay the same for every transaction
PB address:
address1 - 155 200 Wellington St W
city - Toronto
state - ON
postal_code - M5V3C7
country - CAN