Skip to main content
All systems operationalChangelogv1
Log in

Direct API

Build a merchant-owned payment experience with DEUNA server APIs.

Last updated October 12, 2026
On this page
Integration method

Own the interface and coordinate payments from your backend.

Build the customer journey in your application and use DEUNA APIs for payment, user, card, and orchestration operations.

Interface
Merchant-owned frontend and backend
Delivery model
Server-to-server APIs with client-side support where required
Best for
Teams that require maximum product control
Compare methodsOpen reference

Use Direct API when your team owns the checkout interface and calls DEUNA from a trusted merchant backend. Your client collects or tokenizes the payment instrument, your backend creates the payment, and both layers handle any customer action required before the final payment state.

Follow the integration path#

1. Configure accessChoose the correct public key, private key, and optional customer Bearer token.2. Prepare the environmentSet base URLs, Postman, network access, retries, rate limits, and client timeouts.3. Collect payment detailsTokenize card data or collect the fields required by the selected payment method.4. Create the paymentImplement the Purchase V2 request, response, headers, and idempotency contract.5. Handle every stateImplement customer action, pending processing, success, denial, capture, void, and refund states.6. Reconcile updatesReceive asynchronous status notifications and confirm the authoritative order state.

1. Configure the merchant and environment#

Before writing the payment request:

  1. Complete account setup and obtain credentials for the sandbox environment.
  2. Read Authentication and API keys to separate public client credentials, private backend credentials, and optional customer identity.
  3. Configure at least one eligible payment connection and routing strategy. Use Provider capabilities to confirm country, method, currency, and operation support, then review Payment strategies.
  4. Apply the shared environment and network requirements in API integration essentials.
  5. Fork the supported Postman collection when you want to inspect sandbox requests before implementing a client.

Sandbox and production use different base URLs, credentials, provider connections, and payment data. Do not mix resources between environments.

2. Collect the payment source safely#

The merchant owns the Direct API interface, but card-data handling still depends on its PCI scope.

  • If the client must avoid handling raw card details on the merchant backend, use the supported card tokenization flow and send the resulting payment-method token to the backend.
  • If the configured fraud provider requires browser or device data, implement the Direct API device-fingerprint flow.
  • For wallets and alternative payment methods, start with Provider capabilities, then follow the linked connection guide for required payment_source, specific_fields, redirect, QR, voucher, or callback behavior.
  • If an existing order token is available, the backend can retrieve its configured payment methods before processing it.

3. Create and process the payment#

New integrations should begin with POST /v2/merchants/orders/purchase. It supports two valid request models:

ModelWhen to use itDocumentation
Inline order · RecommendedCreate the order and process its payment in one Purchase V2 request.Payment request contract and complete industry examples
Existing order token · OptionalCreate the order first only when another channel or experience needs the order_token before payment.Create order, then process the existing order

Use the sandbox payment Quickstart for the shortest runnable backend flow. The endpoint catalog is the authoritative inventory of published operations and their supported callers.

For every supported payment-changing request, generate a stable X-Idempotency-Key in the backend. Reuse the same key and byte-for-byte identical body when retrying an uncertain attempt. Follow the complete idempotent-request guidance, including its retention window and conflict handling.

4. Handle the response and customer action#

An HTTP 2xx response means the API request was accepted or processed; it does not by itself prove that money moved. Read order.payment.data.status and any returned next action.

Choose the lifecycle that matches the selected method:

Card workflowHandle purchase, authorization, risk review, capture, void, refund, and final card states.3D SecurePresent a supported Direct API challenge and evaluate the resulting payment state.APM workflowHandle redirects, QR codes, vouchers, bank confirmation, cancellation, and expiration.

Do not use a browser return URL, SDK callback, or provider redirect as proof of payment. Keep fulfillment blocked while the payment is pending, processing, under review, or waiting for customer action.

5. Confirm asynchronous results#

Configure order and payment status webhooks for the merchant and environment. Verify the signature, accept repeated delivery idempotently, and acknowledge the request before running slow business logic.

When the synchronous response is lost or a notification is delayed, retrieve the original order with GET /merchants/orders/{order_token}. Reconcile the retrieved payment state before fulfillment or before creating a materially new attempt.

For network timeouts, follow Managing client timeouts. A client timeout does not mean the payment failed.

6. Implement post-payment operations#

Expose only the operations supported by the selected connection and current payment state:

CaptureCapture all or part of an eligible authorization.VoidRelease an eligible authorization before capture.RefundCreate a full or partial refund for a processed payment.

For advanced operation behavior, continue to Multiple Partial Captures, Multiple Partial Refunds, and asynchronous refunds.

Production-readiness checklist#

  • Private keys are stored only in protected backend configuration and redacted from logs.
  • Sandbox and production credentials, base URLs, connections, and data are isolated.
  • Every reachable payment status and required customer action is implemented.
  • The backend preserves order identifiers, request bodies, and idempotency keys for recovery.
  • Webhook signatures, duplicate delivery, delayed delivery, and out-of-order updates are tested.
  • Client timeout behavior follows the agreed timeout and reconciliation model.
  • 429 and platform errors follow rate-limit guidance and the error reference.
  • Capture, void, and refund controls are shown only when supported by the connection and current state.
  • Success, denial, 3DS, pending, timeout, retry, and provider-failure scenarios are certified before production.