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:

• 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.

At minimum, you need to pass a vendorId and an expenseLimit. All other fields are optional and let you configure spending controls, usage limits, and merchant restrictions. For example, you can cap per-transaction spend with transactionAmountLimit, set daily limits with dailyAmountLimit and dailyTransactionCount, define an expense period with expenseLimitPeriod, or restrict merchant categories with mcc and tcc.

1
using PayabliPayabliApi;
2
using System.Threading.Tasks;
3
4
namespace Usage;
5
6
public class Example
7
{
8
    public async Task Do() {
9
        var client = new PayabliPayabliApiClient(
10
            apiKey: "YOUR_API_KEY_HERE"
11
        );
12
13
        await client.GhostCard.CreateGhostCardAsync(
14
            "8cfec2e0fa",
15
            new CreateGhostCardRequestBody {
16
                VendorId = 42L,
17
                ExpenseLimit = 500,
18
                MaxNumberOfUses = 3,
19
                ExactAmount = false,
20
                ExpenseLimitPeriod = "monthly",
21
                BillingCycle = "monthly",
22
                BillingCycleDay = "1",
23
                DailyTransactionCount = 5,
24
                DailyAmountLimit = 200,
25
                TransactionAmountLimit = 100,
26
                Mcc = "5411",
27
                Tcc = "R",
28
                Misc1 = "PO-98765",
29
                Misc2 = "Dept-Finance"
30
            }
31
        );
32
    }
33
34
}

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
using PayabliPayabliApi;
2
using System.Threading.Tasks;
3
4
namespace Usage;
5
6
public class Example
7
{
8
    public async Task Do() {
9
        var client = new PayabliPayabliApiClient(
10
            apiKey: "YOUR_API_KEY_HERE"
11
        );
12
13
        await client.GhostCard.UpdateCardAsync(
14
            "8cfec2e0fa",
15
            new UpdateCardRequestBody {
16
                CardToken = "gc_abc123def456",
17
                Status = CardStatus.Cancelled
18
            }
19
        );
20
    }
21
22
}

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