Lesson 2 — Create a payment intent

The payment intent is the single object that tracks one payment through

its whole life — across any rail. This lesson creates one and reads its

next_action.

The lifecycle

requires_action → processing → succeeded | failed

You never branch on the rail. You read next_action.type and do exactly what

it says. That is the core of the "one integration, all rails" promise.

Create the intent

curl https://api.transxact.io/payment-intents \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order-1234" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500,
    "reference": "order-1234",
    "return_url": "https://you.example.com/thanks"
  }'

Two details worth internalising:

• amount is in FJD cents — 2500 is FJ$25.00.
• Idempotency-Key makes retries safe. If your network drops after the

server processed the create, replaying with the same key returns the same

intent instead of charging twice.

Read the response

{
  "intent": {
    "id": "pi_...",
    "status": "requires_action",
    "next_action": { "type": "redirect", "url": "/simulate/pi_..." }
  }
}

requires_action means the customer must now do something. What they do is

fully described by next_action:

Exercise

1. Create three intents with amounts 100, 200, and 5000, each with a

distinct reference.

2. Fetch one back with GET /payment-intents/{id} and confirm the status.

3. Retry the exact same create with the same Idempotency-Key and verify you

get the *same* intent id (check is_replay semantics in the

payment intents reference).

What's next

Your intent is waiting at requires_action. Drive it to completion in

Lesson 3.

1. Your first API call

2. Create a payment intent

3. Complete the payment

4. Magic values

5. Receive webhooks

6. Links & going live