Configure card transactional limits
Learn how to define specific transactional limits for a card. This guide explains how to set spending caps for different periods or transaction types to control spending.
The user in this document pertains to both the individual and business user types.
Use Cases
- You want to add additional transaction limitations on top of the default global limits configured in the user account.
- You want to set transaction limits on a specific card based on the transaction category of the card transaction.
- You want to set transaction limits on a specific card, adding interval and velocity parameters. e.g., daily, weekly, and monthly limits.
- You want to block spending on a specific transaction category. e.g. blocking of ATM withdrawal
Prerequisites
- The user profile risk assessment status must not be
risk_flagged. - The user profile must be in an
activestatus. - The user must have an
approvedKYC or KYB status. - The user account or wallet must be in an
activestatus. - The user card must be in an
activestatus.
API Workflow
1
Retrieve the platform-defined transaction categories
First, we need to get the correct transaction category ID generated in the system during program setup.
Call Get Transaction Categories (GET /oauth/consumer/transaction/categories) to get the list of supported categories defined in the program.
Please note that this API is called on the admin scope, so it X-Auth-User-ID should not be passed in the header.
Get Transaction Categories request
CURL
curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/oauth/consumer/transaction/categories' \
--header 'Authorization: ••••••'Get Transaction Categories response
JSON
[
{
"id": "67e63d53432263cbe00fc05fd0643ac8",
"name": "ATM",
"label": null
},
{
"id": "386c8cd58faeb68175b6261450a49e53",
"name": "ATM_DOMESTIC",
"label": null
},
{
"id": "9789ec5907cc9f5854b5d8f57fa30ed9",
"name": "ECOM",
"label": null
},
{
"id": "69ca5d99cc4a8bb16bb170efacb0de5b",
"name": "ECOM_DOMESTIC",
"label": null
},
{
"id": "6ae4dd74ea2a4c2a8639645477ecc231",
"name": "POS_CONTACTLESS",
"label": null
},
{
"id": "453cd0fb0d5de3f85bf098ea86ac2fc2",
"name": "POS",
"label": null
},
{
"id": "d4f9c272aeb7b671a545d75811b7c48c",
"name": "TOPUP",
"label": "topup"
},
{
"id": "c1bc4715f4172078e926912f191972d8",
"name": "DEDUCT",
"label": "deduct"
},
{
"id": "830eacca2657aa5da668f164626cbafa",
"name": "LOAD",
"label": "load"
},
{
"id": "47e22a9490c8e7ba8fde098551cfeaba",
"name": "UNLOAD",
"label": "unload"
},
{
"id": "ff26a9df02697cf4396eb70cb8d28b0b",
"name": "TRANSFER_IN",
"label": "transfer_in"
},
{
"id": "8d59b769f3107052a6e9e4e9875ae362",
"name": "TRANSFER_OUT",
"label": "transfer_out"
},
{
"id": "a712ce34747f7a3496cc4eaa5157d3a9",
"name": "REMITTANCE",
"label": "remittance"
}
]Applicable transaction categories for card transactions:
*Domestic will be based on the region where your program and cards are issued.
| Card transaction limits for *domestic and international ATM withdrawals |
| Card transaction limits for *domestic ATM withdrawals |
| Card transaction limits for *domestic and international online e-commerce payments |
| Card transaction limits for *domestic online e-commerce payments |
| Card transaction limits for *domestic and international point-of-sale (POS) terminal payments |
| Card transaction limits for *domestic point-of-sale (POS) terminal payments |
2
Create a card transactional limit for a specific transaction category
Call the Configure Card Transactional Limit (POST /users/wallets/cards/{{card_id}}/transactions/categories/{{transaction_category_id}}/limit) setting the interval limits for the transaction category. This category limit will only apply to the specific card where it is defined.
In this example, we will configure a card transactional limit for the ATM category using the following transaction category id:
{ "id": "67e63d53432263cbe00fc05fd0643ac8", "name": "ATM", "label": null },
Configure Card Transactional Limit request
Bash
curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/{{card_id}}/transactions/categories/67e63d53432263cbe00fc05fd0643ac8/limit' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••' \
--data-urlencode 'enable=true' \
--data-urlencode 'values=[
"{\"amount\": 10,\"interval\": \"unit\"}",
"{\"amount\": 100,\"interval\": \"daily\",\"count\": 3}",
"{\"amount\": 200,\"interval\": \"weekly\",\"count\": 4}",
"{\"amount\": 300,\"interval\": \"monthly\",\"count\": 5}",
"{\"amount\": 400,\"interval\": \"annual\", \"count\": 6}",
"{\"amount\": 500,\"interval\": \"lifetime\",\"count\": 7}"
]'Configure Card Transactional Limit response
JSON
{
"id": "ecfc55bda36d97a00cb650b023cc9544",
"enable": true,
"card_limits": [
{
"amount": 10,
"interval": "unit"
},
{
"amount": 100,
"interval": "daily",
"count": 3
},
{
"amount": 200,
"interval": "weekly",
"count": 4
},
{
"amount": 300,
"interval": "monthly",
"count": 5
},
{
"amount": 400,
"interval": "annual",
"count": 6
},
{
"amount": 500,
"interval": "lifetime",
"count": 7
}
],
"program_limits": {
"pre_kyc": [
{
"amount": 0,
"count": 0,
"interval": "daily"
}
],
"post_kyc": [
{
"amount": 2500,
"count": 3,
"interval": "daily"
}
]
},
"wallet_limits": null,
"user_details_set": true
}3
List all defined transactional limits for a specific card
Call the Retrieve Card Transactional Limits (GET /users/wallets/cards/{{card_id}}/transactions/categories/limit) to get the list of enabled and disabled card transactional limits affecting the card.
Retrieve Transactional Limit request
Bash
curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/{{card_id}}/transactions/categories/limit' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Authorization: ••••••'Retrieve Transactional Limit response
JSON
{
"ATM": {
"id": "ecfc55bda36d97a00cb650b023cc9544",
"enable": true,
"user_details_set": true,
"program_limits": {
"pre_kyc": [
{
"amount": 0,
"count": 0,
"interval": "daily"
}
],
"post_kyc": [
{
"amount": 2500,
"count": 3,
"interval": "daily"
}
]
},
"card_limits": [
{
"amount": 10,
"interval": "unit"
},
{
"amount": 100,
"interval": "daily",
"count": 3
},
{
"amount": 200,
"interval": "weekly",
"count": 4
},
{
"amount": 300,
"interval": "monthly",
"count": 5
},
{
"amount": 400,
"interval": "annual",
"count": 6
},
{
"amount": 500,
"interval": "lifetime",
"count": 7
}
]
},
"ATM_DOMESTIC": {
"id": "ecfc55bda36d97a00cb650b023cc9544",
"enable": false,
"user_details_set": false
},
"ECOM": {
"id": "ecfc55bda36d97a00cb650b023cc9544",
"enable": true,
"user_details_set": false
},
"ECOM_DOMESTIC": {
"id": "ecfc55bda36d97a00cb650b023cc9544",
"enable": true,
"user_details_set": false
},
"POS_CONTACTLESS": {
"id": "ecfc55bda36d97a00cb650b023cc9544",
"enable": true,
"user_details_set": false
},
"POS": {
"id": "ecfc55bda36d97a00cb650b023cc9544",
"enable": true,
"user_details_set": false
},
"TOPUP": {
"id": "ecfc55bda36d97a00cb650b023cc9544",
"enable": true,
"user_details_set": false,
"program_limits": {
"pre_kyc": [
{
"amount": 750,
"interval": "unit"
},
{
"amount": 2250,
"interval": "daily"
},
{
"amount": 2250,
"interval": "weekly"
},
{
"amount": 2250,
"interval": "monthly"
},
{
"amount": 15000,
"interval": "annual"
},
{
"amount": null,
"interval": "lifetime"
}
],
"post_kyc": [
{
"amount": 500000,
"interval": "unit"
},
{
"amount": 500000,
"interval": "daily"
},
{
"amount": 500000,
"interval": "weekly"
},
{
"amount": 1000000,
"interval": "monthly"
},
{
"amount": null,
"interval": "annual"
},
{
"amount": null,
"interval": "lifetime"
}
]
}
},
"DEDUCT": {
"id": "ecfc55bda36d97a00cb650b023cc9544",
"enable": true,
"user_details_set": false,
"program_limits": {
"pre_kyc": [
{
"amount": 750,
"interval": "unit"
},
{
"amount": 2250,
"interval": "daily"
},
{
"amount": 2250,
"interval": "weekly"
},
{
"amount": 2250,
"interval": "monthly"
},
{
"amount": 15000,
"interval": "annual"
},
{
"amount": null,
"interval": "lifetime"
}
],
"post_kyc": [
{
"amount": 500000,
"interval": "unit"
},
{
"amount": 500000,
"interval": "daily"
},
{
"amount": 500000,
"interval": "weekly"
},
{
"amount": 1000000,
"interval": "monthly"
},
{
"amount": null,
"interval": "annual"
},
{
"amount": null,
"interval": "lifetime"
}
]
}
},
"LOAD": {
"id": "ecfc55bda36d97a00cb650b023cc9544",
"enable": true,
"user_details_set": false,
"program_limits": {
"pre_kyc": [
{
"amount": 750,
"interval": "unit"
},
{
"amount": 2250,
"interval": "daily"
},
{
"amount": 2250,
"interval": "weekly"
},
{
"amount": 2250,
"interval": "monthly"
},
{
"amount": 15000,
"interval": "annual"
},
{
"amount": null,
"interval": "lifetime"
}
],
"post_kyc": [
{
"amount": 500000,
"interval": "unit"
},
{
"amount": 500000,
"interval": "daily"
},
{
"amount": 500000,
"interval": "weekly"
},
{
"amount": 1000000,
"interval": "monthly"
},
{
"amount": null,
"interval": "annual"
},
{
"amount": null,
"interval": "lifetime"
}
]
}
},
"UNLOAD": {
"id": "ecfc55bda36d97a00cb650b023cc9544",
"enable": true,
"user_details_set": false,
"program_limits": {
"pre_kyc": [
{
"amount": 750,
"interval": "unit"
},
{
"amount": 2250,
"interval": "daily"
},
{
"amount": 2250,
"interval": "weekly"
},
{
"amount": 2250,
"interval": "monthly"
},
{
"amount": 15000,
"interval": "annual"
},
{
"amount": null,
"interval": "lifetime"
}
],
"post_kyc": [
{
"amount": 500000,
"interval": "unit"
},
{
"amount": 500000,
"interval": "daily"
},
{
"amount": 500000,
"interval": "weekly"
},
{
"amount": 1000000,
"interval": "monthly"
},
{
"amount": null,
"interval": "annual"
},
{
"amount": null,
"interval": "lifetime"
}
]
}
},
"TRANSFER_IN": {
"id": "ecfc55bda36d97a00cb650b023cc9544",
"enable": true,
"user_details_set": false,
"program_limits": {
"pre_kyc": [
{
"amount": 750,
"interval": "unit"
},
{
"amount": 2250,
"interval": "daily"
},
{
"amount": 2250,
"interval": "weekly"
},
{
"amount": 2250,
"interval": "monthly"
},
{
"amount": 15000,
"interval": "annual"
},
{
"amount": null,
"interval": "lifetime"
}
],
"post_kyc": [
{
"amount": 500000,
"interval": "unit"
},
{
"amount": 500000,
"interval": "daily"
},
{
"amount": 500000,
"interval": "weekly"
},
{
"amount": 1000000,
"interval": "monthly"
},
{
"amount": null,
"interval": "annual"
},
{
"amount": null,
"interval": "lifetime"
}
]
}
},
"TRANSFER_OUT": {
"id": "ecfc55bda36d97a00cb650b023cc9544",
"enable": true,
"user_details_set": false,
"program_limits": {
"pre_kyc": [
{
"amount": 750,
"interval": "unit"
},
{
"amount": 2250,
"interval": "daily"
},
{
"amount": 2250,
"interval": "weekly"
},
{
"amount": 2250,
"interval": "monthly"
},
{
"amount": 15000,
"interval": "annual"
},
{
"amount": null,
"interval": "lifetime"
}
],
"post_kyc": [
{
"amount": 500000,
"interval": "unit"
},
{
"amount": 500000,
"interval": "daily"
},
{
"amount": 500000,
"interval": "weekly"
},
{
"amount": 1000000,
"interval": "monthly"
},
{
"amount": null,
"interval": "annual"
},
{
"amount": null,
"interval": "lifetime"
}
]
}
},
"REMITTANCE": {
"id": "ecfc55bda36d97a00cb650b023cc9544",
"enable": true,
"user_details_set": false,
"program_limits": {
"pre_kyc": [
{
"amount": 0,
"interval": "unit"
},
{
"amount": 0,
"interval": "daily"
},
{
"amount": 0,
"interval": "weekly"
},
{
"amount": 0,
"interval": "monthly"
},
{
"amount": null,
"interval": "annual"
},
{
"amount": 0,
"interval": "lifetime"
}
],
"post_kyc": [
{
"amount": 500000,
"interval": "unit"
},
{
"amount": 500000,
"interval": "daily"
},
{
"amount": 500000,
"interval": "weekly"
},
{
"amount": 1000000,
"interval": "monthly"
},
{
"amount": null,
"interval": "annual"
},
{
"amount": null,
"interval": "lifetime"
}
]
}
}
}4
Disable (or enable) a specific card transactional limit for a specific card
Call Update Transactional Limit (PUT /users/wallets/cards/{{card_id}}/transactions/categories/{{transaction_category_id}}/limit) passing the enable parameter with a true or false value.
Update Transactional Limit request (disable)
Bash
curl --location --request PUT 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/{{card_id}}/transactions/categories/{{transaction_category_id}}/limit' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••' \
--data-urlencode 'enable=false'Update Transactional Limit response (disable)
JSON
{
"id": "ecfc55bda36d97a00cb650b023cc9544",
"enable": false,
"card_limits": [
{
"amount": 10,
"interval": "unit"
},
{
"amount": 100,
"interval": "daily",
"count": 3
},
{
"amount": 200,
"interval": "weekly",
"count": 4
},
{
"amount": 300,
"interval": "monthly",
"count": 5
},
{
"amount": 400,
"interval": "annual",
"count": 6
},
{
"amount": 500,
"interval": "lifetime",
"count": 7
}
],
"program_limits": {
"pre_kyc": [
{
"amount": 0,
"count": 0,
"interval": "daily"
}
],
"post_kyc": [
{
"amount": 2500,
"count": 3,
"interval": "daily"
}
]
},
"wallet_limits": null,
"user_details_set": true
}Related Links
Was this section helpful?
On this page
- Configure card transactional limits