Mock Commerce & Billing

Payment Intents API

Model production payment lifecycles with stateful intents, client secrets, two-phase authorizations, and automated webhook events. Supports both automatic immediate capture and manual two-step authorization/capture workflows.

State Machine Lifecycle Interactive Playground Idempotency Keys

Payment Intent State Machine

Every PaymentIntent transitions through well-defined, immutable terminal or transitional states.

Step 1

requires_payment_method

Intent created on backend. Safe client_secret returned to frontend UI.

Action

requires_action

3DS 2.0 challenge or biometric authorization required before the bank approves funds.

Auth

requires_capture

Card authorized for two-step fulfillment (capture_method: "manual"). Awaiting capture.

Final

succeeded

Funds debited. Email receipt delivered to Virtual Inbox. Webhook dispatched.

Interactive Intent Execution

Test every step of the payment pipeline directly against your live isolated visitor sandbox.

Workflow: Backend invokes this endpoint when user initializes checkout. Amount is in the smallest currency unit (e.g. 4900 = $49.00 USD).

Create Payment Intent

POST

response.json

{

// Click "Send" above to execute this request against the live server.

}

Idempotency & Replay Protection

Prevent double-billing on network drops, mobile connection switching, and client retries.

How Idempotency Works

Attach a unique Idempotency-Key: <uuid> header to any POST request. If a retry occurs with the exact same key:

No duplicate charges or cards are processed.
The initial response payload is replayed verbatim.
The response includes header Idempotent-Replay: true.
Keys are cached per visitor sandbox for 24 hours.

Recommended Key Generation

Always tie your idempotency key to a specific checkout cart ID or user action attempt rather than a generic random string:

const idempotencyKey = `pay_${cartId}_${attemptIndex}`;

Production Integration Recipes

Complete client-side and server-side code samples for modern frameworks.

Frontend React Hook (Custom / Stripe Elements)

typescript

import { useState } from 'react';

export function usePaymentIntent() {

const [loading, setLoading] = useState(false);

const [error, setError] = useState<string | null>(null);

const processPayment = async (amount: number, cardDetails: any) => {

setLoading(true);

setError(null);

try {

// 1. Create intent on your backend

const res = await fetch('/api/create-intent', {

method: 'POST',

headers: { 'Content-Type': 'application/json' },

body: JSON.stringify({ amount }),

});

const { clientSecret, intentId } = await res.json();

// 2. Confirm intent with card data

const confirmRes = await fetch(https://playground.nileslabs.com/api/v1/payments/intents/${intentId}/confirm`, {

method: 'POST',

headers: {

'Content-Type': 'application/json',

'Idempotency-Key': idem_${intentId},

body: JSON.stringify({ payment_method: cardDetails }),

});

const result = await confirmRes.json();

return result;

} catch (err: any) {

setError(err.message || 'Payment failed');

throw err;

} finally {

setLoading(false);

}

};

return { processPayment, loading, error };

}

Python Backend Client

python

import requests

import uuid

API_BASE = "https://playground.nileslabs.com/api/v1"

def create_and_confirm_payment(amount_cents: int, card_num: str):

idempotency_key = f"order_py_{uuid.uuid4().hex[:12]}"

# 1. Create Intent

intent = requests.post(

f"{API_BASE}/payments/intents",

json={

"amount": amount_cents,

"currency": "usd",

"capture_method": "automatic",

"description": "Python SDK Test Order"

headers={"Idempotency-Key": idempotency_key}

).json()

intent_id = intent["id"]

# 2. Confirm Intent

confirmed = requests.post(

f"{API_BASE}/payments/intents/{intent_id}/confirm",

json={

"payment_method": {

"card_number": card_num,

"exp_month": 12,

"exp_year": 2028,

"cvc": "123"

}

).json()

return confirmed

PreviousHosted Checkout

Next3DS Challenge Modal