Virtual cards
A virtual charge card is a unique 16-digit card number that is digitally generated and linked to your Spend & Expense account.
You can create member cards and set limits based on different needs, such as budgets, users, and expiration date. In addition, you can create vendor cards and associate these cards with specific vendors.
Use POST /v3/spend/cards
to create a virtual card. You can then use GET /v3/spend/cards/{cardId}/pan-jwt
to get a JWT token for the virtual card Primary Account Number (PAN). The JWT token contains all the information required for retrieving details about a virtual card (16-digit PAN, CVV, and expiration date). The JWT token lifespan is 5 minutes.
Creating a virtual card
In this section, we create a member card and assign it to an existing budget and existing user. See Budgets and Users to learn about creating budgets and users.
In your POST /v3/spend/cards
request, set the required fields.
Field | Description |
---|---|
name | Card name |
userId | BILL-generated ID of the user |
budgetId | BILL-generated ID of the budget |
limit | Current budget spend limit assigned to the card |
See the /v3/spend/cards API for more information about the other card fields you can set.
Sample request
In this cURL example, a virtual card is created with the specified details. The userId
and budgetId
values are set to assign the card to the budget and user. A spend limit of $10
is assigned to the card.
curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/spend/cards' \
--header 'apiToken: {api_token}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"budgetId": "{budget_id}",
"limit": "10",
"name": "Happy Music Supplies card for Clark Spenderson",
"userId": "{user_id}"
}'
Response
In the response, a BILL-generated card id
is available. The currentPeriod
object provides information about the current budget assigned to the card.
NOTE
In the sandbox environment, the
status
for all created cards isFROZEN
.
{
"id": "{card_id}",
"name": "Happy Music Supplies card for Clark Spenderson",
"userId": "{user_id}",
"budgetId": "{budget_id}",
"lastFour": "4242",
"validThru": "12/25",
"status": "FROZEN",
"type": "VIRTUAL_VENDOR",
"shareBudgetFunds": false,
"recurring": false,
"currentPeriod": {
"limit": 10.00,
"spent": 0.00
},
"createdTime": "2024-12-16T20:24:35.000+00:00",
"updatedTime": "2024-12-16T20:24:35.000+00:00"
}
Getting a PAN token
The JWT token for a card contains all the information required for retrieving details about the card (16-digit PAN, CVV, and expiration date).
In your GET /v3/spend/cards/{cardId}/pan-jwt
request, set the required fields.
Field | Description |
---|---|
cardId | BILL-generated ID of the card |
Sample request
In this cURL example, a JWT token is requested for the specified card id
.
curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/spend/cards/{card_id}/pan-jwt' \
--header 'apiToken: {api_token}' \
--header 'Accept: application/json'
Response
In the response, a JWT token is available for the specified card.
JWT to PAN
You can use the JWT token from the GET /v3/spend/cards/{cardId}/pan-jwt
response to get PAN details about the card.
curl --request POST \
--url 'https://app-dev-sandbox.divvy.co/de/rest/pan' \
--header 'Content-Type: application/json' \
--data-raw '{"token":"{JWT_token}"}'
curl --request POST \
--url 'https://api.divvy.co/de/rest/pan' \
--header 'Content-Type: application/json' \
--data-raw '{"token":"{JWT_token}"}'
See the /v3/spend/cards API for more information about the Spend & Expense card operations.
Updated 18 days ago