> ## 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

> Straight answers on access, coverage, custody, failure cases and testing.

Every answer here is short and points at the page that owns the fact in full. Where something is not published, this page says so rather than inventing it. There is no rate card, no service level agreement and no onboarding timeline anywhere in this documentation, because none of them is a property of the platform. All three are terms in your partner agreement.

## The product

<AccordionGroup>
  <Accordion title="What is Stableyard?">
    Payment infrastructure for products that move stablecoins on behalf of their own customers. Your backend calls one API. Stableyard creates the account records, moves the money, verifies independently that it arrived, keeps the record, and delivers signed events when something changes.

    The premise in full, including what Stableyard is not, is on [Capabilities](/capabilities).
  </Accordion>

  <Accordion title="Who is it for?">
    Neobanks and consumer wallets, merchant platforms and marketplaces, payroll and disbursement products, subscription and billing products, and treasury products that need spend bounded by rules.

    Which capabilities does my product need? maps eight product shapes to the capability set each one turns on, and names the constraint that will shape your plan before you write code.
  </Accordion>

  <Accordion title="Do my customers have to create an account with Stableyard?">
    Your customer never registers with Stableyard. Your backend creates a Universal Payment Account (UPA) for them, addressed by your own user ID, and that is the whole of it. There is no second signup and no Stableyard login for your users.

    Payers need nothing at all. Someone paying your merchant on a hosted page has no account, no login and no wallet on file. [Understanding Universal Payment Accounts](/universal-payment-account) is the concept in full.
  </Accordion>

  <Accordion title="Can a business hold an account?">
    Yes, and it works completely for crypto: wallets, a permanent handle, its own name and logo at checkout, a payment link, deposit addresses, and stablecoin send and receive.

    It is refused on every path that crosses into a bank, by name, in every corridor, because business verification does not exist today. Not partially, not behind a switch, and not on a published date. [Who can hold an account](/universal-payment-account) is exact about which nine operations fail and what to do instead.
  </Accordion>
</AccordionGroup>

## Access and environments

<AccordionGroup>
  <Accordion title="How do I get access?">
    Access is provisioned by the Stableyard team, not by a signup form. Your organization, your app, each environment, the modules the app is entitled to, the rails and corridors switched on inside it, your fee rates and the single Partner Dashboard owner email are all created for you.

    What you do yourself starts one level down: minting app secrets after the first, pointing a webhook endpoint, choosing where money settles, setting checkout branding, and deciding what your customer sees. [What launch requires of you](/environments) is the full split.
  </Accordion>

  <Accordion title="How long does onboarding take, and what is the commercial gate?">
    Not published, and this documentation will not invent a number. Lead times, the commercial gate in front of any capability, support hours and escalation paths are agreed with the Stableyard team per capability and per environment. Ask for them in writing, naming the environment, before you commit to a launch date.
  </Accordion>

  <Accordion title="Is there a sandbox?">
    There is a staging environment at `https://staging-api-v2.stableyard.fi` and production at `https://prod-api.stableyard.fi`. Staging runs the same verification, the same state machine and the same reconciliation as production, with no real money.

    Staging and production are provisioned separately and nothing is inherited. A capability proven on staging is still off in production until Stableyard grants it there, and credentials belong to one environment and cannot see the other's data.
  </Accordion>

  <Accordion title="How do I know what my own app can actually do?">
    Call `GET /v2/partners/config`. Everything on this site describes what Stableyard can do; that call is the only honest answer for your credential, in your environment, right now. Read it at startup rather than hardcoding it, because a capability set can change without a documentation deploy.

    The four independent reasons a capability is off for you, and which of them you can fix yourself, are on [What's live, and how it gets switched on](/supported-regions-and-currencies). How to read the response is on [Runtime configuration](/capabilities).
  </Accordion>
</AccordionGroup>

## What is live

<AccordionGroup>
  <Accordion title="What is live, and what is not?">
    Live: customer accounts, handles and payer-facing identity; hosted checkout and direct crypto receive; crypto sends and internal transfers; reusable deposit addresses; identity verification where the module is enabled.

    Not live, stated plainly because these are the ones a partner reasonably assumes are: card payments do not exist and there is no provider behind them; a customer's verified bank account cannot yet receive settlement; bank funding accounts for US customers are certified on staging with no production path; business verification does not exist; deposit-address issuance is paused for Tron and Bitcoin.

    Limited: local currency payouts, Vaults, cross-chain routed pay-in, hosted fiat on-ramp, and regulated capability activation. [What's live, and how it gets switched on](/supported-regions-and-currencies) carries a status word and the exact constraint behind it for every capability.
  </Accordion>

  <Accordion title="Where does it work?">
    Two different questions. Creating an account and everything crypto has no country restriction at all.

    Fiat is narrow and specific. Local currency payouts run in Vietnam, the Philippines and Kenya, and Kenya is scan-to-pay only with no bank fallback. A customer's own bank can be linked in the United States, the Philippines and Vietnam, and only the United States route executes a payout. Bank funding accounts are United States only. The published bank-field catalogue covers fifty countries, and three of them are implemented: the rest are input contracts, not corridors.

    Twelve chains are registered and they do not all do the same things. [Markets, chains and assets](/supported-regions-and-currencies) is the coverage truth, per chain and per corridor.
  </Accordion>

  <Accordion title="Do you support cards?">
    No. There is an entitlement for card payments and nothing behind it. The catalogue reports it as not released and configuration reports it as not operational. Do not plan around it.
  </Accordion>
</AccordionGroup>

## Money

<AccordionGroup>
  <Accordion title="What does it cost, and how do I earn?">
    Stableyard charges in basis points on the amount independently verified to have landed. Your own take rides in the same waterfall as a partner rate in basis points, summed with the platform rate and deducted once, at final settlement, in USD terms. Your revenue share is collected by the same mechanism rather than invoiced back to you.

    **No rate card is published and there is not one anywhere in this documentation.** Your platform rate and your partner rate are set in your partner agreement and returned to your app by configuration. How and when your accrued balance is remitted to you is a commercial term, not an API behaviour. Fees, and what you earn works the arithmetic through on a real amount.
  </Accordion>

  <Accordion title="Who absorbs the fee?">
    It depends which side you named the amount on. On a receive payment you name what the payer transfers, so the recipient nets less than the sticker price. On a local currency payout you name what the recipient receives, so the sender absorbs it and every fee is already inside the funding figure your customer authorizes.

    On a payout there are three fee components rather than two, because the local provider's fee joins them. All three are quoted in the funding stablecoin. Showing that total as a surcharge on top of the funding figure double-charges your customer. See Fees, and what you earn.
  </Accordion>

  <Accordion title="Who holds the money?">
    Your customer, in their own wallet, Vault or bank, except for the interval between a verified receipt and a confirmed settlement. In that interval the funds sit in a Stableyard escrow created for that one payment, which is funded once and then closes.

    There is no pooled account holding your customers' money and no number inside Stableyard representing a claim a customer could withdraw. Who holds the money, and who is responsible has the moment-by-moment table, and [Reconciliation](/payments/reconciliation) is the page to hand a risk committee.
  </Accordion>

  <Accordion title="Can I show my customer a balance?">
    Not a bank-style one. What the API reports is recorded activity: a reconciliation view of money that has already moved, on Stableyard's own timeline. It is not a live read of any wallet and not a guarantee that funds are currently held anywhere recoverable. A "sufficient funds" check built on it will eventually produce a false positive.

    [Transactions](/payments/transactions) says what to put on the screen instead.
  </Accordion>
</AccordionGroup>

## When something goes wrong

<AccordionGroup>
  <Accordion title="What happens if a payer sends too little?">
    Nothing settles. There is no partial credit path and there will not be one: if your customer owes 25.00 USDC and sends 24.00, the payment is not collected, it does not auto-settle at the lower figure, and the order does not ship. The receipts accumulate against the obligation, so the payer can complete it by sending the rest.

    The funds are not lost. If the payer never completes, Stableyard operations returns what arrived. You cannot initiate that return yourself. This is a deliberate guarantee, and the support cost it creates is real: plan it with Exceptions and interventions open.
  </Accordion>

  <Accordion title="What happens if a payer pays twice, or pays after the payment expired?">
    A duplicate is held and returned to the payer, and the winning receipt settles. The recipient is credited the full amount, once.

    Late funds are retained against that original payment for recovery and are never reassigned to somebody else's payment. The terminal outcome is preserved: an expired order stays expired. So you can treat every terminal outcome other than success as unpaid, and create a fresh payment for a retry, with no risk that a slow payer's money is credited to a stranger.

    Both are reported on the Payment in an incident-recovery summary kept deliberately separate from the refund summary, so returning a duplicate never makes a fulfilled order look refunded.
  </Accordion>

  <Accordion title="Can a retry charge my customer twice?">
    No. Every operation that moves money or creates recipient-bound instructions requires an idempotency key, and the requirement is enforced rather than advised. Reusing a key with an identical request returns the original result. Reusing it with changed input is refused as a conflict and the original operation is left untouched.

    A client-side timeout on a send is safe to retry, and is the correct thing to do, as long as you retry with the same key. Never create a replacement payment to work around a stuck one: that is how a customer gets paid twice. See [Errors and idempotency](/api-reference).
  </Accordion>

  <Accordion title="What happens when a payout fails or a bank returns a transfer?">
    A local currency payout that fails after the funds were collected is held by Stableyard, not left with your customer and not with the recipient, and operations reserve a recovery to the sending account's preferred crypto settlement destination. Keeping an active preferred destination on every paying account is therefore a partner obligation.

    A payout that fails before funding was confirmed is not a failed payout: nothing was collected, and you create a new payment with a fresh quote. A settled US bank transfer later returned by the receiving bank keeps its truthful status of succeeded and is marked as returned, with no automatic replacement and no automatic customer credit.

    When a provider's response is lost and the outcome is genuinely unknown, automatic retry is blocked on purpose, because a retry could pay the beneficiary twice. The payment waits for a person. Exceptions and interventions is the full inventory.
  </Accordion>

  <Accordion title="Is there a response time commitment for a payment held for review?">
    No, and this documentation will not invent one. Nothing in the platform commits to a response time, an escalation path, support hours or a resolution target. Those are commercial terms in your partner agreement. Ask for them in writing, per environment and per rail, before you launch a rail whose exceptions you cannot resolve yourself.

    What you can plan is the shape of the work: which exceptions each capability introduces is tabulated on Exceptions and interventions, so the queue can be sized before you commit rather than after.
  </Accordion>
</AccordionGroup>

## Compliance and identity

<AccordionGroup>
  <Accordion title="Do I have to run identity checks on my customers?">
    Only for the rails that cross into a bank. Creating an account, attaching a wallet, issuing a reusable deposit address, taking a crypto payment through hosted checkout, handing out a payment link and paying out to a wallet or another account all work with no identity verification anywhere in the flow.

    Linking a customer's bank account, paying a third party's bank and issuing a bank funding account each need an approved identity check plus a capability activation for that specific country, currency and rail. Paying a merchant QR needs no capability activation: it is enabled per app. So the question is not whether you need compliance, it is which of your capabilities cross into a bank. Identity, compliance and data has the table.
  </Accordion>

  <Accordion title="Does my company end up storing identity documents or bank account numbers?">
    No. Identity reads return a state, not a person: verification status, eligibility, validity, expiry and a next action, with no name, no date of birth, no documents and no provider decision payload. The account email is masked. Bank payout responses return a sanitized beneficiary snapshot with the final four characters only, and the full account number never appears in responses, metadata or events. Refund destinations are derived from verified payer evidence and are never disclosed.

    The customer fills the hosted compliance page directly, on a browser contract deliberately isolated from your systems. Security and data handling is written to be handed to whoever signs off your integration.
  </Accordion>
</AccordionGroup>

## Building it

<AccordionGroup>
  <Accordion title="What do I build, and what do I get for free?">
    Free, in the sense that Stableyard renders and maintains it: the hosted checkout page and its payer help sheet, the permanent payment link and its QR code, the embedded checkout and funding components, the hosted identity and compliance pages, the Partner Dashboard your operations team signs into, signed webhook delivery, and all of the chain monitoring, verification, escrow, routing and settlement behind them.

    Yours to build: the server call that creates each Payment, a webhook endpoint per environment that verifies signatures and is idempotent, a settlement destination picker for your customer, a handle picker that says the choice is permanent, fee and expiry disclosure in your own flow, a held state that is visibly different from failed, the identifiers you persist for every movement, and a queue with a named person for the exceptions. Choose a surface compares the five integration modes by how much of that you keep.
  </Accordion>

  <Accordion title="Do I need a frontend integration at all?">
    Not necessarily. Server-initiated payouts, internal transfers and local currency payouts have no payer-facing screen: your backend creates the Payment and your own product reports the result. At the other end, a payment link needs no integration at all, because a recipient account with a handle and an active settlement destination can be handed a permanent URL and a QR code from the Partner Dashboard.

    No credential that can move money for your app ever needs to exist in a browser. If an app secret reaches client code, that is a choice your integration made, not something the platform required.
  </Accordion>

  <Accordion title="How do I test?">
    Build against staging with staging credentials, and rehearse the ugly paths rather than the happy one: an underpayment, a duplicate, an expiry, a webhook replay, a retry with the same idempotency key.

    Know what staging cannot prove. Bank funding can only be exercised outside production, and its one verified chain and asset pair is a testnet pair. Vietnamese one-time bank transfers are production only and cannot be rehearsed at all. The extra staging collection chain supports connected wallets and does not support deposit addresses or settlement, so a rehearsal there proves neither. An identity check proves nothing in an environment where the identity provider is not configured, so ask which environments have one.

    [Test your integration](/environments) is the staging matrix, and [Go-live checklist](/environments) is the pre-flight in order.
  </Accordion>

  <Accordion title="Is a webhook enough to mark an order paid?">
    No. A webhook tells you something changed; the resource tells you what is true. Delivery is at least once, so a delivery can arrive twice, out of order, or after you already read the change, and your handler has to be idempotent.

    A funding provider reporting success is not collection either, and neither is the HTTP 200 on your own create call. Stableyard marks a payment collected only after independently confirming on-chain, in its own escrow, that at least the exact quoted destination amount arrived. [Reconciliation](/payments/reconciliation) is the single owner of that rule.
  </Accordion>

  <Accordion title="Can I use an AI coding assistant to build this?">
    Yes, and there is a machine-readable index of this documentation at [/llms.txt](https://docs.stableyard.fi/llms.txt) plus two OpenAPI specifications to hand it. Building with an AI assistant covers how to point one at them, and the five rules an assistant will get wrong if you do not tell it.
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="What's live, and how it gets switched on" icon="toggle-on" href="/supported-regions-and-currencies">
    The status word for every capability, and the four reasons one is off for you.
  </Card>

  <Card title="What launch requires of you" icon="rocket" href="/environments">
    Provisioning, environments, and the obligations you take on at go-live.
  </Card>

  <Card title="Understanding Universal Payment Accounts" icon="id-card" href="/universal-payment-account">
    The concept everything else needs, and the one call that makes a customer payable.
  </Card>

  <Card title="Quickstart" icon="code" href="/universal-payment-account">
    The Build-tab counterpart: discover configuration, create an account, move money once, reconcile it.
  </Card>
</CardGroup>


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