# OrsunPay

> Guides, API contracts and workspace walkthroughs for merchants integrating OrsunPay.

- [OrsunPay documentation](https://docs.orsunpay.com/index.md): Choose a checkout, integrate the merchant API, and follow a payment from your buyer’s browser to your order ledger.
- [Quickstart: your first payment](https://docs.orsunpay.com/quickstart.md): Use a test API key to create a sale, send the buyer to the payment page and confirm the result with a signed webhook.
- [Go live](https://docs.orsunpay.com/go-live.md): Verify your checkout, credentials and order handling before accepting the first live payment.
- [Create a sale](https://docs.orsunpay.com/create-sale.md): Start a buyer payment with decimal-string money and a stable idempotency key.
- [Hosted payment page](https://docs.orsunpay.com/hosted-payment-page.md): Redirect the buyer while keeping payment confirmation on your backend.
- [Payment links](https://docs.orsunpay.com/payment-links.md): Create and manage links scoped to your merchant API key.
- [Public store page](https://docs.orsunpay.com/public-store-page.md): Share a small store page with selected reusable payment links.
- [JavaScript widget and card fields](https://docs.orsunpay.com/js-widget.md): Open an OrsunPay payment link or hosted payment page from your own site without handling card data.
- [Embed the cashier](https://docs.orsunpay.com/cashier.md): Open a cashier for an authenticated player and keep merchant credentials on your server.
- [Payments, transactions and statuses](https://docs.orsunpay.com/payments.md): The objects the merchant API creates and the states a payment moves through.
- [Transaction status](https://docs.orsunpay.com/transaction-status.md): Poll an existing payment without sending another PSP request.
- [Payouts](https://docs.orsunpay.com/payouts.md): Send money to a buyer through a payout-capable provider connection with createPayout.
- [Refunds](https://docs.orsunpay.com/refunds.md): Create an idempotent full or partial refund and follow its stored status.
- [Reconcile an order](https://docs.orsunpay.com/reconciliation.md): Trace a missing or delayed payment using the merchant order ID, OrsunPay transaction and provider record.
- [Usage billing](https://docs.orsunpay.com/usage-billing.md): Sell subscriptions with included credits and metered overage to your customers.
- [Environments and base URL](https://docs.orsunpay.com/environments.md): Test and live modes share one API; your API key selects the mode and your account determines the base URL.
- [Authentication and API keys](https://docs.orsunpay.com/authentication.md): Authenticate server-to-server requests with your merchant API key in the x-api-key header.
- [Idempotency, money and versioning](https://docs.orsunpay.com/idempotency.md): Contract rules that apply to every merchant API call.
- [Testing in sandbox](https://docs.orsunpay.com/testing.md): Exercise your integration with a test key, sandbox provider connections and your providers' published test data.
- [Errors and retries](https://docs.orsunpay.com/errors.md): Distinguish validation, business rejection and uncertain outcomes, and retry safely.
- [Security and card data](https://docs.orsunpay.com/security.md): How card data stays out of your systems and OrsunPay's API, and how to protect your credentials.
- [Webhooks](https://docs.orsunpay.com/webhooks.md): Verify each delivery with your merchant-specific signing secret before processing it.
- [Webhook events](https://docs.orsunpay.com/webhook-events.md): Reference for the webhook event types and envelope OrsunPay sends today.
- [Server SDKs](https://docs.orsunpay.com/sdks/overview.md): Integrate merchant payments, payouts, refunds, payment links and signed webhooks in your backend language.
- [Node SDK](https://docs.orsunpay.com/sdks/node.md): Server-side TypeScript client for payments, payouts, payment links and webhook verification.
- [Go SDK](https://docs.orsunpay.com/sdks/go.md): Look up merchant orders, create payments and verify signed webhooks in a Go service.
- [PHP](https://docs.orsunpay.com/sdks/php.md): Configure the PHP HTTP client, look up an order and verify incoming webhooks.
- [Java SDK](https://docs.orsunpay.com/sdks/java.md): Connect a Java or Kotlin server to the merchant API using the JVM client.
- [.NET SDK](https://docs.orsunpay.com/sdks/dotnet.md): Use the C# client to look up payments, request refunds and verify signed webhooks in .NET 8 or later.
- [Python SDK](https://docs.orsunpay.com/sdks/python.md): Read a payment with the synchronous or asynchronous Python client and verify webhook signatures.
- [Ruby and Rails SDK](https://docs.orsunpay.com/sdks/ruby.md): Look up a merchant order from Rails and verify webhook requests before acting on them.
- [Rust SDK](https://docs.orsunpay.com/sdks/rust.md): Look up payments, request refunds and verify signed webhooks from an async Rust service.
- [Changelog](https://docs.orsunpay.com/changelog.md): Merchant-visible changes to the OrsunPay API contract and SDKs.
- [Merchant API reference](https://docs.orsunpay.com/api-overview.md): Find an operation by task, choose the correct credentials and read the versioned request and response schemas.
- [Create a crypto invoice](https://docs.orsunpay.com/api-reference/cashier-player/create-a-crypto-invoice.md)
- [Retrieve a crypto invoice](https://docs.orsunpay.com/api-reference/cashier-player/retrieve-a-crypto-invoice.md)
- [Quote a crypto deposit](https://docs.orsunpay.com/api-reference/cashier-player/quote-a-crypto-deposit.md)
- [List eligible deposit methods](https://docs.orsunpay.com/api-reference/cashier-player/list-eligible-deposit-methods.md)
- [List cashier operations](https://docs.orsunpay.com/api-reference/cashier-player/list-cashier-operations.md)
- [Submit a deposit](https://docs.orsunpay.com/api-reference/cashier-player/submit-a-deposit.md)
- [Retrieve a cashier operation](https://docs.orsunpay.com/api-reference/cashier-player/retrieve-a-cashier-operation.md)
- [Quote a deposit](https://docs.orsunpay.com/api-reference/cashier-player/quote-a-deposit.md)
- [Refresh cashier authorization](https://docs.orsunpay.com/api-reference/cashier-player/refresh-cashier-authorization.md)
- [Read the authenticated player cashier and its currency](https://docs.orsunpay.com/api-reference/cashier-player/read-the-authenticated-player-cashier-and-its-currency.md)
- [Read the immutable presentation pinned when the player session was created](https://docs.orsunpay.com/api-reference/cashier-player/read-the-immutable-presentation-pinned-when-the-player-session-was-created.md)
- [List withdrawals](https://docs.orsunpay.com/api-reference/cashier-player/list-withdrawals.md)
- [Request a withdrawal](https://docs.orsunpay.com/api-reference/cashier-player/request-a-withdrawal.md)
- [List eligible withdrawal methods](https://docs.orsunpay.com/api-reference/cashier-player/list-eligible-withdrawal-methods.md)
- [Quote a withdrawal](https://docs.orsunpay.com/api-reference/cashier-player/quote-a-withdrawal.md)
- [Retrieve a withdrawal](https://docs.orsunpay.com/api-reference/cashier-player/retrieve-a-withdrawal.md)
- [Cancel a withdrawal](https://docs.orsunpay.com/api-reference/cashier-player/cancel-a-withdrawal.md)
- [Reconcile a withdrawal reservation](https://docs.orsunpay.com/api-reference/cashier-player/reconcile-a-withdrawal-reservation.md)
- [Read the stored merchant frame origin; does not authorize a session](https://docs.orsunpay.com/api-reference/cashier-embedding-policy/read-the-stored-merchant-frame-origin;-does-not-authorize-a-session.md)
- [Authorize a player cashier from the merchant backend](https://docs.orsunpay.com/api-reference/cashier-sessions-merchant-s2s/authorize-a-player-cashier-from-the-merchant-backend.md)
- [Renew player access for the same bound instance](https://docs.orsunpay.com/api-reference/cashier-sessions-merchant-s2s/renew-player-access-for-the-same-bound-instance.md)
- [Revoke this player cashier immediately](https://docs.orsunpay.com/api-reference/cashier-sessions-merchant-s2s/revoke-this-player-cashier-immediately.md)
- [Acknowledge a wallet effect](https://docs.orsunpay.com/api-reference/cashier-sessions-merchant-s2s/acknowledge-a-wallet-effect.md)
- [List payments or find by order ID](https://docs.orsunpay.com/api-reference/payments/list-payments-or-find-by-order-id.md): With orderId returns one transaction or 404. Otherwise returns newest first by created_at and ID; use next_cursor as starting_after. Merchant and live/test mode come only from the API key. All money is decimal-string major units.
- [Create withdrawal transaction (Payout)](https://docs.orsunpay.com/api-reference/payments/create-withdrawal-transaction-payout.md): Creates a payout through an eligible provider connection. Use the payment method configured for the merchant, mode, currency and payout rail. Colibrix card payouts require sourceTransactionId from an eligible earlier sale. Bank payouts require a supported connection and its beneficiary fields. Money…
- [Create deposit transaction (Sale)](https://docs.orsunpay.com/api-reference/payments/create-deposit-transaction-sale.md): Creates a new deposit transaction for customer account funding. Supports various payment methods including cryptocurrencies, e-wallets, and BNPL services. Money is a decimal string in major units (`"amount": "10.00"`), in the request and in the response. Without `paymentMethod`, or with incomplete `…
- [Get a payment by ID](https://docs.orsunpay.com/api-reference/payments/get-a-payment-by-id.md): Stored status only; never creates or retries a PSP operation. Same response as GET /v1/transactions/:id.
- [List the authenticated merchant’s links, newest first](https://docs.orsunpay.com/api-reference/payment-links/list-the-authenticated-merchant’s-links-newest-first.md): Scoped to the authenticated API key’s live/test mode. Keyset pagination: pass nextCursor from the previous page as cursor; null means the last page.
- [Create a merchant-scoped payment link](https://docs.orsunpay.com/api-reference/payment-links/create-a-merchant-scoped-payment-link.md): Creates a link in the authenticated API key’s live/test mode that the merchant can share with a buyer. Money is a decimal string in major units within the currency exponent. Idempotency-Key is required: a retry with the same key and body returns the stored answer with Idempotency-Replayed: true.
- [Get a link owned by the authenticated merchant](https://docs.orsunpay.com/api-reference/payment-links/get-a-link-owned-by-the-authenticated-merchant.md): Links of other merchants or API-key modes answer 404 PAYMENT_LINK_NOT_FOUND, like unknown ids.
- [Permanently deactivate a link; repeated requests are safe](https://docs.orsunpay.com/api-reference/payment-links/permanently-deactivate-a-link;-repeated-requests-are-safe.md): Only links in the authenticated API key’s live/test mode are accessible. A deactivated link cannot be reopened. Deactivating an inactive link returns it unchanged.
- [List refunds for a payment](https://docs.orsunpay.com/api-reference/refunds/list-refunds-for-a-payment.md): Read stored refunds for the authenticated merchant and API-key mode. Ordered by refund ID ascending, with at most 100 records per page. Pass nextCursor to continue; null means the final page.
- [Request a full or partial refund](https://docs.orsunpay.com/api-reference/refunds/request-a-full-or-partial-refund.md): Accepts an asynchronous refund in the authenticated merchant and API-key mode. Omit amount to refund the remaining refundable amount. PENDING/PROCESSING are not completion. The original connection must support refunds and payment and processing currencies must match. Idempotency-Key is mandatory.
- [Get a refund](https://docs.orsunpay.com/api-reference/refunds/get-a-refund.md): Read the stored refund status in the authenticated merchant and API-key mode. Unknown and foreign refund IDs return the same 404.
- [Poll a merchant transaction](https://docs.orsunpay.com/api-reference/transactions/poll-a-merchant-transaction.md): Read the current stored status. Scoped to the merchant and live/test mode of the authenticated API key. IDs longer than 32 characters return 404 without a transaction lookup. No PSP sale is sent. Amounts are decimal strings. Poll after PSP_OUTCOME_UNKNOWN; do not create a second order.
- [Record a usage event](https://docs.orsunpay.com/api-reference/usage-billing/record-a-usage-event.md): Record positive credits with at most six fractional digits at server receipt time. Included credits are consumed first, then overage; exceeding the overage cap rejects the whole event. An identical eventId replay returns the original event, even after the period closes; a changed payload conflicts.…
- [List usage invoices](https://docs.orsunpay.com/api-reference/usage-billing/list-usage-invoices.md): List the latest 100 usage statements in the authenticated merchant and API-key mode, optionally filtered by subscriptionId. Amounts are exact decimal strings. These statements are separate from platform billing and tax invoices.
- [List usage plans](https://docs.orsunpay.com/api-reference/usage-billing/list-usage-plans.md): List the latest 100 pricing plans in the authenticated merchant and API-key mode. Decimal values are strings.
- [Create a usage plan](https://docs.orsunpay.com/api-reference/usage-billing/create-a-usage-plan.md): Create immutable pricing terms for customer usage, scoped to the authenticated merchant API key and its live/test mode. Monthly price uses currency precision; credits and overage rate allow six fractional digits. Reusing a code with identical terms returns the plan; changed terms conflict.
- [List usage subscriptions](https://docs.orsunpay.com/api-reference/usage-billing/list-usage-subscriptions.md): List the latest 100 subscriptions in the authenticated merchant and API-key mode. Decimal values are strings.
- [Create a usage subscription](https://docs.orsunpay.com/api-reference/usage-billing/create-a-usage-subscription.md): Create one noncancelled subscription per opaque customer reference in the authenticated merchant and API-key mode. Idempotency-Key is required. Overage limit is a money string; zero disables overage. Paid plans initially await confirmed payment.
- [Get a usage subscription](https://docs.orsunpay.com/api-reference/usage-billing/get-a-usage-subscription.md): Get one subscription in the authenticated merchant and API-key mode, with its latest 100 events and invoices. Resources in another merchant or mode return the same not-found response as an unknown id.
- [confirmAutoRenew for a usage subscription](https://docs.orsunpay.com/api-reference/usage-billing/confirmautorenew-for-a-usage-subscription.md): Scoped to the merchant API key and test/live mode. Setup creates a hosted Stripe consent link; it does not authorize a charge. Unknown payment outcomes must be reconciled before recovery.
- [disableAutoRenew for a usage subscription](https://docs.orsunpay.com/api-reference/usage-billing/disableautorenew-for-a-usage-subscription.md): Scoped to the merchant API key and test/live mode. Setup creates a hosted Stripe consent link; it does not authorize a charge. Unknown payment outcomes must be reconciled before recovery.
- [setupAutoRenew for a usage subscription](https://docs.orsunpay.com/api-reference/usage-billing/setupautorenew-for-a-usage-subscription.md): Scoped to the merchant API key and test/live mode. Setup creates a hosted Stripe consent link; it does not authorize a charge. Unknown payment outcomes must be reconciled before recovery.
- [Cancel a usage subscription](https://docs.orsunpay.com/api-reference/usage-billing/cancel-a-usage-subscription.md): Cancel at the paid period end, preserving final accrued overage. An unpaid initial subscription cancels immediately. Repeating this request is safe. Scope comes from the authenticated API key.
- [notifications for a usage subscription](https://docs.orsunpay.com/api-reference/usage-billing/notifications-for-a-usage-subscription.md): Scoped to the merchant API key and test/live mode. Setup creates a hosted Stripe consent link; it does not authorize a charge. Unknown payment outcomes must be reconciled before recovery.
- [paymentHistory for a usage subscription](https://docs.orsunpay.com/api-reference/usage-billing/paymenthistory-for-a-usage-subscription.md): Scoped to the merchant API key and test/live mode. Setup creates a hosted Stripe consent link; it does not authorize a charge. Unknown payment outcomes must be reconciled before recovery.
- [recoverPayment for a usage subscription](https://docs.orsunpay.com/api-reference/usage-billing/recoverpayment-for-a-usage-subscription.md): Scoped to the merchant API key and test/live mode. Setup creates a hosted Stripe consent link; it does not authorize a charge. Unknown payment outcomes must be reconciled before recovery.
- [Reconcile a usage subscription](https://docs.orsunpay.com/api-reference/usage-billing/reconcile-a-usage-subscription.md): Reconcile confirmed invoice payments and period boundaries for this subscription. Repeating this request is safe. When automatic renewal is enabled, this operation can advance the persisted Stripe payment attempt; otherwise it reconciles payment links. Scope comes from the authenticated API key.
- [Refund failed event](https://docs.orsunpay.com/api-reference/webhooks/refund-failed-event.md): Terminal refund event sent to the original sale callbackUrl, falling back to the merchant default webhook URL. Verify HMAC-SHA256 over the exact raw body before parsing, using the merchant webhook secret (ADR-010). Reject signature timestamps beyond 300 seconds; compare in constant time. Deliveries…
- [Refund succeeded event](https://docs.orsunpay.com/api-reference/webhooks/refund-succeeded-event.md): Terminal refund event sent to the original sale callbackUrl, falling back to the merchant default webhook URL. Verify HMAC-SHA256 over the exact raw body before parsing, using the merchant webhook secret (ADR-010). Reject signature timestamps beyond 300 seconds; compare in constant time. Deliveries…
- [Transaction status event](https://docs.orsunpay.com/api-reference/webhooks/transaction-status-event.md): OrsunPay sends this POST to the transaction callbackUrl after a status update. Verify HMAC-SHA256 over the exact raw body before parsing, using the merchant webhook secret (ADR-010). Reject signature timestamps beyond 300 seconds; compare in constant time. Deliveries are at least once and can arrive…
- [Payment methods](https://docs.orsunpay.com/payment-methods.md): Find a method for a sale, identify its provider connection and check which options your buyers can use.
- [Choose a payment method](https://docs.orsunpay.com/methods/choose-a-method.md): Let buyers pick an eligible method or send a connection ID when your backend has already made the choice.
- [Routing and connection selection](https://docs.orsunpay.com/routing.md): How OrsunPay chooses a provider connection for a sale or payout, and what happens when a provider declines.
- [Cards and hosted checkout](https://docs.orsunpay.com/methods/cards.md): Accept cards through a hosted provider page and handle Adyen and Revolut payment outcomes.
- [Wallets](https://docs.orsunpay.com/methods/wallets.md): Offer Apple Pay or Google Pay on checkout, and identify the providers that host other wallet flows.
- [Pay by bank and bank transfers](https://docs.orsunpay.com/methods/bank-payments.md): Start a bank-funded sale, supply country and currency where required, and reconcile bank payment initiation.
- [Local payment methods](https://docs.orsunpay.com/methods/local-payments.md): Match local bank, app, voucher and pay-later options to the connection and buyer inputs they require.
- [Crypto invoices](https://docs.orsunpay.com/methods/crypto.md): Create a BitPay hosted invoice for an order and distinguish invoice creation from a confirmed crypto payment.
- [Merchant cabinet](https://docs.orsunpay.com/merchant-cabinet.md): Find a payment, check a webhook delivery and manage the credentials for your shop.
- [Operator backoffice](https://docs.orsunpay.com/offices/operator-backoffice.md): Investigate a transaction, review a held payout and trace an operator decision in OrsunPay Ops.

## OpenAPI Specs

- [openapi](/openapi.json)


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