API Reference

Activate a feature

Turns on a feature for a customer. For virtual_cards it creates a card application and, when the application is approved, issues a virtual card. Cards need completed KYC with a liveness check, a card-type account, and provider_data with annual_remuneration and estimated_monthly_limit. If the customer has no liveness check, the status is pending_liveness. Give the cardholder websdk_url, then call again.

crypto_wallet and international_transfers become active at once. An activation that already exists is returned unchanged. Every error is HTTP 400.

POSThttps://api.gravv.xyz/v1/risk/features/activate

Headers

Required for POST requests. 1 to 255 printable ASCII characters. A retry with the same key and body within 24 hours returns the first response.

Request Body

ID of the customer

The catalogue lists six features: virtual_cards (Cards), usd_account, eur_account and gbp_account (accounts), crypto_wallet (Wallet) and international_transfers (Payout). These routes serve cards, so send virtual_cards. Open accounts, wallets and payouts with their own APIs.

Possible values: crypto_wallet, virtual_cards, eur_account, usd_account, gbp_account, international_transfers

Optional ID of the user who made the request. An invalid value is ignored.

Data the feature needs. Only virtual_cards reads it today, and that feature requires it. Send numbers as JSON numbers.

Cardholder's yearly income. Required for virtual_cards.

Expected monthly card spend. Required for virtual_cards. When a card is issued during activation, it also becomes that card's daily limit.

Always send it for virtual_cards. It is the ID of your business's card account (type card, status active). The same card account backs every cardholder. Leaving it out fails with cards service: internal server error.

How the card is funded

Possible values: shared, own

Only with mode shared

Gravv replaces it with the IP address of the calling server when one is present. You do not need to send it.

Request Examples

{
"customer_id": "302dabcb-d4fd-4a00-a80b-afad70982614",
"feature_id": "virtual_cards",
"provider_data": {
"annual_remuneration": 12000,
"estimated_monthly_limit": 200,
"account_id": "5d9e677f-f071-4881-a861-7cdcebacd9d5"
}
}

{
"customer_id": "302dabcb-d4fd-4a00-a80b-afad70982614",
"feature_id": "crypto_wallet"
}

Responses

Status	Description
`200`	Activated, or a liveness check is needed first
`400`	Any error

200 response

Possible values: crypto_wallet, virtual_cards, eur_account, usd_account, gbp_account, international_transfers

active when activated. For virtual_cards this means the card application was submitted, not that a card was issued. pending_liveness when the cardholder must first complete a liveness check at websdk_url. Nothing is stored, so call again afterwards.

Possible values: active, pending_liveness, pending_service

Activation time in RFC 3339 format. Empty for pending_liveness.

Set when an activation already exists, and for pending_liveness

Liveness link for pending_liveness. It expires after 30 minutes.

{
"data": {
"customer_id": "302dabcb-d4fd-4a00-a80b-afad70982614",
"feature_id": "virtual_cards",
"status": "active",
"activated_at": "2026-10-13T11:20:05Z"
},
"error": null
}

{
"data": {
"customer_id": "302dabcb-d4fd-4a00-a80b-afad70982614",
"feature_id": "virtual_cards",
"status": "pending_liveness",
"activated_at": "",
"message": "Liveness verification required. Please complete the verification using the provided WebSDK URL.",
"websdk_url": "https://verify.gravv.xyz/websdk/p/example_token"
},
"error": null
}

400 response

Always null for error responses

{
"data": null,
"error": "failed to check liveness requirement: customer KYC must be completed before activating cards feature"
}

{
"data": null,
"error": "cards service: annual_remuneration must be a number of at least 1000"
}

{
"data": null,
"error": "cards service: internal server error"
}

Authorization

ApiKeyAuth

Was this page helpful?