> ## Documentation Index
> Fetch the complete documentation index at: https://guides.saber.money/llms.txt
> Use this file to discover all available pages before exploring further.

# Frequently Asked Questions

> Common questions on authentication, KYC, onramp, offramp, and troubleshooting.

# Authentication & API Keys

<AccordionGroup>
  <Accordion title="How is the API signature generated?">
    The signature is an HMAC-SHA256 hash, where the key is your `api_secret` and the message is constructed as follows:

    * For client-level operations (e.g., create a user): `client_id + timestamp`
    * For user-specific operations (e.g., create a transaction): `client_id + timestamp + user_id`

    The resulting hash should be Base64-encoded and uppercased. This value goes in the `X-Signature` header. The `X-Signature` is not your raw API secret — it is the computed HMAC value.
  </Accordion>

  <Accordion title="I'm getting 'Invalid X-Api-Key or X-Client-Id' even though my credentials are active. What's wrong?">
    This almost always means the signature is being computed incorrectly — wrong field order, missing encoding step, or using the raw API secret instead of the computed HMAC. Double-check that you are signing with `api_secret` as the HMAC key, and that the output is Base64-encoded and uppercased.
  </Accordion>
</AccordionGroup>

# User Operations, KYC and Bank Account

<AccordionGroup>
  <Accordion title="What is kyc_country and when should I set it?">
    `kyc_country` determines which KYC flow (and downstream transaction capabilities) applies to a user. It should be set during user creation or via the Update User API. It is distinct from `phone_country`. If not set correctly, users may be routed to the wrong KYC flow (e.g., an Indian KYC widget for a UK-based user).
  </Accordion>

  <Accordion title="Can I add a bank account before KYC is complete?">
    No. Bank accounts can only be added after a user's KYC is verified. Attempting to add a bank account before KYC completion will result in an error.
  </Accordion>

  <Accordion title="KYC is stuck loading or returning a 500 error. What should I do?">
    This is typically caused by an upstream KYC provider issue or a missing platform configuration on the Saber side. As a fallback, try using the KYC Partner URL directly. Share the user UUID with the Saber team for investigation.
  </Accordion>

  <Accordion title="KYC shows 'Unverified' even after the user completed the process. Why?">
    There can be a sync delay between the KYC provider confirming completion and the status updating in Saber's system. If the status does not update within a reasonable time, share the user UUID with the Saber team who can manually trigger a sync.
  </Accordion>

  <Accordion title="Can I embed the Indian KYC widget (Digilocker) in an iframe?">
    No. Digilocker enforces a `Content-Security-Policy: frame-ancestors` restriction that blocks iframe embedding. The recommended approach is to:

    1. Listen for the `DIGILOCKER_URL` event from the Saber KYC widget.
    2. Open the Digilocker URL in a new browser tab.
    3. Configure a redirect URL to bring the user back to your application after completion.
  </Accordion>

  <Accordion title="The user completed KYC successfully but did not receive any confirmation. What happened?">
    This is a redirect/callback configuration issue. If the `redirect_url` is not properly configured in your integration, the user will see a blank or generic Saber page after KYC completes. Ensure your redirect URL is registered and your application is listening for the KYC success event.
  </Accordion>

  <Accordion title="A user is being asked for Indian KYC despite having a non-Indian phone number. Is this a bug?">
    Yes. This occurs when `kyc_country` is not explicitly set and the system falls back to `phone_country` for routing. Always set `kyc_country` explicitly during user creation to avoid this.
  </Accordion>

  <Accordion title="Can I reset a user's KYC if it was completed incorrectly?">
    KYC cannot be reset from the client dashboard. Contact the Saber team with the user UUID to have it reset manually.
  </Accordion>

  <Accordion title="We're reusing the same recipient across multiple remitters. Why is the PAN being rejected as 'already exists'?">
    Saber creates a separate user record for each KYC submission. If a PAN is already linked to an existing user (even with an unverified status), a duplicate submission will be rejected. Coordinate with the Saber team on a deduplication approach for shared-recipient use cases.
  </Accordion>

  <Accordion title="What does 'You cannot consume this service' mean when calling the KYC Documents API?">
    This means the KYC document submission feature has not been enabled for your client account. Contact the Saber team to have it provisioned.
  </Accordion>

  <Accordion title="Are webhooks available for KYC and bank account status updates?">
    Yes. Saber supports webhooks for both KYC verification and bank account status changes, so you do not need to poll for status. Refer to the Saber documentation for the webhook payload format and how to configure your endpoint.
  </Accordion>

  <Accordion title="Why is a bank account being rejected with 'Bank account already exists in name rejected state'?">
    Despite the wording, this error typically means a bank account was previously submitted and rejected due to a name mismatch between the account holder name and the user's KYC record. Review the KYC name and the account holder name for discrepancies before resubmitting.
  </Accordion>

  <Accordion title="What is the name_match_score in the bank account response, and what threshold triggers rejection?">
    Saber performs a name verification check between the account holder name and the user's legal KYC name. A low match score results in a `NAME_REJECTED` status. If the name on the bank account is an abbreviated or variant form of the legal name, this can cause mismatches — ensure the account holder name matches the legal name submitted during KYC as closely as possible.
  </Accordion>

  <Accordion title="How do I flag a bank account as NRE?">
    The `is_nre` field is set at the bank account level when adding the account via the Add Bank Account API. It is not a user-level property.
  </Accordion>
</AccordionGroup>

# Onramp

<AccordionGroup>
  <Accordion title="After completing open banking payment, the transaction status is still 'processing.' Is this normal?">
    Yes, in sandbox this is expected behaviour as the banking simulation does not auto-complete. In production, open banking settlement involves a short delay between the user's bank debiting the funds and the credit reaching the Saber settlement account. If funds are confirmed debited but the status does not progress, contact the Saber team with the transaction ID.
  </Accordion>

  <Accordion title="The payment in the user's bank statement shows a company name other than the recipient's name. Why?">
    This is expected. Saber acts as the collecting entity for onramp transactions, so the payee name visible to the sender's bank will reflect the Saber/collecting entity name. The recipient receives funds on the offramp leg. This is a known UX consideration — communicate this to your end users in your product flow.
  </Accordion>

  <Accordion title="How can I configure the redirect URL after payment completion?">
    The redirect URL should be registered in your client configuration. Contact the Saber team to set or update your redirect URL. After payment, the user will be redirected to this URL with the `ref_id` and `order_id` as query parameters.
  </Accordion>

  <Accordion title="Can I simulate a successful onramp in sandbox to test webhooks?">
    In sandbox, onramp transactions can be manually advanced to a completed state by the Saber team. Share the transaction IDs and request a status update. A self-serve simulation capability is a known gap.
  </Accordion>
</AccordionGroup>

# Offramp

<AccordionGroup>
  <Accordion title="What is the overall offramp architecture? Does Saber hold custody of funds?">
    Yes — Saber operates a custodial model. Onramp deposits fiat and holds the equivalent value in stablecoin (USDT/USDC) within the user's Saber account. Offramp converts that balance back to fiat and disburses to a registered bank account. There's no external wallet address involved in the standard flow.
  </Accordion>

  <Accordion title="How does the Pool Sell flow work? What is source_id?">
    The Pool Sell flow is designed for clients who hold a central (pool) wallet and disburse to multiple recipients:

    1. Create a pool user and mark it as a pool account (requires Saber-side enablement).
    2. Get the pool wallet's deposit address.
    3. For each payout, call the Pool Sell API with `source_id` set to the bank account UUID of the recipient user — not the wallet address.
  </Accordion>

  <Accordion title="Quote IDs are returning as all zeros (00000000-0000-...). Is this correct?">
    Yes, this is a known limitation for pool sell quotes. The quote is valid for pricing purposes but does not carry a persistent ID. This will be addressed in a future update.
  </Accordion>

  <Accordion title="The Pool Sell API accepts crypto_amount. Can I pass a fixed fiat_amount instead to guarantee a specific INR payout?">
    Currently, the API accepts `crypto_amount`. Passing a fixed target `fiat_amount` is a requested feature on the roadmap. In the interim, use the Sell Quote API to derive the `crypto_amount` closest to your desired fiat value, noting that the final payout may vary slightly due to rate movement between quote and settlement.
  </Accordion>

  <Accordion title="I'm getting error 901011: service configuration missing on the quote or sell API.">
    This means your client has not been fully configured for the requested currency pair or payment method. Contact the Saber team specifying the currency pair and payment method you are attempting to use.
  </Accordion>

  <Accordion title="I'm getting error 3002: invalid bank account UUID on pool sell.">
    The bank account UUID you are passing is either invalid or belongs to an account that has been rejected. Verify the bank account status via the Get User Details API before initiating a sell.
  </Accordion>

  <Accordion title="I'm getting error 304017: bank account verification pending on pool sell.">
    This means the recipient's bank account has not yet been verified. Wait for the bank account verification webhook before initiating payouts for that user.
  </Accordion>

  <Accordion title="A transaction is stuck in 'created' status with funds already debited from the user. What should I do?">
    This is the most common operational issue. It is usually caused by a banking rail issue or an aggregator routing failure. Share the affected transaction IDs with the Saber team urgently — they can manually advance or process refunds. Where refunds are involved, they are returned to the original payment source.
  </Accordion>

  <Accordion title="When does TDS apply to INR payouts?">
    1% TDS applies to 3rd party INR transfers (where the sender and recipient are different people). It does not apply to 1st party transfers (person sending to their own Indian bank account). TDS is deducted at the time of the transaction and is rebatable — recipients can claim it when filing their annual tax return.
  </Accordion>

  <Accordion title="I'm seeing TDS deducted unexpectedly on what should be a 1st party transfer. Why?">
    This can happen if you are passing the `pre_fee_to_amount` from a sell quote as the `from_amount` without correctly identifying the transfer as 1st party. Ensure the transaction is configured correctly and that the user's relationship (sender = recipient) is reflected in your API call. Contact the Saber team if the deduction appears incorrect after verification.
  </Accordion>
</AccordionGroup>

# Others

<AccordionGroup>
  <Accordion title="How can we export transaction history for reconciliation?">
    Transaction history can be exported from the Saber dashboard. For bulk or programmatic reconciliation, the Saber team can also provide reports directly.
  </Accordion>

  <Accordion title="What are the typical SLAs for INR payout processing?">
    For production volumes, typical performance targets are:

    * p50 TAT: \~1.6 minutes
    * p95 TAT: \~2–3 minutes
    * Success rate: 95–97%

    Tail-end outliers (p99) can occur during rail incidents and are investigated on a priority basis. Daily performance summaries are shared for high-volume partners.
  </Accordion>

  <Accordion title="Is there a refund API?">
    There is no self-serve refund API at this time. Refund requests must be raised with the Saber team via the support channel, specifying the transaction ID. Refunds are processed back to the original payment source.
  </Accordion>

  <Accordion title="Can I withdraw crypto (e.g., USDC) from the Saber wallet back to an external address?">
    Support for crypto withdrawals depends on the network and asset. Use the Get Supported Networks and Limits API to check which chains and tokens are currently supported for withdrawal. If a specific network (e.g., BASE chain) is not listed, contact the Saber team.
  </Accordion>
</AccordionGroup>


## Related topics

- [MCP](/getting-started/mcp.md)
- [Product Updates](/changelogs.md)