Sandbox testing

The Orki sandbox is a self-contained environment for integration testing. Its accounts, API keys, transactions, webhook configuration, and logs are separate from production.

Surface	Sandbox URL
Terminal	https://demo.money.orki.io
Partner API	`https://sandbox.money.orki.io`

Never send a sandbox-created API key to api.money.orki.io, and never send a production-created API key to sandbox.money.orki.io. A key is valid only in the environment where it was created.

Set up a sandbox account

Create a separate sandbox account

Open demo.money.orki.io and register. Production accounts are not copied into the sandbox, so create an account there even if you already use the production Terminal.

Optionally test sandbox KYB

The Sumsub sandbox KYB flow is available for testing onboarding, but completing it is not required to request quotes, create Partner API transactions, receive provider completion callbacks, or receive outgoing partner webhooks. Sandbox KYB approval does not approve the corresponding production account.

Start a plan or free trial

Start a subscription or trial from the sandbox Terminal. All subscribed sandbox plans can use the Partner API and access the configured sandbox providers.

Create the sandbox API key

Open API Management, create an API key, and copy its plaintext value when it is displayed. The plaintext key cannot be recovered later; revoke it and create another key if it is lost.

Confirm the API key

Use the key with the sandbox base URL and the X-ORKI-API-KEY header:

curl --get "https://sandbox.money.orki.io/api/v1/partner/fiat-currencies" \
  --header "X-ORKI-API-KEY: YOUR_SANDBOX_API_KEY" \
  --data-urlencode "type=BUY"

A 200 response confirms that the key is recognized. A 401 response usually means the key is missing, revoked, or was created in the other environment. A 402 response means the account does not have an active subscription or trial. Sandbox Partner API access is not gated by plan tier or Sumsub KYB; a 403 can indicate an account-level restriction such as suspension.

Test a complete transaction lifecycle

Sandbox capability varies by provider. Some providers support only discovery or checkout creation in their test environment. Stripe currently supports the complete Orki sandbox path: quote, checkout, provider callback, transaction update, and outgoing partner webhook. Before completing checkout, configure an outgoing webhook as described below. Webhooks are the normal asynchronous completion signal in sandbox, just as they are in production. The transaction retrieval endpoint is available for reconciliation and recovery if a delivery is delayed or missed. Use this route for a complete BUY test:

Field	Value
Provider	`stripe`
Fiat currency	`EUR`
Cryptocurrency	`USDC`
Network	`ethereum`
Payment method	`credit_debit_card`
Transaction type	`BUY`

Explicitly select stripe when creating the sandbox transaction, even if Coinify, MoonPay, or another quote is marked is_best. The is_best flag reflects quote pricing only; it does not describe the provider’s sandbox lifecycle coverage.

Use a correctly formatted Ethereum address dedicated to testing so you can also verify recipient_address throughout your integration.

1. Request quotes

curl --get "https://sandbox.money.orki.io/api/v1/partner/quotes" \
  --header "X-ORKI-API-KEY: YOUR_SANDBOX_API_KEY" \
  --data-urlencode "fiat_currency=EUR" \
  --data-urlencode "crypto_currency=USDC" \
  --data-urlencode "network=ethereum" \
  --data-urlencode "payment_method=credit_debit_card" \
  --data-urlencode "amount=25" \
  --data-urlencode "type=BUY" \
  --data-urlencode "wallet_address=YOUR_VALID_ETHEREUM_ADDRESS"

Find the quote whose provider.identifier is stripe. Provider availability is evaluated at request time, so a route that is normally supported can still be temporarily unavailable.

2. Create the transaction

curl --request POST "https://sandbox.money.orki.io/api/v1/partner/transactions" \
  --header "X-ORKI-API-KEY: YOUR_SANDBOX_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "fiat_currency": "EUR",
    "crypto_currency": "USDC",
    "network": "ethereum",
    "payment_method": "credit_debit_card",
    "amount": 25,
    "type": "BUY",
    "provider": "stripe",
    "wallet_address": "YOUR_VALID_ETHEREUM_ADDRESS",
    "partner_context": "sandbox-order-1001",
    "redirect_url": "https://your-app.example/ramp/return"
  }'

Store data.transaction_id, then open data.link in a browser to continue through the provider checkout. Creating the Orki transaction only creates the tracking record and checkout link; it does not complete the purchase.

3. Complete the Stripe sandbox checkout

Stripe documents these values for completing its sandbox onramp:

Checkout field	Sandbox value
OTP	`000000`
SSN	`000000000`
Address line 1	`address_full_match`
Card number	`4242424242424242`

Stripe can override the requested amount with its sandbox limits. See Stripe’s sandbox onramp instructions for the provider’s current requirements.

4. Receive the outgoing webhook

The transaction is initially pending. After Orki receives and verifies a terminal provider callback, it updates the transaction and delivers the corresponding event to your configured sandbox webhook endpoint.

Provider outcome	Orki status	Outgoing event
Stripe reaches `fulfillment_complete`	`success`	`transaction.success`
Stripe reaches `rejected`	`failed`	`transaction.failed`
Checkout is incomplete, abandoned, or remains at `requires_payment`	`pending`	None

A declined Stripe sandbox payment can remain at requires_payment; it does not necessarily produce a terminal failure callback. A deterministic success path is available with Stripe’s documented sandbox values, while a final failure event is emitted only when the provider reports a terminal rejected state.

5. Reconcile through the transaction API

Use the transaction endpoint to confirm the stored state, recover after a missed webhook, or reconcile periodically:

curl --get "https://sandbox.money.orki.io/api/v1/partner/transactions/ORKI_TRANSACTION_ID" \
  --header "X-ORKI-API-KEY: YOUR_SANDBOX_API_KEY"

Polling is a fallback and reconciliation mechanism. It does not replace webhook handling for normal transaction updates.

Test outgoing webhooks

Configure webhooks before completing the provider checkout:

Create a public HTTPS endpoint that accepts POST requests.
In the sandbox Terminal, open API Management → Webhooks.
Register the endpoint and select success, failure, or both.
Save the webhook signing secret securely.
Complete the Stripe sandbox checkout and return 2xx promptly when the event arrives.

Sandbox delivers the same public event names and payload structure as production:

transaction.success
transaction.failed

The value supplied as partner_context during transaction creation is returned as data.partner_context. Use it to reconcile the webhook with your own order. Partner webhooks are sent for API transactions and client-owned widget transactions. Transactions created through the public, non-client-owned widget do not generate partner webhooks.

Verify the signature

Every delivery includes:

X-Timestamp: Unix timestamp used when signing the request.
X-Signature: lowercase hexadecimal HMAC-SHA256 signature.

Read the request body exactly as received and calculate:

HMAC-SHA256(webhook_secret, X-Timestamp + "." + raw_request_body)

Compare the result with X-Signature using a timing-safe comparison. Reject an invalid signature and reject timestamps outside your accepted replay window. See Webhooks for implementation examples and retry behavior. Each sandbox account has one active webhook destination and signing secret. Saving a webhook subscription rotates its signing secret, so update your receiver whenever you change and save the subscription. Production webhook configuration is separate because production uses a separate account and environment.

What sandbox proves

Sandbox can validate:

API-key authentication and environment isolation.
Asset, payment-method, and quote discovery.
Transaction creation and checkout redirects.
Provider callbacks and final Orki status when the selected provider supports them.
Outgoing webhook delivery, with transaction retrieval available for fallback reconciliation.
Webhook payload reconciliation and signature verification.

Sandbox does not prove real fiat settlement, real blockchain delivery, or production KYB approval. Repeat a small controlled transaction in production before enabling wider access.

Troubleshooting

Symptom	Check
`401 Invalid or revoked API key`	Confirm the key was created at `demo.money.orki.io` and is being sent to `sandbox.money.orki.io`.
No Stripe quote	Confirm the complete EUR/USDC/Ethereum/card combination and use a supported amount and location.
Transaction remains `pending`	Confirm checkout reached a terminal provider state. Abandoned or declined payment attempts can remain non-terminal.
No partner webhook	Confirm the transaction belongs to the sandbox account, the event is selected, the endpoint is public HTTPS, and the provider issued a terminal callback.
Signature mismatch	Use `X-Timestamp + "." + raw body`; do not parse and re-serialize the JSON before calculating the HMAC.
Webhook returned non-2xx	Review API Management → Webhooks logs. Orki retries automatic deliveries twice with backoff, and the Terminal also supports a manual retry.

Continue with API Integration for every request and response field, Events for the payload schema, and Errors for API error handling.

Getting started

Authentication

Integration Guide

Widget Integration

API Integration

Ramp Providers

Supported Assets

Webhooks

Set up a sandbox account

Confirm the API key

Test a complete transaction lifecycle

1. Request quotes

2. Create the transaction

3. Complete the Stripe sandbox checkout

4. Receive the outgoing webhook

5. Reconcile through the transaction API

Test outgoing webhooks

Verify the signature

What sandbox proves

Troubleshooting

​Set up a sandbox account

​Confirm the API key

​Test a complete transaction lifecycle

​1. Request quotes

​2. Create the transaction

​3. Complete the Stripe sandbox checkout

​4. Receive the outgoing webhook

​5. Reconcile through the transaction API

​Test outgoing webhooks

​Verify the signature

​What sandbox proves

​Troubleshooting

Set up a sandbox account

Confirm the API key

Test a complete transaction lifecycle

1. Request quotes

2. Create the transaction

3. Complete the Stripe sandbox checkout

4. Receive the outgoing webhook

5. Reconcile through the transaction API

Test outgoing webhooks

Verify the signature

What sandbox proves

Troubleshooting