Idempotency

Nexpay supports idempotent requests for financial mutation endpoints, allowing you to safely retry requests without the risk of performing the same operation twice. This is especially important for payment operations where network issues or timeouts may leave you uncertain whether a request was processed.

How it works

Financial mutation endpoints support idempotency — most importantly submitting a payment intent (POST /v2/payment-intents/{id}/submit). Nexpay uses two mechanisms to prevent duplicates:

1. Idempotency key (recommended) -- You provide an explicit key via the Idempotency-Key header.
2. Automatic fingerprinting -- If no key is provided, Nexpay automatically generates a fingerprint based on the request body to detect identical requests.

When an idempotency key is provided, it takes precedence over automatic fingerprinting.

Using the Idempotency-Key header

Include the Idempotency-Key header in your request with a unique value (e.g. a UUID) that identifies the intended operation:

curl -X POST 'https://api.nexpay.com.au/v2/payment-intents/507f1f77bcf86cd799439011/submit' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000'

try {
  const intentId = '507f1f77bcf86cd799439011';
  const response = await fetch(`https://api.nexpay.com.au/v2/payment-intents/${intentId}/submit`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'nxp_ck_your-client-id:nxp_sk_your-secret',
      // Derive the key from a stable upstream id (e.g. your order id) and reuse it across retries.
      'Idempotency-Key': '550e8400-e29b-41d4-a716-446655440000',
    },
  });

  if (response.ok) {
    const { data: intent } = await response.json();

    console.log(intent);
  } else {
    throw new Error(`Request failed with status: ${response.status}`);
  }
} catch (error) {
  console.error(error);
}

use Illuminate\Support\Facades\Http;

$intentId = '507f1f77bcf86cd799439011';

$response = Http::withHeaders([
    'X-API-Key' => 'nxp_ck_your-client-id:nxp_sk_your-secret',
    // Derive the key from a stable upstream id (e.g. your order id) and reuse it across retries.
    'Idempotency-Key' => '550e8400-e29b-41d4-a716-446655440000',
])->post("https://api.nexpay.com.au/v2/payment-intents/{$intentId}/submit");

if ($response->successful()) {
    $intent = $response->json('data');

    print_r($intent);
} else {
    throw new Exception("Request failed with status: {$response->status()}");
}

Behavior

Best practices

• Generate a unique key per operation -- Use a UUID or another unique identifier for each distinct payment. Do not reuse keys across different operations.

• Store keys alongside your records -- Save the idempotency key with the corresponding record in your system so you can reliably retry with the same key if needed.

• Retry safely on network errors -- If a request times out or you receive a network error, retry with the same Idempotency-Key to safely determine whether the original request was processed.

• Keys expire after 24 hours -- Idempotency keys are valid for 24 hours after the first request. After expiry, the same key may be reused for a new operation; an expired key replayed within the same 24h window returns the originally cached response.

• Which errors bind the key, which release it — Some errors lock the key to a failed-response replay; others leave the key un-engaged so a retry is safe. Quick reference:

  First-call outcome	Same key on retry
  2xx	Returns the original response (cached).
  4xx validation error	Bound to the error response — mint a new key for any corrected payload.
  [QOT0001] (expired quote)	Bound to the error — mint a new intent and a new key. See recovery.
  [PAY0003] from the connector	Not engaged — retry with the SAME key after the dedup window.
  5xx / network timeout	State unknown — either replay with the same key or GET the resource first to confirm state.
  429	Not engaged — retry with the same key after Retry-After.