Allowances

Allowances limit what can be topped up onto a card. They can be set per month or all time. They can be used for two use cases:

• Share a balance across cards
• Limit the amount of cash in the system

This page will explain how to manage allowances by API and has the following sections:

• Allowance use cases
• Enabling the allowance
• Checking the allowance
• Top up the allowance
• Get the allowance history

Initiating allowances can also be done manually in the user management section of our web app.

Allowance use cases

To share a balance across different cards, you should do the following:

• Create a user and enable the allowance
• Top up the allowance
• Allow a user to transfer money between cards themselves. This will be done automatically on our UI: a user with allowance left can top up and down their own cards

To explain how to limit the amount of cash in the system, let's use an example. Let's say you want to give 20 users £500. Normally that would mean you need to put 20 * £500 = £10,000 of cash on the system. Allowances enable you to give each user £500 in allowance but only £200 in cash so you only need to put £4,000 of cash on the system. You can then enable auto top-ups or allow the users to top up their own cards to make sure the user can spend their full allowance.

Enabling the allowance

You have to enable allowances for a user like this:

curl {baseURL}/users
-H "Authorization:your-api-key"  
-H "Content-type: application/json"  
-X POST  
-d '{
    "allowance": {
        "allowanceInCents": 50000,
        "allowancePeriod": "ALL_TIME/MONTH",
        "allowanceCurrency": "GBP"
    },
    ...
}'

The allowanceInCents is the initial allowance. It is most useful if you want to give a user the same allowance every month or just a fixed all time allowance. If the allowance fluctuates, you can set the allowancInCents to 0 and top up the allowance as you go.

The allowancePeriod only applies if the allowanceInCents is not 0. If you want to top up the allowance as you go you should set it to ALL_TIME.

ALL_TIME it means the allowance does not renew and MONTH means the allowance renews every month. Allowances do not roll over so if a user has £100 left of their £500 allowance at the end of the month, they will only get a £400 additional allowance next month.

"..." are all the other fields required to update a user. This example is a POST but the same fields can also be provided on PUT on /users.

📘

You have to enable the allowance for a user

None of the APIs listed below will work unless you have enabled the allowance for a user

Checking the allowance

The allowance can be checked like this:

curl {baseURL}/cards/allowances?userId=user-id  
-H "Authorization:your-api-key"  
-X GET

The response will look like this

{
   "userAllowances": [
       {
           "allowanceId": "allowance-id",
           "yordexUserId": "[email protected]",
           "allowanceInCents": 0,
           "allowancePeriod": "ALL_TIME",
           "allowanceCurrency": "GBP",
           "allowanceLeftToTopUpInCents": 35000,
           "allowanceLeftToSpendInCents": 40000,
           ...
       }
   ]
}

In this case, an allowanceLeftToTopUpInCents of £350 can still be topped up on the cards but an allowanceLeftToSpendInCents of £400 is left to spend. That means £50 is still sitting on the card and has not yet been used.

📘

Card payments do not affect the allowance

Card payments do not affect the allowance they only affect the allowanceLeftToSpend field. The allowance only goes up or down when the card or the allowance is topped up.

Topping up the allowance

You can top the allowance up or down like this:

curl {baseURL}/cards/card-id/ownpayments
-H "Authorization:your-api-key"  
-H "Content-type: application/json"  
-X POST  
-d '{
  "debitCredit": "CREDIT/DEBIT",
  "amountInCents": 10000,
  "date": "2020-10-10",
  "description": "Additional allowance",
  "customerTransactionId": "your-transction-id"
}'

debitCredit means you add (CREDIT) or remove (DEBIT) money from the allowance. The customerTransactionId is an optional field and can be used to link the allowance to a transaction to a transaction in your own system.

Getting the allowance history

You can get the allowance history like this:

curl {baseURL}/cards/allowances/allowance-id/allowanceusagehistory?page=0&size=10 
-H "Authorization:your-api-key"  
-X GET

The response will look like this

{
   "content": [
       {
           "updateAmountInCents": 61477,
           "updateCurrency": "GBP",
           "recordedId": "fa565ad1-c971-4283-a688-df8390493914",
           "allowanceSource": "OWN_PAYMENT",
           "usageDate": "2021-11-16",
           "details": {
               "lastDigits": "0005"
           }
       }
   ]
   "page": {
       "size": 10,
       "totalElements": 2,
       "totalPages": 1,
       "number": 0
   }
}

There can be two allowanceSources:

• OWN_PAYMENT: which is where you topped up the allowance
• TOP_UP: which is where a card was topped up or down

As mentioned before, card payments do not affect the allowance they only affect the allowanceLeftToSpendInCents field.