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

# FAQ

> Short answers on access, coverage, money, failure cases, compliance and testing.

Each answer is short and links to the page that covers it in full. Pricing, service levels and onboarding timelines are set in your partner agreement.

## The product

<AccordionGroup>
  <Accordion title="What is Stableyard?">
    Payment infrastructure for products that move money for their own customers. Your backend calls one API to collect, send, convert and settle across stablecoins and local payment rails. Stableyard keeps the account records, verifies every receipt before it credits it, and sends signed webhook events when something changes.

    See [Capabilities](/capabilities).
  </Accordion>

  <Accordion title="Who is it for?">
    Wallets and neobanks, merchant platforms and marketplaces, payout and payroll products, and treasury teams that want spending bound by rules.

    [Use cases](/use-cases) maps each one to the guide that builds it.
  </Accordion>

  <Accordion title="Do my customers sign up with Stableyard?">
    No. Your backend creates a Universal Payment Account (UPA) for each customer, keyed by your own user ID. Your customers have no Stableyard login. A payer on hosted checkout needs no account either.

    See [Universal Payment Account](/universal-payment-account).
  </Accordion>

  <Accordion title="Can a business hold an account?">
    Yes. Create it with `subjectType: "business"`. With no verification, it can collect and send stablecoin, hold a handle and deposit addresses, and appear under its own name at checkout.

    After hosted business verification, it can also link its own US bank, hold a USD on-ramp account and pay out to that bank. One-time bank and QR payouts to a third party are for `individual` accounts only. `subjectType` cannot be changed after creation.

    See [Business verification](/concepts/business-verification).
  </Accordion>
</AccordionGroup>

## Access and environments

<AccordionGroup>
  <Accordion title="How do I get access?">
    Stableyard provisions your organization, your app and each environment, and enables the products in your agreement. Write to [partners@stableyard.fi](mailto:partners@stableyard.fi) to start.

    Your team then manages credentials, webhook endpoints, checkout branding and settlement in the [Partner Dashboard](https://dashboard.stableyard.fi). See [Environments](/environments) and [Authentication](/authentication).
  </Accordion>

  <Accordion title="How long does onboarding take, and what does it cost?">
    Onboarding timelines, pricing, support hours and escalation paths are agreed with Stableyard and set in your partner agreement. Your fee rates are then returned by `GET /v2/partners/config`.

    See [Assessing fees](/payments/assessing-fees).
  </Accordion>

  <Accordion title="Is there a sandbox?">
    Yes. Sandbox is at `https://staging-api-v2.stableyard.fi` and production is at `https://prod-api.stableyard.fi`. Sandbox uses the same API, states and verification rules as production, with test networks and no real money.

    The two are provisioned separately. Credentials, accounts, webhook endpoints and enabled capabilities do not carry across. See [Environments](/environments).
  </Accordion>

  <Accordion title="How do I know what my app can do?">
    Call `GET /v2/partners/config` with your credential. It reports your organization's KYB status and the products, networks, assets and payment methods available to your app in that environment. Read it at startup rather than hardcoding it, because what is enabled for you can change.

    See [Capabilities](/capabilities) and [Get configuration](/api-reference/configuration/get-partner-config).
  </Accordion>
</AccordionGroup>

## Coverage

<AccordionGroup>
  <Accordion title="What is limited or not available?">
    | Capability | Status |
    | - | - |
    | Card payments | Not available |
    | Settlement to a bank account | Not supported. Settlement runs in stablecoin, to a connected wallet or a Vault |
    | New deposit addresses on Tron and Bitcoin | Issuance paused. Addresses already issued are still monitored |
    | US on-ramp accounts and payouts to a linked US bank | Available in sandbox. Confirm production availability with Stableyard |
    | Vaults | Arbitrum only, with USDC and USDT |

    See [Supported regions and currencies](/supported-regions-and-currencies).
  </Accordion>

  <Accordion title="Where does it work?">
    Stablecoin collection, sends and settlement work the same in every market, on the supported networks. Fiat rails are market by market.

    | Rail | Markets |
    | - | - |
    | US bank details that convert to stablecoin | United States |
    | Payouts to a customer's own linked bank | United States |
    | One-time bank transfers to a third party | Vietnam, Philippines |
    | Paying a local merchant's QR code | Vietnam, Philippines, Kenya |

    Chains, assets and limits are on [Supported regions and currencies](/supported-regions-and-currencies).
  </Accordion>

  <Accordion title="Do you support cards?">
    No. Card payments are not available. A payer without stablecoin can pay through fiat at checkout, where it is enabled for your app.

    See [On-ramps](/payments/on-ramps).
  </Accordion>
</AccordionGroup>

## Money

<AccordionGroup>
  <Accordion title="How do fees work, and how do I earn?">
    Every payment carries two rates in basis points: Stableyard's platform rate and your partner rate. Both are frozen onto the payment at creation and deducted together, once. Your partner fee accrues to you per movement; it is not invoiced back to you.

    Your rates are set in your agreement and returned under `fees` in `GET /v2/partners/config`. See [Assessing fees](/payments/assessing-fees).
  </Accordion>

  <Accordion title="Who absorbs the fee?">
    It depends on which amount you name.

    | You name | `amountMode` | Where the fee comes from |
    | - | - | - |
    | What the payer sends, on every receive | `collect_exact` | Deducted from it. The recipient nets less |
    | What the recipient gets, on most sends | `deliver_exact` | Added on top. The sender funds more |

    A fiat send also carries the payout rail's own fee. Its quote already includes every fee in the amount to fund, so never add them on top. See [Assessing fees](/payments/assessing-fees).
  </Accordion>

  <Accordion title="Who holds the money?">
    Value rests in the account holder's own wallet or Vault. Between a verified receipt and confirmed settlement, it sits in an escrow created for that one payment. Stableyard does not keep a spendable balance for your customers.

    See [Settlement lifecycle](/settlement/receiving-settlement) and [Reconciliation](/payments/reconciliation).
  </Accordion>

  <Accordion title="Can I show my customer a balance?">
    Not from Stableyard. `GET /v2/accounts/{accountId}/balances` is a reporting view of recorded activity, marked `custodyScope: "not_a_custody_balance"`. It can be negative and is not a live read of any wallet. Never authorize a payout against it.

    If your product shows a spendable balance, keep that ledger yourself. See [Transactions](/payments/transactions).
  </Accordion>
</AccordionGroup>

## When something goes wrong

<AccordionGroup>
  <Accordion title="What happens if a payer sends too little?">
    The payment does not complete at the lower amount. There is no partial credit. Receipts add up against the amount owed, so the payer can complete it by sending the rest before it expires. If the payer never completes, Stableyard returns what arrived.

    See [Reconciliation](/payments/reconciliation).
  </Accordion>

  <Accordion title="What if a payer pays twice, or after the payment expired?">
    A duplicate is returned to the payer, and the winning receipt settles once. Late funds are held against the original payment and returned, and an expired payment stays expired. Neither is ever credited to another payment.

    Both are reported in `incidentRecoverySummary` on the payment, separate from `refundSummary`, so a returned duplicate never makes a fulfilled order look refunded. See [Reconciliation](/payments/reconciliation).
  </Accordion>

  <Accordion title="Can a retry charge my customer twice?">
    Not if you reuse the idempotency key. Every create that moves money requires an `Idempotency-Key`. The same key with the same request returns the original result. The same key with a changed request is refused.

    After a timeout, read the payment or retry with the same key. Never create a replacement payment for a stuck one. See [Idempotency](/idempotency).
  </Accordion>

  <Accordion title="What happens when a payout fails?">
    | When it fails | What happens |
    | - | - |
    | Before funding is confirmed | Nothing was collected. Create a new payment with a fresh quote |
    | After funding is confirmed | Stableyard returns the funds to the sending account's preferred crypto settlement destination. Keep one active on every account that pays |
    | Outcome uncertain | `operationalState` becomes `requires_intervention` and Stableyard resolves it. Do not create a new payment |
    | Returned by the bank after delivery | The payment stays `succeeded` and `payment.settlement_returned` fires. Nothing is resent automatically |

    See [Settlement failures](/settlement/error-handling) and [Error handling](/payments/error-handling).
  </Accordion>

  <Accordion title="How quickly is a held payment resolved?">
    Response times and escalation paths are set in your partner agreement. A held payment reports `operationalState: "requires_intervention"` and an `operationalReasonCode`. Put it in a queue with a named owner on your side, and contact Stableyard.

    See [Error handling](/payments/error-handling).
  </Accordion>
</AccordionGroup>

## Compliance and identity

<AccordionGroup>
  <Accordion title="Do I have to verify my customers?">
    Only for fiat. Creating accounts, issuing deposit addresses, hosted checkout, public payment pages and stablecoin sends need no verification.

    Fiat needs your organization's KYB, approved once. Each account that uses a fiat rail is then verified: email and identity for an `individual`, hosted business verification for a `business`. Each bank capability is then activated per account. See [Onboarding overview](/concepts/onboarding).
  </Accordion>

  <Accordion title="Do we store identity documents or bank account numbers?">
    No. Your customer completes identity verification on a hosted page, and no API accepts identity documents from you. Identity reads return a status, eligibility and a next action, never documents or personal details.

    Bank account numbers you send are write-only: responses carry the last four digits. The exception is an on-ramp account's deposit instructions, which return its full bank details so you can show them to your customer. Never log or store them. See [Individual KYC](/concepts/individual-kyc) and [Bank accounts](/concepts/bank-accounts).
  </Accordion>
</AccordionGroup>

## Building it

<AccordionGroup>
  <Accordion title="What do I build, and what does Stableyard provide?">
    | You build | Stableyard provides |
    | - | - |
    | Your product, your screens and the customer relationship | Account records, routing, escrow and settlement behind every rail |
    | The server call that creates each payment | Hosted checkout and public payment pages, if you use them |
    | Screens that start verification and show its status | Hosted identity, business verification and compliance pages |
    | A webhook endpoint per environment that verifies signatures | Signed webhook delivery, with retries |
    | A queue with a named owner for held payments | The Partner Dashboard for your operations team |

    See [Branding and your frontend](/white-label/branding-and-frontend).
  </Accordion>

  <Accordion title="Do I need a frontend integration?">
    Not always. Payouts and transfers your backend starts have no payer screen. To collect, send payers to hosted checkout, or turn on an account's public payment page so payers can pay it by handle.

    If you build your own screens, the browser uses a payment's client secret or a short-lived client session. Your app secret never leaves your backend. See [Authentication](/authentication).
  </Accordion>

  <Accordion title="How do I test?">
    Build in sandbox with sandbox credentials. Rehearse the failure paths, not only the happy one: an underpayment, a duplicate, an expiry, a webhook replay and a retry with the same idempotency key.

    Sandbox has no simulator. Hosted verification needs a real person, and no endpoint fakes a bank deposit or settles a payout. Some fiat corridors cannot be tested end to end in sandbox: start each of those in production with a supervised low-value transfer. See [Platform tools](/payments/platform-tools) and [Environments](/environments).
  </Accordion>

  <Accordion title="Is a webhook enough to mark an order paid?">
    No. A webhook is a prompt to read the payment. Delivery is at least once, so an event can arrive twice or out of order.

    Decide from the payment's own status: `accepted` means the payer's funds were verified, and `succeeded` means the recipient's destination was credited. See [Webhooks](/webhooks) and [Reconciliation](/payments/reconciliation).
  </Accordion>

  <Accordion title="Can I use an AI coding assistant?">
    Yes. Point it at [llms.txt](https://docs.stableyard.fi/llms.txt), a machine-readable index of these docs, and at the [API reference](/api-reference). Tell it to read availability from `GET /v2/partners/config`, to send an `Idempotency-Key` on every money-moving create, and to keep the app secret on your backend.
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="Capabilities" icon="layer-group" href="/capabilities">
    What Stableyard does, and what must be enabled first.
  </Card>

  <Card title="Supported regions and currencies" icon="globe" href="/supported-regions-and-currencies">
    Markets, chains and assets, for each capability.
  </Card>

  <Card title="Environments" icon="server" href="/environments">
    Sandbox and production, and what to prove before you go live.
  </Card>

  <Card title="Payments quickstart" icon="rocket" href="/payments/quickstart">
    Read your configuration, create an account and take a first payment in sandbox.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.