Manage ghost cards with the API

A ghost card is a multi-use virtual card for paying a specific vendor over time, rather than for a single payout. It suits recurring or discretionary vendor spend with configurable limits. This guide covers creating ghost cards, updating their status, and canceling them through the API. For how ghost cards compare to single-use virtual cards, see Cards overview.

Considerations

When working with ghost cards, keep the following in mind:

• Only one active ghost card can exist per vendor per paypoint. If the vendor already has one, the create request fails. To issue a new card to the same vendor, cancel the existing card first. Canceled and expired cards don’t count toward this limit. See Cancel a ghost card.
• Ghost cards are linked to a vendor. The vendor must belong to the paypoint and have an active status.
• expenseLimit is required and must be greater than 0. It can’t exceed the paypoint’s configured payout credit limit.
• Setting exactAmount to true forces maxNumberOfUses to 1, regardless of any other value you pass.
• If you set maxNumberOfUses to 0 or a negative number, it defaults to 9999.
• Card currency is always USD.

How Payabli records ghost card charges

A ghost card can be charged many times, up to the limits set on the card. Payabli records each charge as a payout transaction, whether the charge is approved or declined. These transactions appear in your Pay Out reporting alongside your other payouts, so you can query and report on them the same way.

You can also view ghost cards and their status in the Cards report under Pay Out in the Payabli Portal.

Create a ghost card

Send a POST request to /api/MoneyOutCard/GhostCard/{entry} to create a ghost card. See the API reference for full documentation.

Most fields are required, including vendorId, expenseLimit, amount, maxNumberOfUses, exactAmount, billingCycle, billingCycleDay, dailyTransactionCount, dailyAmountLimit, and transactionAmountLimit. Optional fields include expirationDate, mcc, tcc, misc1, and misc2.

curl -X POST https://api-sandbox.payabli.com/api/MoneyOutCard/GhostCard/8cfec329267 \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "vendorId": 456,
  "expenseLimit": 500,
  "amount": 500,
  "maxNumberOfUses": 3,
  "exactAmount": false,
  "expenseLimitPeriod": "monthly",
  "billingCycle": "monthly",
  "billingCycleDay": "1",
  "dailyTransactionCount": 5,
  "dailyAmountLimit": 200,
  "transactionAmountLimit": 100,
  "mcc": "5411",
  "tcc": "R",
  "misc1": "PO-98765",
  "misc2": "Dept-Finance"
}'

A successful request returns a ReferenceId in responseData. This is the card token. Store it to reference the card in subsequent operations.

{
  "responseText": "Success",
  "isSuccess": true,
  "responseData": {
    "ReferenceId": "129-219",
    "ResultCode": 1,
    "ResultText": "Ghost Card created"
  }
}

Update a card’s status

Send a PATCH request to /api/MoneyOutCard/card/{entry} to update a card’s status. See the API reference for full documentation.

Pass the cardToken (the ReferenceId from the create response) and the new status. Valid statuses are Active, Inactive, Cancelled, and Expired.

Not all status transitions are allowed:

The following example cancels a card by setting its status to Cancelled.

curl -X PATCH https://api-sandbox.payabli.com/api/MoneyOutCard/card/8cfec329267 \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "cardToken": "gc_abc123def456",
  "status": "Cancelled"
}'

A successful response confirms the status change.

{
  "responseText": "Success",
  "isSuccess": true
}

Cancel a ghost card

Send a DELETE request to /api/MoneyOutCard/GhostCard/{cardToken} to cancel a ghost card. See the API reference for full documentation.

Canceling a ghost card frees the vendor’s slot, so you can issue the vendor a new ghost card. The cancellation is always a soft delete: Payabli keeps the card record and its transaction history. You can’t use or reactivate a canceled card.

Your OAuth credentials need the vcard_delete permission, which is separate from the permission to create cards. Pass the card token (the ReferenceId from the create response) in the path. The request has no body.

curl -X DELETE https://api-sandbox.payabli.com/api/MoneyOutCard/GhostCard/gc_abc123def456 \
     -H "Authorization: Bearer <token>"

A successful response returns the card token and a deleteType of soft.

{
  "isSuccess": true,
  "responseData": {
    "deleteType": "soft",
    "cardToken": "gc_abc123def456"
  }
}

The request fails in these cases:

If the card issuer declines the cancellation, the card isn’t canceled. The response returns a resultCode of 2 with the decline reason.

Related resources

See these related resources to help you get the most out of Payabli.