Skip to main content
All systems operationalChangelogv1
Log in
DEUNA API

API Reference

Choose the correct DEUNA API operation, authorization model, and caller for each integration flow.

Last updated October 2, 2026Postman collection
On this page

The DEUNA API reference covers the merchant-backend and customer-application operations published in the previous documentation. Start with the caller—not only the resource name—because the supported authorization model changes by surface. Other API Gateway routes are intentionally excluded from this reference.

Use the API Reference navigation to browse the published operations by product area and resource.

Order and payment request examplesCopy complete Purchase V2 and optional create-order requests by industry.AuthenticationChoose the correct credential and authorization model for each caller.Create paymentReview the complete payment contract and interactive request panel.Themes APICreate and manage reusable Checkout and Widget theme configurations.

Base URLs#

Use the sandbox base URL while you build. Switch to production only after receiving production credentials and completing certification.

Sandbox
https://api.sandbox.deuna.io
Production
https://api.deuna.io

Choose the API surface#

SurfaceIntended callerAuthorizationUse it for
Merchant backend · server to serverTrusted merchant infrastructurePrivate API key in X-Api-Key; X-Store-Code and idempotency headers where requiredOrders, purchases, captures, refunds, voids and operational reads
Customer application · user to serverMerchant Web or mobile application acting for a customerPublic application context plus user Authorization: Bearer … after login; never embed a private keyOptional login, reusable profiles and addresses, and stored cards

Authentication#

Merchant backend

Send the private API key in X-Api-Key, not in the Bearer header. Keep it on trusted server infrastructure.

Server-to-server request headersHTTP
X-Api-Key: YOUR_PRIVATE_API_KEY
X-Store-Code: STORE_CODE
X-Idempotency-Key: order_1042-attempt_1
Content-Type: application/json

Authenticated customer

Send the user access token in the Bearer header. Some order and wallet operations also require the merchant application key or store context; each operation page lists its authorization and forwarded headers.

User-to-server request headersHTTP
Authorization: Bearer USER_ACCESS_TOKEN
X-Api-Key: APPLICATION_API_KEY
X-Store-Code: STORE_CODE
Content-Type: application/json

See Authentication for credential handling, token lifetimes and rotation.

Merchant backend operations#

POST
/merchants/orders
Create an order and obtain its order token
GET
/merchants/orders/{order_token}
Retrieve current order and payment state
GET
/merchants/orders/{order_token}/payments-methods
Get the payment methods available to the order
POST
/v2/merchants/orders/purchase
Create payment
POST
/v2/merchants/orders/{order_token}/capture
Capture an authorized payment
POST
/v2/merchants/orders/{order_token}/refund
Create a full or partial refund
GET
/merchants/checkout/themes
List and manage merchant Checkout themes

Customer application operations#

POST
/users/request-code
Request a one-time login code
POST
/users/login
Exchange an OTP for a user token
GET
/users/me
Read the authenticated user profile
GET
/users/{user_id}/cards
List stored cards for the authenticated user
PATCH
/users/{user_id}/cards/{card_id}/set-as-default
Set or unset the authenticated user's default card

Responses and errors#

2xxThe request succeeded.
4xxAuthentication, permissions, state or request data must change. Inspect the returned error code.
5xxDEUNA or a provider failed. Retry only when the operation is idempotent, using the same idempotency key.

Browse the complete list in Error codes.

Path versioning#

Use each path exactly as published. API Gateway frequently exposes canonical routes without an internal /api/v1 prefix. A version segment such as /v2 is included only when it is part of the public route shown in the catalog. Backwards-compatible changes are listed in the Changelog.