Kulipa API — Frequently Asked Questions (FAQ)
🔑 Authentication & API Keys
Q: How do I authenticate API requests?
Use the x-api-key header with your API key on every request over HTTPS. See Authentication docs.
Q: How do I add an additional API key or give access to a new team member?
Contact your Kulipa account manager or onboarding engineer, and provide the email addresses that need access. Multiple API keys can be provisioned per environment.
Q: What is the difference between sandbox and production keys?
They are fully isolated environments. Sandbox keys only work against test data; production keys work against real user data and real funds. Never mix them.
👤 Users
Q: I'm getting a 409 duplicate_user_error when trying to create a user.
Kulipa already has a user that matches your request—most commonly because that phone number is already registered. Do not call the create-user endpoint again; use GET /v1/users/{userId} to load the existing record and continue your integration from there.
Q: Can I delete a user or update their details?
User deletion is not currently exposed as a self-serve API endpoint. Contact Kulipa support for edge cases. You can change a user's phone number using the dedicated PUT endpoints once the required phone verification has been completed in your distributor flow. Address changes are only supported for B2B customers.
Q: Why is a user stuck in onboarding status for days?
Most often the user has not finished the required onboarding forms or steps. If those are already complete, open a support ticket in Linear with the usr-xxxx ID so the team can investigate.
✅ KYC & Verification
Q: What is an RFI and why is my user being asked for one?
A Request for Information (RFI) is a compliance step for Transaction Monitoring. Kulipa may ask for: explanation of flagged transactions, source of funds, source of wealth, and an updated professional profile. Users complete RFIs independently via a Persona link included in the RFI notification — they don't need to go through you.
Q: How do I send a new KYC verification link to a user?
Use the Resume KYC endpoint: POST /v1/kycs/{kycId}/resume. Only KYCs in status expired can be resumed; if the KYC is still pending, you must wait for it to expire (14 days) before resume is available. If the user has already completed that verification, create a new KYC through the API instead of using resume.
Q: Can we trigger the KYC resume earlier, e.g. on day 13 instead of day 14?
The resume endpoint is restricted to expired KYCs. Triggering it before expiry will return kyc_resume_not_allowed_error.
The 14-day expiry is deliberately longer than many comparable products allow, so most users have enough time to complete verification.
Q: Can we run KYC on web or in an embedded integration?
Yes. You can use Persona's hosted link in the browser or an embedded flow, depending on your product and Persona's options for your setup; desktop web flows can redirect users back to your app when they finish. On mobile, using Persona's native SDK is highly recommended instead of relying on web or embedded WebView-only flows. Contact your account manager for embedded vs hosted guidance and SDK specifics.
💳 Cards
Q: A user's card keeps declining. How do I investigate?
Check the cardAuthorization.rejected webhook event for the declineReasonCode. Common reasons:
insufficientFund— wallet balance too lowfailedControl— blocked by a spending control or MCC restriction- Card may be frozen or blocked after too many incorrect PIN/CVV entries
Contact Kulipa support with the crd-xxxx ID if the reason is unclear.
Q: A user's card is blocked because they entered their card details incorrectly too many times. Can it be unblocked?
Yes — raise a support ticket in Linear with the crd-xxxx ID. Kulipa support can unblock the card only if the user certifies that they personally entered the incorrect details (mistyped their own card information), not that someone else misused the card.
Q: Cards are declining on Netflix, iCloud, YouTube Music, Steam, and X Premium. Why?
Recurring subscription services can sometimes fail due to MCC restrictions or 3DS authentication flows. Before contacting Kulipa support, make sure this is not an isolated case—for example, check whether other merchants, cards, or users see the same behaviour. When you escalate, provide the transaction ID and crd-xxxx so we can investigate the specific decline reason.
Q: Some MCCs are now blocked. Which ones?
Kulipa periodically restricts certain Merchant Category Codes (MCCs) under AML/CFT obligations. Currently restricted MCCs include quasi-cash merchants, money transfers, weapons, and similar elevated-risk categories. Standard retail, dining, travel, and e-commerce transactions are unaffected.
Q: A physical card was shipped to the wrong address. What happened?
Physical cards use whatever shipping address is current when you call POST /v1/cards. There are two ways to set it: B2B distributors can include the shipping details in the payload when creating the user (POST /v1/users); otherwise, submit a KYC of type shipping and wait until the user has finished the form. If you use the shipping KYC, that KYC must be fully completed before card creation. Listen for the KYC webhook before triggering card creation in that flow.
Q: How do I reissue a card?
Use POST /v1/cards/{cardId}/reissue. See the Cards docs.
Q: A card can't be unfrozen — I'm getting "Card cannot be unfrozen due to additional blocks".
This means a compliance or fraud hold has been placed on the card in addition to the freeze. Raise a support ticket in Linear with the affected crd-xxxx IDs for Kulipa to investigate and clear the blocks.
💰 Wallets & Balances
Q: A deposit was made on-chain but the wallet balance isn't reflecting it.
This can happen due to processing delays or an error ingesting blockchain events (so the on-chain transfer is not reflected in wallet state). Contact Kulipa support with the wallet ID (wlt-xxxx), card ID (crd-xxxx), and on-chain transaction hash. Kulipa can manually reconcile the balance.
Q: A wallet has a negative balance. What should I do?
Negative balances can occur if a transaction was authorized for slightly more than the available balance (e.g. tip added at point-of-sale), or offline transactions. Raise a Linear ticket with the wallet ID. Final settlement may or may not fail depending on the amount.
Q: A user deposited the wrong token (e.g. USDT instead of USDC). Can we recover it?
Contact Kulipa support immediately with the wallet ID and on-chain transaction hash. Recovery may be possible depending on the token and amount — it is handled case-by-case, with no guarantee of success or ETA.
Q: What is our FX markup?
This is defined in your Order Form, check your specific agreement. Your account manager can confirm.
Q: Is USDC the only currency supported for funding?
Currently yes — USDC is the primary supported stablecoin for wallet top-ups. Future currency support is on the roadmap. Contact your account manager for latest updates.
🔔 Webhooks
Q: Webhooks are not being delivered in sandbox. Why?
Ensure your webhook endpoint is publicly accessible (not localhost), properly registered via POST /v1/webhook-subscriptions, and that the subscription is verified. Also confirm there are no firewall or IP whitelist issues on your server.
Q: How do I verify that a webhook came from Kulipa?
Use the Webhook public key endpoint to retrieve the public key and verify the signature on incoming events.
Q: The Retool dashboard shows no data even though cards are active.
This is a configuration or access issue. Raise it with your Kulipa account manager / onboarding team to check that your dashboard is linked to your program.
🔐 3DS & Digital Wallets
Q: We're getting 3DS connection timeouts.
Connection to 3ds.kulipa.xyz timed out errors indicate a connectivity issue between your infrastructure and Kulipa's 3DS server. Check that 3ds.kulipa.xyz on port 443 is reachable from your servers. Contact Kulipa support if the issue persists.
🌍 Compliance & Country Coverage
Q: Which countries can we onboard users from?
Supported countries are defined in your program configuration. EEA and LATAM are generally available. Some countries are subject to periodic restrictions based on compliance reviews by Kulipa's sponsor bank. Contact your account manager for the current definitive list, as it can change with limited notice.
Q: A country was suddenly removed from the supported list. Why?
Country suspensions can be triggered by Kulipa's sponsor bank immediately, sometimes without advance notice. Waivers for specific countries can be requested and typically take a few weeks to process. Contact your account manager.
Q: What happens when a user is flagged for suspicious activity?
Kulipa's compliance team may place a hold on a user's wallet or card, or request an RFI. You will receive webhook events for status changes. Users complete the RFI independently. If you suspect suspicious behaviour from a user, coordinate with Kulipa via your Linear support board.
🛠️ Support Process
Q: How should I raise a support request?
Use your dedicated Linear board for all user-related support tickets. Templates are available for the most common cases (KYC issues, card declines, balance discrepancies, etc.). Add as much context as possible (user ID, card ID, transaction ID). Slack should be used for system-level incidents, program discussions, and questions — not individual user tickets.
Q: What qualifies as urgent?
Reserve urgent priority for critical system issues or widespread failures — not for individual user complaints, however loud. The on-call Kulipa engineer is listed in your Slack channel daily via the Kulipa Automation bot.
Q: Where is the Kulipa backoffice dashboard?
At https://dashboard.kulipa.xyz. Contact your onboarding manager for access. The dashboard lets you view and action user, card, and transaction data, and is the primary tool for front-line support.