Hosted Checkout

Complete Hosted Checkout flow in Java 17+. Your server creates a payment link, redirects the customer, then confirms payment server-side.

Prerequisites: Sandbox Setup, staging x-api-key, Java 17+ with java.net.http.HttpClient.

The path is spelled /payment/checkout/intiate — not /session.

Never mark an order paid based only on arrival at successUrl. Always confirm via status API or webhook.

Architecture

sequenceDiagram
  participant Browser as Customer Browser
  participant Shop as Your Java Server
  participant API as DigetPay API
  participant Checkout as DigetPay Checkout

  Browser->>Shop: Checkout (order total)
  Shop->>API: POST /payment/checkout/intiate
  API-->>Shop: redirectUrl
  Shop->>Browser: HTTP 302 redirect
  Browser->>Checkout: Pay (card / Mada / Apple Pay)
  Checkout->>Browser: Redirect successUrl / failureUrl
  Browser->>Shop: Return to your site
  Shop->>API: GET /payment/checkout/status
  API-->>Shop: transactionStatus

Step 1 — Configuration

// DigetPayConfig.java
public final class DigetPayConfig {
    private static final Map<String, String> API_BASES = Map.of(
        "staging", "https://fin-api.digetpay.com/v1",
        "production", "https://api.digetpay.com/v1"
    );

    public static String environment() {
        return System.getenv().getOrDefault("DIGETPAY_ENV", "staging");
    }

    public static String apiKey() {
        String key = System.getenv("DIGETPAY_API_KEY");
        if (key == null || key.isBlank()) throw new IllegalStateException("DIGETPAY_API_KEY is not set");
        return key;
    }

    public static String apiBase() {
        return API_BASES.get(environment());
    }
}

Step 2 — API client

// DigetPayClient.java
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.*;
import java.util.Map;

public class DigetPayClient {
    private final HttpClient http = HttpClient.newHttpClient();
    private final ObjectMapper mapper = new ObjectMapper();
    private final String apiBase = DigetPayConfig.apiBase();
    private final String apiKey = DigetPayConfig.apiKey();

    @SuppressWarnings("unchecked")
    private Map<String, Object> request(String method, String path, Map<String, Object> body) throws Exception {
        HttpRequest.Builder builder = HttpRequest.newBuilder()
            .uri(URI.create(apiBase + path))
            .header("Content-Type", "application/json")
            .header("x-api-key", apiKey);
        if (body != null) {
            builder.method(method, HttpRequest.BodyPublishers.ofString(mapper.writeValueAsString(body)));
        } else {
            builder.method(method, HttpRequest.BodyPublishers.noBody());
        }
        HttpResponse<String> resp = http.send(builder.build(), HttpResponse.BodyHandlers.ofString());
        if (resp.statusCode() >= 400) throw new RuntimeException("DigetPay HTTP " + resp.statusCode() + ": " + resp.body());
        return mapper.readValue(resp.body(), Map.class);
    }

    public Map<String, Object> createPaymentLink(Map<String, Object> payload) throws Exception {
        return request("POST", "/payment/checkout/intiate", payload);
    }

    public Map<String, Object> getTransactionStatus(String gatewayTransactionId) throws Exception {
        return request("GET", "/payment/checkout/status?id=" + gatewayTransactionId, null);
    }

    public Map<String, Object> processRefund(String transactionId, double amount) throws Exception {
        return request("POST", "/payment/refund", Map.of("transactionId", transactionId, "amount", amount));
    }
}

Step 3 — Create payment link and redirect

Spring Boot controller example:

@GetMapping("/checkout")
public ResponseEntity<Void> checkout() throws Exception {
    boolean isStaging = "staging".equals(DigetPayConfig.environment());
    String successUrl = isStaging
        ? "https://fin-admin.digetpay.com/pay/checkout/success"
        : "https://yourstore.com/checkout/success";
    String failureUrl = isStaging
        ? "https://fin-admin.digetpay.com/pay/checkout/failure"
        : "https://yourstore.com/checkout/failure";

    Map<String, Object> session = new DigetPayClient().createPaymentLink(Map.of(
        "merchantOrderId", "ORD-" + System.currentTimeMillis(),
        "amount", 10.0,
        "currency", "SAR",
        "customerName", "Ahmed Ali",
        "customerEmail", "[email protected]",
        "customerPhone", "501223324",
        "successUrl", successUrl,
        "failureUrl", failureUrl
    ));
    // Store session id in your DB before redirect
    return ResponseEntity.status(HttpStatus.FOUND)
        .location(URI.create((String) session.get("redirectUrl")))
        .build();
}

Apple Pay: DigetPay checkout displays Apple Pay when the customer uses Safari and customerPhone was sent. No additional Java code required — see Apple Pay on Hosted Checkout.

Step 4 — Handle return URLs

@GetMapping("/checkout/success")
public String checkoutSuccess(@RequestParam(required = false) String sessionId) {
    return "Processing your payment… We will confirm shortly.";
}

Step 5 — Confirm payment

Map<String, Object> response = client.getTransactionStatus("2232e99b-0257-47d5-bbfd-022c8951767f");
// Parse data.content[0].transactionStatus === "SUCCESS"

See Query Transaction Status.

Step 6 — Webhook handler

@PostMapping("/webhooks/digetpay")
public ResponseEntity<String> webhook(@RequestBody Map<String, Object> payload) {
    // Idempotent update — skip if already processed
    return ResponseEntity.ok("OK");
}

Full details: Handle Webhooks, Verify Signatures.

Step 7 — Refund

client.processRefund("2232e99b-0257-47d5-bbfd-022c8951767f", 5.0);

Process Refund guide →

Next steps

Checkout Experience

Customer-facing checkout UX.

Webhooks Code (Java)

Dedicated webhook handler stub.

Fin Staging Guide

Validate before go-live.