API integration essentials
Configure DEUNA environments, Postman, network access, idempotency, response handling, and client timeouts.
On this page
Use these shared settings before integrating a DEUNA API resource. The same environment, network, retry, and timeout rules apply across orders, payments, users, payment links, and subscriptions.
Environments#
Sandbox and production are isolated and use different credentials, data, provider connections, and payment state.
| Environment | Base URL | Use |
|---|---|---|
| Sandbox | https://api.sandbox.deuna.io | Integration and certification testing |
| Production | https://api.deuna.io | Live transactions |
See Authentication and environments for credential types, rotation, and request examples.
Postman collection#
Use the DEUNA Postman collection to explore requests without building a client first.
Open the DEUNA collection in Postman
- Sign in to Postman and fork the collection into your workspace.
- Select the sandbox or production environment.
- Set
merchant_id,public_api_key, andprivate_api_keywith the values for that environment. - Start with an operation from the endpoint catalog.
IP addresses#
Prefer domain allowlisting when your network policy supports it. If a payment or fraud provider requires IP allowlisting, use the addresses below.
| Environment | Provider traffic |
|---|---|
| Sandbox | 3.22.44.237 |
| Production | 3.131.108.151 · 3.132.78.68 · 3.19.18.42 · 18.220.134.28 |
Response codes#
Successful operations return a 2xx response. A 4xx response means that authentication, permissions, request data, or resource state must change. A 5xx response is a temporary DEUNA or provider failure and should be retried only when the operation is safe to repeat.
Use the response and error code reference to identify the cause, retry policy, and corrective action.
Idempotent requests#
Send a stable X-Idempotency-Key for each supported operation that creates or changes payment state. Reuse the same key and byte-for-byte identical request body when retrying after a network failure or client timeout. Use a new key for a new business attempt.
X-Api-Key: YOUR_PRIVATE_API_KEY
X-Store-Code: STORE_CODE
X-Idempotency-Key: order_1042-attempt_1
Content-Type: application/jsonSuccessful responses are retained for 24 hours by default. Read Idempotent requests for supported endpoints, error-response retention, replay headers, conflicts, and sandbox verification.
Client timeouts#
A client timeout means that the caller stopped waiting; it does not prove that a payment failed. Payment processing can continue through fraud checks, routing, and a provider after the client disconnects.
When a payment request times out:
- Keep fulfillment blocked and mark the attempt as pending reconciliation in your own system.
- Preserve the order ID, request body, and original idempotency key.
- Retry only when the operation is eligible, using the same idempotency key and identical body.
- Reconcile the final state through the supported asynchronous processing model and an appropriate order lookup in the endpoint catalog.
- Surface the reconciled result to the shopper and resolve any required void or refund before fulfillment.