API integration essentials

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, and webhook endpoints.

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

1. Sign in to Postman and fork the collection into your workspace.
2. Select the sandbox or production environment.
3. Set merchant_id, public_api_key, and private_api_key with the values for that environment.
4. Start with an operation from the endpoint catalog.

IP addresses#

Prefer domain allowlisting when your network policy supports it. If your webhook receiver or a payment or fraud provider requires IP allowlisting, use the addresses below.

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 every distinct operation that creates or changes payment state. Reuse the same key and 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/json

See Create a payment for the purchase-specific contract and retry example.

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:

1. Keep fulfillment blocked and mark the attempt as pending reconciliation in your own system.
2. Preserve the order ID, request body, and original idempotency key.
3. Retry only when the operation is eligible, using the same idempotency key and identical body.
4. Reconcile the final state from a verified webhook or an appropriate order lookup in the endpoint catalog.
5. Surface the reconciled result to the shopper and resolve any required void or refund before fulfillment.