Manage ghost cards with the API

Payabli supports two types of virtual cards for Pay Out:

• Single-use virtual cards are tied to a specific payout and can only be used once. You create them by passing vcard as the payment method when you authorize a payout, or a vendor can select vCard as the payment method through a vendor link.
• Ghost cards (multi-use virtual cards) are issued directly to a vendor and aren’t tied to a specific payout. They’re designed for recurring or discretionary vendor spend with configurable limits.

This guide covers creating ghost cards and updating their status through the API.

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.

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.

1
curl -X POST https://api-sandbox.payabli.com/api/MoneyOutCard/GhostCard/8cfec2e0fa \
2
     -H "requestToken: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "vendorId": 42,
6
  "expenseLimit": 500,
7
  "amount": 500,
8
  "maxNumberOfUses": 3,
9
  "exactAmount": false,
10
  "expenseLimitPeriod": "monthly",
11
  "billingCycle": "monthly",
12
  "billingCycleDay": "1",
13
  "dailyTransactionCount": 5,
14
  "dailyAmountLimit": 200,
15
  "transactionAmountLimit": 100,
16
  "mcc": "5411",
17
  "tcc": "R",
18
  "misc1": "PO-98765",
19
  "misc2": "Dept-Finance"
20
}'

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

1
{
2
  "responseText": "Success",
3
  "isSuccess": true,
4
  "responseData": {
5
    "ReferenceId": "gc_abc123def456",
6
    "ResultCode": 1,
7
    "ResultText": "Ghost Card created"
8
  }
9
}

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:

1
curl -X PATCH https://api-sandbox.payabli.com/api/MoneyOutCard/card/8cfec2e0fa \
2
     -H "requestToken: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "cardToken": "gc_abc123def456",
6
  "status": "Cancelled"
7
}'

1
{
2
  "responseText": "Success",
3
  "isSuccess": true
4
}