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 and updating their status 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 ghost card can exist per vendor per paypoint. To issue a new card to the same vendor, cancel the existing card first.
• 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
}

Related resources

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