Status Polling

#!/usr/bin/env bash
# Poll one transaction until it reaches a final state.
BASE="https://billapi.oneclickdz.com"
TXN="68b2f4c1a7d3e9f204c81a55"
INTERVAL=3
DEADLINE=$(( $(date +%s) + 300 ))

while [ "$(date +%s)" -lt "$DEADLINE" ]; do
  STATUS=$(curl -s "$BASE/v3/bills/transactions/$TXN" \
    -H "X-Access-Token: YOUR_API_KEY" \
    | grep -o '"status":"[A-Z_]*"' | head -1 | cut -d'"' -f4)

  echo "status=$STATUS"

  case "$STATUS" in
    SUCCESS|FAILED|REFUNDED) exit 0 ;;
    UNKNOWN)                 INTERVAL=30 ;;
    *)                       [ "$INTERVAL" -lt 10 ] && INTERVAL=$((INTERVAL + 2)) ;;
  esac

  sleep "$INTERVAL"
done

echo "still not final — hand over to background reconciliation"
exit 1

const BASE = "https://billapi.oneclickdz.com";
const KEY = process.env.ONECLICKDZ_API_KEY;

const FINAL = new Set(["SUCCESS", "FAILED", "REFUNDED"]);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function getTransaction(transactionId) {
  const response = await fetch(`${BASE}/v3/bills/transactions/${transactionId}`, {
    headers: { "X-Access-Token": KEY },
  });

  const body = await response.json();

  // Transient — worth another attempt.
  if (["AUTH_UNAVAILABLE", "SERVICE_UNAVAILABLE"].includes(body?.error?.code)) {
    return null;
  }

  if (!body.success) {
    throw new Error(`${body.error.code}: ${body.error.message}`);
  }

  return body.data;
}

async function pollUntilFinal(transactionId, { timeoutMs = 300_000 } = {}) {
  const deadline = Date.now() + timeoutMs;
  let interval = 3000;

  while (Date.now() < deadline) {
    const transaction = await getTransaction(transactionId);

    if (transaction) {
      if (FINAL.has(transaction.status)) return transaction;

      // Under review — slow right down, but never stop.
      interval = transaction.status === "UNKNOWN" ? 30_000 : Math.min(interval + 2000, 10_000);
    }

    await sleep(interval);
  }

  // Not final yet. Hand over — never assume a failure.
  await queueForReconciliation(transactionId);
  return null;
}

import os
import time
import requests

BASE = 'https://billapi.oneclickdz.com'
KEY = os.getenv('ONECLICKDZ_API_KEY')

FINAL = {'SUCCESS', 'FAILED', 'REFUNDED'}
TRANSIENT = {'AUTH_UNAVAILABLE', 'SERVICE_UNAVAILABLE'}


def get_transaction(transaction_id):
    response = requests.get(
        f'{BASE}/v3/bills/transactions/{transaction_id}',
        headers={'X-Access-Token': KEY}
    )

    body = response.json()

    # Transient — worth another attempt.
    if body.get('error', {}).get('code') in TRANSIENT:
        return None

    if not body['success']:
        raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")

    return body['data']


def poll_until_final(transaction_id, timeout_s=300):
    deadline = time.monotonic() + timeout_s
    interval = 3.0

    while time.monotonic() < deadline:
        transaction = get_transaction(transaction_id)

        if transaction:
            if transaction['status'] in FINAL:
                return transaction

            # Under review — slow right down, but never stop.
            interval = 30.0 if transaction['status'] == 'UNKNOWN' else min(interval + 2, 10)

        time.sleep(interval)

    # Not final yet. Hand over — never assume a failure.
    queue_for_reconciliation(transaction_id)
    return None

<?php
const BASE = 'https://billapi.oneclickdz.com';
const FINAL_STATUSES = ['SUCCESS', 'FAILED', 'REFUNDED'];
const TRANSIENT = ['AUTH_UNAVAILABLE', 'SERVICE_UNAVAILABLE'];

function getTransaction(string $transactionId): ?array
{
    $ch = curl_init(BASE . "/v3/bills/transactions/$transactionId");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'X-Access-Token: ' . getenv('ONECLICKDZ_API_KEY')
    ]);

    $body = json_decode(curl_exec($ch), true);
    curl_close($ch);

    // Transient — worth another attempt.
    if (in_array($body['error']['code'] ?? '', TRANSIENT, true)) {
        return null;
    }

    if (!$body['success']) {
        throw new Exception($body['error']['code'] . ': ' . $body['error']['message']);
    }

    return $body['data'];
}

function pollUntilFinal(string $transactionId, int $timeoutSeconds = 300): ?array
{
    $deadline = time() + $timeoutSeconds;
    $interval = 3;

    while (time() < $deadline) {
        $transaction = getTransaction($transactionId);

        if ($transaction !== null) {
            if (in_array($transaction['status'], FINAL_STATUSES, true)) {
                return $transaction;
            }

            // Under review — slow right down, but never stop.
            $interval = $transaction['status'] === 'UNKNOWN'
                ? 30
                : min($interval + 2, 10);
        }

        sleep($interval);
    }

    // Not final yet. Hand over — never assume a failure.
    queueForReconciliation($transactionId);
    return null;
}
?>