Build a subscriptions integration

// Generate and store a unique customer identifier
String merchantCustId = "CUST-" + UUID.randomUUID();
userRepository.saveMerchantCustId(userId, merchantCustId);

// Check whether a 3DS redirect is needed
if ("R".equals(status)) {
    return Map.of("action", "redirect", "url", redirectUrl);
}

// Perform redirect (use replace to avoid adding an intermediate page to history)
if (result.action === 'redirect') {
  window.location.replace(result.url);
}

@PostMapping(value = "/webhook", produces = "text/plain")
public String handleWebhook(@RequestBody Map<String, Object> data) {
    String transactionId = (String) data.get("transactionId");

    // 1. Verify signature (see API docs)
    if (!verifySignature(data)) {
        return "";
    }

    // 2. Idempotency guard: transactionId is the deduplication key
    if (alreadyProcessed(transactionId)) {
        return transactionId;
    }

    try {
        // 3. Parse key fields
        String txnType = (String) data.get("txnType");
        String status = (String) data.get("status");                    // S=success, F=failure
        String merchantCustId = (String) data.get("merchantCustId");

        // 4. Dispatch by transaction type
        if ("BIND_CARD".equals(txnType)) {
            handleBindCard(data, status, merchantCustId);
        } else if ("SALE".equals(txnType)) {
            handleSale(data, status, merchantCustId);
        }

        // 5. Mark success and acknowledge
        markProcessed(transactionId);
        return transactionId;
    } catch (Exception ex) {
        // Return empty response to trigger Onerway retry
        log.error("Webhook processing failed, transactionId={}", transactionId, ex);
        return "";
    }
}

// Handle card-binding notification (BIND_CARD does not include contractId)
private void handleBindCard(Map<String, Object> data, String status, String merchantCustId) {
    if (!"S".equals(status)) {
        log.warn("Card binding failed: merchantCustId={}", merchantCustId);
        return;
    }
    saveTokenId(merchantCustId, (String) data.get("tokenId"));
}

// Handle charge notification
private void handleSale(Map<String, Object> data, String status, String merchantCustId) {
    String scenarios = (String) data.get("scenarios");
    String subscriptionStatus = (String) data.get("subscriptionStatus");
    String contractId = (String) data.get("contractId");
    String tokenId = (String) data.get("tokenId");

    // Save subscription credentials first (idempotent)
    saveSubscription(merchantCustId, contractId, tokenId);

    // Check transaction result
    if (!"S".equals(status)) {
        handlePaymentFailure(merchantCustId, subscriptionStatus);
        return;
    }

    // Dispatch by subscription event type
    switch (scenarios) {
        case "SUBSCRIPTION_INITIAL":
            handleInitialSubscription(merchantCustId, subscriptionStatus);
            break;
        case "SUBSCRIPTION_RENEWAL":
            handleRenewalSuccess(merchantCustId, contractId);
            break;
        case "SUBSCRIPTION_CANCELED":
        case "SUBSCRIPTION_ENDED":
            revokeAccess(merchantCustId);
            break;
    }
}

// Initial subscription: activate service based on subscriptionStatus
private void handleInitialSubscription(String merchantCustId, String subscriptionStatus) {
    switch (subscriptionStatus) {
        case "active":   grantFullAccess(merchantCustId); break;
        case "trialing": grantTrialAccess(merchantCustId); break;
        // paymentdue: awaiting payment, do not activate yet
    }
}

// Renewal succeeded
private void handleRenewalSuccess(String merchantCustId, String contractId) {
    extendUserAccess(merchantCustId);
    subscriptionRepository.updateNextBillingDate(contractId);
}

// Payment failed
private void handlePaymentFailure(String merchantCustId, String subscriptionStatus) {
    if ("pastdue".equals(subscriptionStatus)) {
        sendPaymentReminder(merchantCustId);  // Renewal failed — send dunning notification
    }
}

@Scheduled(cron = "0 0 2 * * ?") // Run daily at 2 AM to process due renewals
public void processRenewals() {
    List<Subscription> dueSubscriptions =
        subscriptionRepository.findByNextBillingDateBefore(LocalDate.now());

    for (Subscription sub : dueSubscriptions) {
        Map<String, Object> subscription = new HashMap<>();
        subscription.put("requestType", "1");          // Renewal
        subscription.put("merchantCustId", sub.getMerchantCustId());
        subscription.put("contractId", sub.getContractId());
        subscription.put("tokenId", sub.getTokenId());
        // billingInformation can be empty: "{}"

        // Call renewal API (see API docs for full parameter list)
        httpClient.post(ONERWAY_API_URL, buildRequest(subscription));
        // Wait for the SALE webhook before updating business state
    }
}

// Update business state after receiving the renewal SALE webhook
private void handleRenewalSale(JSONObject data) {
    if ("S".equals(data.getString("status"))) {
        extendUserAccess(data.getString("merchantCustId"));
        subscriptionRepository.updateNextBillingDate(data.getString("contractId"));
    }
}

// Frontend: confirm and submit cancellation
async function cancelSubscription(contractId) {
  if (!confirm('Are you sure you want to cancel your subscription?')) return;
  await fetch('/api/cancel-subscription', {
    method: 'POST',
    body: JSON.stringify({ contractId })
  });
}

// Backend: call cancellation API (access is revoked when the SUBSCRIPTION_CANCELED webhook arrives)
@PostMapping("/api/cancel-subscription")
public ResponseEntity<?> cancelSubscription(@RequestBody Map<String, String> req) {
    Map<String, Object> cancelRequest = new HashMap<>();
    cancelRequest.put("contractId", req.get("contractId"));
    // Call cancellation API (see API docs for full parameter list)
    httpClient.post(ONERWAY_CANCEL_API_URL, buildRequest(cancelRequest));
    // Access is revoked when the SUBSCRIPTION_CANCELED webhook arrives
    return ResponseEntity.ok(Map.of("message", "Cancellation request submitted"));
}