Help center

Help, in plain words.

Short answers for the things people get stuck on. If yours is not here, contact support and quote the request id from any error.

Get started.

A summary of docs/developers/quickstart.md. The repository file is the source; the code samples with full detail are on the developers page.

  1. Create an account. Sign up in the app. You start on the free Developer plan with a workspace of your own.
  2. Connect a wallet. Use the practice wallet (a labelled simulator) or an LND node on regtest. Give Orynt a credential that can only pay invoices and look them up.
  3. Create your approval key. Approvers sign each payout with a key held in their browser. Set it up in Settings.
  4. Make a payout. Paste an invoice, submit it, have someone else approve it, send it once, then download the receipt.
  5. Automate if you want to. Create an API key in the app's Developers page (it can create, submit, execute and read, never approve).
local run
# Run the whole thing yourself, locally (development mode, simulator wallet)
pnpm install && pnpm db:start
pnpm build:all
ORYNT_ENV=development ORYNT_SEED_DEMO=1 pnpm start
# app at /app, API at /v1 on the same port

No public instance is deployed yet, so today the app runs where you run it. See status.

Account and sign-in.

What you can do

  • Verify your email with a single-use link, and request a new one in Settings.
  • Reset a forgotten password by email; resetting signs out every session.
  • Turn on two-factor protection with an authenticator app (TOTP); it is asked for at sign-in and again when approving or executing.
  • Invite teammates by email; an invitation expires after 7 days.
  • Export your organisation's data (no secrets), or close your own account.

Good to know

  • Email delivery is not commissioned. Unless a mail provider is configured, messages are queued in an outbox and marked sent without being delivered, so on a local setup you will not receive them.
  • A wrong or missing authenticator code is reported as approval_invalid with mfa_required: true.
  • Sign-in and registration are rate-limited (15 a minute per address).
  • Approval keys live in the browser. Clearing site data removes the key; register a new one.

When a payment is “checking”.

In the app it reads “Checking wallet record”. The states behind it are UNKNOWN and RECONCILING. It means the wallet's answer was lost and nobody can yet say whether the money moved.

  1. Do not pay again. Do not create a second payout for the same person, and do not pay from your wallet by hand. The first attempt may still have gone through. Orynt refuses a second send for this reason (send_blocked_unresolved).
  2. Ask the wallet. On the payout page choose “Check the wallet's record now”. Orynt looks the payment up by its payment hash. Only the wallet's own record moves the payout to SETTLED or DEFINITIVELY_FAILED.
  3. Check the connection. If the wallet is unreachable, fix that first (Wallets, then re-check the connection) and ask again.
  4. Still unclear? An incident is opened. Add notes and assign someone. The payment hash is on the payout; you can look for it in your own node.
  5. Only if you can show nothing was sent, use “Confirm it was never sent” with a written reason (at least 10 characters) and fresh evidence. This needs the incident-resolver permission. A new attempt can start only after a failure is proven or attested.

Why not “failed”?

A lost reply is not proof of failure, and an expired invoice is not either. Showing “failed” would invite a second payment. Indigo means not yet proven either way.

Over the API

An execute that returns HTTP 202 is this same situation. Call POST /v1/payments/:id/reconcile or wait; do not call execute again.

How to read a receipt.

A receipt is a JSON file. You do not have to trust it or us: a separate verifier checks it offline, and tells you what it cannot prove.

What is inside

Receipt fields and what they tell you
FieldWhat it tells you
schemaorynt.receipt/1. The format version the verifier checks against.
receipt_id, issued_atA unique id and the time the issuer signed it. A replay ledger can reject a receipt id seen before.
issuerThe key id and public key that signed the receipt. Trust in it is your decision: get the key out-of-band.
network, environmentregtest, mainnet and so on, and whether the payment was REAL_PROVIDER or SIMULATOR. Simulator receipts are never a real payment.
providerThe wallet kind and its node public key.
workspaceThe workspace that issued the receipt (id and name).
agreementWhat was agreed: payee, amount in millisatoshis, memo, your reference, the invoice and its payment hash.
policy, intentThe approval rules in force, and the fingerprint (digest) of the exact payout that approvers signed.
approvalsEach approver, their public key and their signature over the intent digest.
attemptsEvery send attempt and its outcome, so a retry after proven failure is visible.
settlementThe preimage (hashing it gives the payment hash), amount, fee, settled time, whether the result came from the wallet's response or a later lookup, and reconciled_after_uncertainty.
auditA short segment of the hash-chained audit log, with a signed checkpoint.
limitationsWhat the receipt cannot prove. It travels with the receipt.
attestationThe issuer's Ed25519 signature over everything above.

What the verifier says

Verifier verdicts and exit codes
VerdictExit codeMeaning
VERIFIED0All checks passed, the issuer is a key you trust, and the payment was real.
REJECTED1A check failed: tampered, forged, replayed, stale or for the wrong payment.
INTEGRITY_ONLY3The receipt is internally consistent and the payment proof is valid, but the issuer key is not one you supplied.
VERIFIED_SIMULATED4Everything checks out, but the payment came from the labelled simulator. Not a real payment.

Exit code 2 means a usage or file error. The command and its options are on the developers page. You can also paste a receipt into the in-app verifier.

What a receipt cannot prove.

  • That the work, goods or services were delivered or any good.
  • That the payee is the person or organisation named: that binding is a claim by the issuing workspace.
  • That no other payments exist for the same obligation outside Orynt.
  • That a contract is enforceable, or that funds were held in escrow.
  • Who was really paid, if the payer also controls the receiving node.

Error codes.

Every API error is application/problem+json with a stable code to switch on, a human detail and a request_id (also the x-request-id header). Switch on code, not on the message.

API error codes, HTTP status, meaning and what to do
CodeHTTPMeaningWhat to do
validation_failed400, 422The request is malformed or a field is invalid. errors[] lists the paths. A missing or badly sized Idempotency-Key is a 400.Fix the request.
unauthenticated401No valid credentials, a stale webhook timestamp, or an unconfigured webhook secret.Sign in again or check the API key.
forbidden403Your role lacks the permission. Roles are checked fail-closed. API keys can never approve.Ask a workspace admin for the right role.
not_found404No such resource, or it belongs to another workspace (the two look the same on purpose).Check the id and the workspace.
conflict409The change collides with existing data or another request.Reload and retry if still valid.
idempotency_conflict422That Idempotency-Key was already used with a different request.Use a new key for a new request; reuse the key only to retry the same one.
rate_limited429Too many requests from your address.Wait and retry.
invalid_state409The action is not possible in the payout's current state; the message says why.Read the state; do the allowed next action.
policy_violation403, 409, 422The payout breaks the active policy (for example a limit or maker-checker rule).Change the payout or ask for a policy change.
invoice_invalid422The invoice cannot be decoded or its signature fails.Ask the payee for a new invoice.
invoice_expired409, 422The invoice has expired.Ask for a fresh invoice. Expiry alone never proves a payment failed.
network_mismatch409, 422The invoice is for a different network than the wallet or workspace.Use an invoice from the right network.
amount_mismatch422The amount differs from the invoice amount.Correct the amount.
destination_mismatch409, 422The invoice's node is not the payee's bound node key.Verify the payee, then ask for a new invoice.
approval_invalid401, 409, 422A signature or approval cannot be accepted. It is also how a missing or wrong authenticator code is reported, with mfa_required: true in the body.Re-sign the exact payout, or enter a current authenticator code.
approval_stale409The policy changed after approval.Submit the payout again.
approval_insufficient409Not enough valid approvals yet.Wait for the remaining approvers.
wallet_unavailable409, 422, 503The wallet cannot be reached or is not connected.Check the wallet connection. If a send was in progress, the payout will say checking, not failed.
wallet_insufficient_permissions409The wallet credential cannot do what is needed (for example it is read-only).Connect a credential that can pay invoices and look up payments.
mainnet_disabled409, 422Mainnet execution is switched off.Use regtest. Mainnet is not available.
entitlement_exceeded402Your plan's limit is reached or the feature is not in your plan. The body names entitlement, plan, limit and used.Free up a resource or change plan in billing.
mfa_required—Reserved in the contract. Today a missing authenticator code is reported as approval_invalid with mfa_required: true.See approval_invalid.
send_blocked_unresolved409A payment for this payout already exists or is unresolved. Sending again is refused.Reconcile or wait. Never retry.
internal500, 502Something went wrong on our side, or a billing provider call failed. Nothing changed unless the response says so.Quote the request_id to support.

Common questions.

Why is the Send button disabled?

The page says why next to the button: usually the payout is not yet approved, a payment is already unresolved, or your role cannot send. Disabled actions always carry a reason.

Why did some rows of my batch fail?

Rows are checked one by one and a bad row never stops the others. The preview lists each problem: a missing recipient, an amount that is not a number of sats, an amount that differs from the invoice, an invalid invoice, or the same invoice twice. A batch is limited to 200 rows and needs a plan that includes batches.

I got a 402. What now?

That is entitlement_exceeded: your plan's limit is reached or the feature is not in it. The response names which limit. See the plan limits and your usage.

Why did my recurring schedule not pay?

It is not supposed to. A schedule opens an “invoice needed” task each cycle, because a Lightning invoice is single-use. Supply the invoice and the payout goes through approval like any other.

Can I get money back after a payment?

Lightning payments are final and Orynt cannot reverse them. A refund is a new payment that you create, approve and send.

Contact support.

Open a support request in the app, signed in or not. Signed in, safe diagnostics are attached automatically: ids, your plan, your role and the kinds of wallets you have connected. You get a reference number to quote. Categories: payment, wallet, billing, account, security, other (without an account: account, billing, security, other).

This is a one-person project, so replies can take days. There is no support SLA.

Never send wallet credentials, macaroons, seed phrases, private keys or full invoices to support, here or anywhere else. We will not ask for them.

Still stuck?

Contact support with the request id from the error. If you have not tried Orynt yet, a free account is the quickest way to see how it behaves.