Process your first sandbox payment

0 of 4 complete

On this page

Prepare the server request
Process the order payment
Handle the immediate result
Confirm the final state
Next steps

This Quickstart uses the merchant-backend purchase endpoint. Before you begin, complete account setup, choose your integration, and confirm that your sandbox merchant has:

A private API key stored on your server.
At least one active payment connection and a routing strategy.
An order token and a payment-method token created by your selected client integration.
A public HTTPS endpoint that can receive DEUNA webhooks.

Prepare the server request#

Load the sandbox private key from your server’s secret storage. Keep the order token and payment-method token produced by the same sandbox flow available for the request body.

.envShell

DEUNA_PRIVATE_API_KEY=YOUR_SANDBOX_PRIVATE_API_KEY

Process the order payment#

Send the order and tokenized payment method to the verified merchant purchase endpoint. Reuse the same X-Idempotency-Key and request body if a network timeout makes the outcome uncertain.

curl --request POST \
  --url https://api.sandbox.deuna.io/v2/merchants/orders/purchase \
  --header "X-Api-Key: ${DEUNA_PRIVATE_API_KEY}" \
  --header "X-Idempotency-Key: order_1042-attempt_1" \
  --header "Content-Type: application/json" \
  --data '{
    "order_token": "YOUR_SANDBOX_ORDER_TOKEN",
    "payer_info": {
      "email": "buyer@example.com",
      "external_user_id": "customer_1042"
    },
    "payment_source": {
      "method_type": "credit_card",
      "payment_method": "YOUR_PAYMENT_METHOD_TOKEN"
    }
  }'

const response = await fetch("https://api.sandbox.deuna.io/v2/merchants/orders/purchase", {
  method: "POST",
  headers: {
    "X-Api-Key": "${DEUNA_PRIVATE_API_KEY}",
    "X-Idempotency-Key": "order_1042-attempt_1",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "order_token": "YOUR_SANDBOX_ORDER_TOKEN",
    "payer_info": {
      "email": "buyer@example.com",
      "external_user_id": "customer_1042"
    },
    "payment_source": {
      "method_type": "credit_card",
      "payment_method": "YOUR_PAYMENT_METHOD_TOKEN"
    }
  })
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();

import requests

response = requests.request(
    "POST",
    "https://api.sandbox.deuna.io/v2/merchants/orders/purchase",
    headers={
        "X-Api-Key": "${DEUNA_PRIVATE_API_KEY}",
        "X-Idempotency-Key": "order_1042-attempt_1",
        "Content-Type": "application/json"
    },
    json={
          "order_token": "YOUR_SANDBOX_ORDER_TOKEN",
          "payer_info": {
            "email": "buyer@example.com",
            "external_user_id": "customer_1042"
          },
          "payment_source": {
            "method_type": "credit_card",
            "payment_method": "YOUR_PAYMENT_METHOD_TOKEN"
          }
        },
)
response.raise_for_status()
data = response.json()

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.deuna.io/v2/merchants/orders/purchase",
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: ${DEUNA_PRIVATE_API_KEY}",
    "X-Idempotency-Key: order_1042-attempt_1",
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS => json_encode([
      "order_token" => "YOUR_SANDBOX_ORDER_TOKEN",
      "payer_info" => [
        "email" => "buyer@example.com",
        "external_user_id" => "customer_1042"
      ],
      "payment_source" => [
        "method_type" => "credit_card",
        "payment_method" => "YOUR_PAYMENT_METHOD_TOKEN"
      ]
    ])
]);

$response = curl_exec($curl);
curl_close($curl);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.sandbox.deuna.io/v2/merchants/orders/purchase"))
      .header("X-Api-Key", "${DEUNA_PRIVATE_API_KEY}")
      .header("X-Idempotency-Key", "order_1042-attempt_1")
      .header("Content-Type", "application/json")
      .method("POST", HttpRequest.BodyPublishers.ofString("{\n    \"order_token\": \"YOUR_SANDBOX_ORDER_TOKEN\",\n    \"payer_info\": {\n      \"email\": \"buyer@example.com\",\n      \"external_user_id\": \"customer_1042\"\n    },\n    \"payment_source\": {\n      \"method_type\": \"credit_card\",\n      \"payment_method\": \"YOUR_PAYMENT_METHOD_TOKEN\"\n    }\n  }"))
      .build();

    HttpResponse<String> response = HttpClient.newHttpClient().send(
      request, HttpResponse.BodyHandlers.ofString()
    );
    System.out.println(response.body());
  }
}

package main

import (
  "fmt"
  "io"
  "net/http"
  "strings"
)

func main() {
  request, err := http.NewRequest("POST", "https://api.sandbox.deuna.io/v2/merchants/orders/purchase", strings.NewReader("{\n    \"order_token\": \"YOUR_SANDBOX_ORDER_TOKEN\",\n    \"payer_info\": {\n      \"email\": \"buyer@example.com\",\n      \"external_user_id\": \"customer_1042\"\n    },\n    \"payment_source\": {\n      \"method_type\": \"credit_card\",\n      \"payment_method\": \"YOUR_PAYMENT_METHOD_TOKEN\"\n    }\n  }"))
  if err != nil { panic(err) }
  request.Header.Set("X-Api-Key", "${DEUNA_PRIVATE_API_KEY}")
  request.Header.Set("X-Idempotency-Key", "order_1042-attempt_1")
  request.Header.Set("Content-Type", "application/json")

  response, err := http.DefaultClient.Do(request)
  if err != nil { panic(err) }
  defer response.Body.Close()

  body, _ := io.ReadAll(response.Body)
  fmt.Println(string(body))
}

The exact payment_source and any specific_fields depend on the selected payment method and provider. See Process an order payment for the complete request contract.

Handle the immediate result#

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

Continue fulfillment only for the confirmed success state documented in Payment workflow and statuses.
Present any customer action, such as 3DS authentication, before retrying.
For pending or uncertain results, retrieve the original order instead of creating a duplicate attempt.
Use a new idempotency key only for a materially new payment attempt.

Confirm the final state#

Use the synchronous response to update the customer experience, but make fulfillment decisions from the latest verified state. Configure a merchant webhook, verify its signature, deduplicate the event, and then reconcile the order.

server.jsJavaScript

app.post('/webhooks/deuna', express.raw({type: 'application/json'}), async (request, response) => {
  const event = verifyDeunaSignature(request.body, request.headers);
  await storeEventOnce(event.id);
  await reconcileOrder(event.data.order_token);
  response.sendStatus(200);
});

Next steps#

Integrate the customer experienceOpen the guide for Payment Widget, Direct API, Payment Link, Vault, or plugins.Configure webhooksVerify signatures, deduplicate events, and reconcile asynchronous results.Payment endpoint referenceReview authorization, parameters, statuses, and the complete request contract.