# Infini Basic Integration Workflow

Use this file when planning or advancing the guided session.

## Language-Aware Documentation

Choose document links based on the user's interaction language.

- Chinese docs base: `https://developer.infini.money/docs/zh`
- English docs base: `https://developer.infini.money/docs/en`
- English overview: `https://developer.infini.money/docs/en/1-overview`

If the user is speaking Chinese, prefer `zh` links.
If the user is speaking English, prefer `en` links.

## Official Links

- Hosted Checkout overview:
  - Chinese: `https://developer.infini.money/docs/zh/3-checkout-mode`
  - English: `https://developer.infini.money/docs/en/3-checkout-mode`
- Authentication and signing:
  - Chinese: `https://developer.infini.money/docs/zh/4-authorization`
  - English: `https://developer.infini.money/docs/en/4-authorization`
- API documentation:
  - Chinese: `https://developer.infini.money/docs/zh/6-api-ducumentation`
  - English: `https://developer.infini.money/docs/en/6-api-ducumentation`
- Webhook documentation:
  - Chinese: `https://developer.infini.money/docs/zh/7-webhook`
  - English: `https://developer.infini.money/docs/en/7-webhook`
- Error codes:
  - Chinese: `https://developer.infini.money/docs/zh/8-errorcodes`
  - English: `https://developer.infini.money/docs/en/8-errorcodes`
- Sandbox API key page: `https://business-sandbox.infini.money/developer`
- TRON Nile test token page: `https://nileex.io/join/getJoinPage`
- TRON test token guide: `https://developers.tron.network/docs/getting-testnet-tokens-on-tron`
- Webhook temporary receiver: `https://webhook.cool`

## Step 1: Confirm Language And Mode

Ask in the user's language:

- whether they use `Node.js` or `Python`
- whether they want `Hosted Checkout` or `Advanced Payment API`

Explain simply:

- Hosted Checkout: easiest, because Infini hosts the payment page for the user
- Advanced Payment API: more flexible, but more things must be handled by the user
- Key difference: Hosted Checkout means less work because Infini handles the payment page, while Advanced Payment API means more control but also more work

If the user is unsure, recommend Hosted Checkout.

## Step 2: Confirm Sandbox

Tell the user:

- we start in sandbox by default
- this is safer because mistakes happen in test mode, not in the real environment

Base URLs:

- Sandbox: `https://openapi-sandbox.infini.money`
- Production: `https://openapi.infini.money`

## Step 3: Get API Key

Direct the user to:

- `https://business-sandbox.infini.money/developer`

Tell the user to prepare:

- `key_id`
- `secret_key`

Explain simply:

- `key_id` is like the public name of the key
- `secret_key` is the password part and must stay on the server

Ask the user to confirm after the keys are ready.

## Step 4: Implement Request Signing

Use the authentication doc in the user's language.

Explain simply:

- Infini needs proof that the request really comes from your server
- the signature is that proof
- without the signature, Infini cannot trust that the request was really sent by you

Before giving code, explain `.env` in plain language:

- `.env` is just a small text file used to store private values like `key_id` and `secret_key`
- this helps the user avoid hardcoding secrets directly in the code
- if the user is a beginner, tell them they can create a file named `.env` in the project root

If you show a first code sample, explain that beginners can place it in a single file first, such as `index.js` or `app.py`, instead of splitting files too early.

When showing Python or Node.js examples, use only fields that are confirmed in the current official create-order documentation.

Important details to include:

- Header `Date` is required
- Header `Authorization` is required
- Header `Digest` is required when the request has a body
- The signing algorithm is HMAC-SHA256
- Time drift must stay within about 5 minutes

Also explain these headers in plain language:

- `Date`: the current request time, used so the server knows the request is fresh
- `Digest`: a short fingerprint of the request body, used so the server knows the body was not changed
- `Authorization`: the final signed proof, built from the request path, time, and body fingerprint

Also explain how they are obtained:

- `Date` is generated from the current server time
- `Digest` is generated by hashing the request body with SHA-256
- `Authorization` is generated by signing the prepared signing string with `secret_key`

## Step 5: Create Order

Use the API doc in the user's language.

Endpoint:

- `POST /v1/acquiring/order`

Explain simply:

- this call asks Infini to create a payment order
- if it succeeds, Infini returns a `checkout_url`

Use only fields confirmed in the current official documentation when giving examples:

- `amount`
- `currency`
- `client_reference`
- `description`
- `expires_at`

Do not present `redirect_url` as an official field.
Do not present `notify_url` as an official field in the create-order request unless the official docs later confirm it.

When giving create-order code, tell the user how it connects to the previous step:

- for beginners, keep it in the same file as the signing example first
- explain that the create-order code reuses the `date`, `digest`, `authorization`, and `body` values from the previous step
- only suggest splitting files later if the user asks for a cleaner project structure

## Step 6: Open checkout_url

Explain simply:

- this link is the Infini payment page
- after you create the order, you send the user to that link to pay
- because this is `sandbox`, the payment is only a test and does not mean real funds are being collected

Completion check:

- the user can see the payment page
- the order data looks correct

Also guide the user to complete one real sandbox payment:

- tell the user they need test tokens before the test payment can succeed
- give the test token links directly:
  - `https://nileex.io/join/getJoinPage`
  - `https://developers.tron.network/docs/getting-testnet-tokens-on-tron`
- say clearly that these are for the `sandbox` test flow only

## Step 7: Configure Webhook

Use the API doc and webhook doc in the user's language.

Explain simply:

- webhook is how Infini tells your server that the payment status changed
- this lets your backend know whether the order is processing, completed, expired, or late

First guide the user to use `webhook.cool` for a quick sandbox callback test:

- open `https://webhook.cool`
- create a temporary webhook URL
- configure the webhook destination by following the current official webhook setup path
- complete one sandbox payment after webhook is configured
- confirm that a callback arrives and the user can see the event body and headers

Only after that, guide the user to replace the temporary `webhook.cool` URL with their own backend webhook endpoint.

If the user says they do not need webhook yet:

- explain that they can stop here temporarily
- explain that this means the integration is only partially complete

Common events to mention:

- `order.processing`
- `order.completed`
- `order.expired`
- `order.late_payment`

## Step 8: Verify Webhook Signature

Use the authentication doc and webhook doc in the user's language.

Explain simply:

- webhook verification checks that the callback really came from Infini
- without this check, anyone could pretend to send you a payment result

Important headers:

- `X-Webhook-Timestamp`
- `X-Webhook-Event-Id`
- `X-Webhook-Signature`

Signature content format:

- `{timestamp}.{event_id}.{payload_body}`

Explain the verification steps in plain language:

1. Read `X-Webhook-Timestamp`
2. Read `X-Webhook-Event-Id`
3. Read the raw webhook body exactly as received
4. Concatenate them as `{timestamp}.{event_id}.{payload_body}`
5. Use `secret_key` to calculate an HMAC-SHA256 signature
6. Compare your computed result with `X-Webhook-Signature`
7. Only trust the callback if they match

## Step 9: Sandbox Payment Test

Use the supported chains and testnet doc when needed:

- Chinese: `https://developer.infini.money/docs/zh/11-supported-chains`
- English: `https://developer.infini.money/docs/en/11-supported-chains`

Explain simply:

- after order creation and webhook setup both work, run a full test payment
- the goal is to confirm order creation, redirect, payment completion, and webhook callback all work together

## Step 10: Production Switch

After sandbox succeeds, explain:

- change the API base URL to production
- change to production keys
- recheck the production webhook URL
- do one controlled production verification before real launch