Manage virtual cards with the API
Learn how to retrieve, renew, send, and cancel single-use virtual cards with the Payabli API
A single-use virtual card is tied to a specific payout and can be used only once. This guide covers retrieving, renewing, sending, and canceling single-use virtual cards through the API. For how they compare to ghost cards, see Cards overview.
Create a virtual card
A single-use virtual card has no standalone create endpoint. You create one when you authorize a payout with vcard as the payment method, or when a vendor selects a virtual card as the payment method through a vendor link. The card is then tied to that payout.
To create a virtual card, send a POST request to /api/MoneyOut/authorize with paymentMethod.method set to vcard. See the API reference for full documentation.
The response returns the payout’s referenceId in responseData. The card’s own token appears in the payout’s payment-method details, as CardToken. You need that token to retrieve, renew, or cancel the card. To find it on an existing payout, see Audit payout transactions with the API.
Retrieve a virtual card
To get the details of a single virtual card in an entrypoint, send a GET request to /api/MoneyOut/vcard/{cardToken}. See the API reference for full documentation.
The response returns the expiration date, current balance, usage counts, and the associated vendor. The card number and CVC are masked, so use this endpoint for card status and balance rather than to retrieve usable card credentials.
Renew a virtual card
To extend the expiration date of an expired or expiring virtual card, send a PUT request to /api/MoneyOutCard/vcard/{cardToken}/renew. See the API reference for full documentation.
The card must not have been used yet. Pass the new expirationDate in MM-YYYY or MM/YYYY format, no more than 2 years and 363 days in the future. The card expires on the last day of the month you specify.
On success, referenceId holds the renewed card’s token. The card processor may issue a new token, so store the returned value.
Send a virtual card link
To email a virtual card link to the vendor associated with a payout, send a POST request to /api/MoneyOut/vcard/send-card-link. See the API reference for full documentation.
Pass the transId of the payout. Payabli sends the link to the vendor’s email on file.
A successful response returns success: true and the secure link sent to the vendor.
Cancel a virtual card
Virtual cards have no hard delete. To cancel a virtual card, send a PATCH request to /api/MoneyOutCard/card/{entry} with the card’s status set to Cancelled. See the API reference for full documentation.
Pass the cardToken and the new status. Valid statuses are Active, Inactive, Cancelled, and Expired. Cancelled is terminal — a canceled card can’t be reactivated.
A successful response confirms the status change.
Related resources
See these related resources to help you get the most out of Payabli.
Prerequisites
- Cards overview - Understand how single-use virtual cards and ghost cards differ