Skill: cola234/infini-api (version 1.0.0)

--- name: infini-api description: Guide users through Infini's basic API integration and webhook integration with step-by-step explanations, sandbox-first setup, and directly runnable Node.js or Python examples. Use when the user asks for help integrating Infini API, Hosted Checkout, webhook callbacks, API signing, sandbox testing, or go-live preparation, including equivalent Chinese or English phrasing such as "指引我完成 Infini API 接入", "帮我接入 Infini 支付", "guide me through Infini integration", or "help me integrate Infini payment". --- # Infini API ## Overview Guide 0-base users through Infini's basic integration flow one step at a time. Default to explanation, links, and runnable examples only; do not modify local code unless the user clearly authorizes code changes. This skill must support both Chinese and English. Match the user's interaction language by default: - if the user writes in Chinese, reply in Chinese and prefer `https://developer.infini.money/docs/zh/...` - if the user writes in English, reply in English and prefer `https://developer.infini.money/docs/en/...` - if the user switches language mid-conversation, switch with them Always treat this English overview page as a valid official entry point when the user prefers English: - `https://developer.infini.money/docs/en/1-overview` ## Operating Rules - Treat this as a guided integration session, not a one-shot answer. - Use simple, everyday language. Avoid dense jargon unless the user asks for deeper detail. - Match the user's interaction language for explanations, questions, code comments, and checklists. - Always keep the user on the current step until they confirm completion. - Show progress as `<current>/<total>`, for example `1/8`. - Only ask for completion after steps that require the user to actually do something. - For explanation-only steps, use a lighter confirmation that matches the user's language. - Default to `sandbox` and say that clearly. - Explain how to switch to production after sandbox succeeds. - Provide the official document link for every step, using the language that matches the user whenever possible. - Provide runnable examples in the user's language only after asking whether they use `Node.js` or `Python`. - When showing code, explain the important variables in plain language and tell the user whether to place the new code in the same file or a new file. - When showing environment variables, explain `.env` usage in plain language before expecting the user to use it. - Do not modify local files or suggest edits as if they already happened unless the user explicitly asks for code changes. ## Documentation Link Rule Use the official docs in the same language as the user. - Chinese docs base: `https://developer.infini.money/docs/zh` - English docs base: `https://developer.infini.money/docs/en` - English overview entry: `https://developer.infini.money/docs/en/1-overview` When giving a step link, prefer the same page in the user's language if both versions exist. ## First Turn Behavior When this skill triggers, do not jump straight into code. First: 1. Detect whether the user is currently speaking Chinese or English. 2. Confirm whether the user uses `Node.js` or `Python`. 3. Ask which integration mode they want. 4. Explain the two modes in simple words: - `Hosted Checkout`: you create the order first, then Infini gives you a payment page link. The user completes payment on Infini's page, so you do not need to build the payment page yourself. This is the easiest option and should be the default recommendation. - `Advanced Payment API`: you control more of the payment flow yourself. This gives more flexibility, but also means more integration work and more things to handle correctly. - Key difference: `Hosted Checkout` saves effort because Infini hosts the payment page, while `Advanced Payment API` gives more control but needs a stronger technical setup. 5. If the user does not choose, recommend `Hosted Checkout`. 6. Tell the user the guide will start in `sandbox`. ## Conversation Loop Follow this loop for the whole session: 1. Show a short status block in the user's current language. 2. State the current step in plain language. 3. Explain what this step does and why it matters. 4. Give the official link for this step in the user's language whenever possible. 5. Give language-specific runnable example code when code is needed. 6. Tell the user how to check whether the step worked. 7. Ask for completion only when the user needs to perform an actual action. 8. Move to the next step only after the user clearly confirms completion. Use a status block that matches the conversation language. Chinese example: ```text Infini 接入进度 进度: <current>/<total> 当前步骤: <step> 环境: <sandbox|production> 语言: <Node.js|Python|unknown> 模式: <Hosted Checkout|Advanced Payment API|unknown> 已完成: <items or 无> 当前卡点: <issue or 无> 下一步: <single next action> ``` English example: ```text Infini Integration Progress Progress: <current>/<total> Current Step: <step> Environment: <sandbox|production> Language: <Node.js|Python|unknown> Mode: <Hosted Checkout|Advanced Payment API|unknown> Completed: <items or none> Current Blocker: <issue or none> Next Action: <single next action> ``` ## Default Workflow For this skill, only support the basic integration path and webhook path. Read [workflow.md](references/workflow.md) when guiding the user through the steps. Read [api-notes.md](references/api-notes.md) when the user needs concrete endpoints, headers, signing details, or webhook verification details. Read [troubleshooting.md](references/troubleshooting.md) when the user reports an error or gets stuck. The default step order is: 1. Confirm language and integration mode 2. Confirm sandbox environment 3. Get API key 4. Implement request signing 5. Create an order 6. Open the returned `checkout_url` and complete one sandbox test payment 7. Configure webhook and verify webhook signature 8. Explain production switch-over For users who say they do not need webhook yet: - allow them to stop after the sandbox payment test as a temporary checkpoint - explain clearly that this is not a full integration yet - do not mark the full integration complete until webhook is also handled or the user explicitly says they only want the partial flow for now ## API Key Step Requirement When the guide reaches the API key step, always give the user this direct sandbox URL: `https://business-sandbox.infini.money/developer` Also give the official authentication document in the user's language: - Chinese: `https://developer.infini.money/docs/zh/4-authorization` - English: `https://developer.infini.money/docs/en/4-authorization` Tell the user to get: - `key_id` - `secret_key` Remind the user: - start with sandbox keys - keep `secret_key` on the server side only - reply only after they have the keys ready ## Troubleshooting Mode When the user reports an error: 1. Stay on the current step. 2. Ask for the exact error text, request code, or webhook payload only if needed. 3. Check [troubleshooting.md](references/troubleshooting.md) first for common errors and fixes. 4. If the issue matches a known case, answer with that fix first. 5. If the issue does not match a known case, continue manual diagnosis using the current step and the official docs. 6. Do not skip ahead just to keep momentum. ## Webhook Testing Rule Before asking the user to connect a real backend webhook endpoint, first guide them to use `webhook.cool` to receive one callback successfully in sandbox. Explain that this is only for quick testing and observation, then move to their real backend webhook after they understand the callback shape. ## Field Accuracy Rule When showing order creation examples, only use fields that are confirmed in the current official Infini documentation. - Do not present `redirect_url` as an official create-order field unless the current official docs explicitly show it. - Do not present `notify_url` as a default create-order field unless the current official docs explicitly show it. - If a user asks about those fields, say whether the current official docs confirm them or not. ## Production Switch Rule After sandbox passes, explain production in simple words: - replace the sandbox base URL with the production base URL - replace sandbox keys with production keys - recheck the webhook URL and signature handling - rerun a controlled end-to-end payment test before going live Do not claim the integration is complete until the user explicitly says it is complete or no longer needs guidance.

path: references/api-notes.md
content: # Infini API Notes

Use this file when the user needs exact technical details.

## 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`

## Base URLs

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

## API Key Page

- Sandbox key page: `https://business-sandbox.infini.money/developer`

## Authentication

Docs:

- Chinese: `https://developer.infini.money/docs/zh/4-authorization`
- English: `https://developer.infini.money/docs/en/4-authorization`

Required request headers:

- `Date`
- `Authorization`
- `Digest` when the request has a body

Plain-language explanation:

- `Date`: the request time
- `Digest`: the fingerprint of the request body
- `Authorization`: the signed proof that the request was created by your server

Signing method:

- HMAC-SHA256

Clock requirement:

- the request timestamp should stay within about 300 seconds of server time

## Basic Hosted Checkout Flow

Docs:

- Chinese: `https://developer.infini.money/docs/zh/3-checkout-mode`
- English: `https://developer.infini.money/docs/en/3-checkout-mode`
- Chinese API doc: `https://developer.infini.money/docs/zh/6-api-ducumentation`
- English API doc: `https://developer.infini.money/docs/en/6-api-ducumentation`

Core flow:

1. Create order with `POST /v1/acquiring/order`
2. Read the returned `checkout_url`
3. Send the user to that URL
4. Receive webhook events
5. Verify the webhook signature

## Confirmed Create-Order Fields

From the current official create-order example, the confirmed request body fields are:

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

Do not treat `redirect_url` as a confirmed official field.
Do not treat `notify_url` as a confirmed official field in the create-order request unless the current official docs explicitly show it.

## Environment Variables

When explaining `.env`, keep it simple:

- a `.env` file is a text file for storing private values
- common beginner example:

```env
INF_KEY_ID=your_key_id
INF_SECRET_KEY=your_secret_key
```

- tell the user to place the file in the project root
- tell the user not to commit the real `secret_key`

When showing code, explain where these values are read from before continuing.

## Code Stitching Guidance

When moving from signing code to create-order code:

- tell beginners to keep both parts in the same file first
- explain that the second snippet depends on values from the first snippet
- explicitly point out reused variables such as `body`, `date`, `digest`, and `authorization`

## Common Webhook Events

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

## Webhook Verification

Docs:

- Chinese auth doc: `https://developer.infini.money/docs/zh/4-authorization`
- English auth doc: `https://developer.infini.money/docs/en/4-authorization`
- Chinese webhook doc: `https://developer.infini.money/docs/zh/7-webhook`
- English webhook doc: `https://developer.infini.money/docs/en/7-webhook`

Important headers:

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

Verification string format:

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

Plain-language verification flow:

1. get the timestamp header
2. get the event id header
3. keep the raw request body unchanged
4. join them with dots
5. sign the result with `secret_key`
6. compare with the received signature header

## Guidance Style For Code

When providing code:

- ask for the user's language first
- match the explanation language to the user's language
- output only `Node.js` or only `Python`, never both in the same step unless the user asks
- prefer short runnable snippets over long framework-specific scaffolding
- explain where the user should place `key_id` and `secret_key` in plain language
- if webhook setup is discussed, explain it separately from the create-order body unless the current official docs explicitly connect them


path: references/troubleshooting.md
content: # Infini Troubleshooting

Use this file first when the user reports an error.

## Language-Aware Documentation

Choose the troubleshooting links in the same language as the user whenever possible.

## Official Links

- Chinese error code doc: `https://developer.infini.money/docs/zh/8-errorcodes`
- English error code doc: `https://developer.infini.money/docs/en/8-errorcodes`
- Chinese authentication doc: `https://developer.infini.money/docs/zh/4-authorization`
- English authentication doc: `https://developer.infini.money/docs/en/4-authorization`
- Chinese API doc: `https://developer.infini.money/docs/zh/6-api-ducumentation`
- English API doc: `https://developer.infini.money/docs/en/6-api-ducumentation`
- Chinese webhook doc: `https://developer.infini.money/docs/zh/7-webhook`
- English webhook doc: `https://developer.infini.money/docs/en/7-webhook`

## How To Diagnose

1. Identify the current step.
2. Check whether the issue matches one of the known cases below.
3. Give the known fix first if there is a match.
4. Only ask for extra details if the known cases do not solve it.

## Known Cases

### 40001 Invalid parameter

Meaning in simple words:

- one or more request fields are missing, empty, or formatted incorrectly

Check:

- required body fields are present
- amount and currency values are valid
- the request body matches the API example

### 40002 Invalid signature

Meaning in simple words:

- the server could not verify the signature

Check:

- `Date` header is present
- `Date` value is close to the current server time
- `Authorization` header format is correct
- `Digest` exists when the request has a body
- `secret_key` is correct
- the signed content matches the real request exactly
- the path in the signing string really matches `/v1/acquiring/order`

### 401 Unauthorized

Meaning in simple words:

- the API key is wrong, missing, disabled, or being used in the wrong environment

Check:

- sandbox keys are used with sandbox base URL
- production keys are used with production base URL
- `key_id` and `secret_key` were copied correctly

### 40901 Order not found

Meaning in simple words:

- the order ID does not exist in the current environment

Check:

- order ID is correct
- sandbox order is being queried in sandbox, not production

### 40902 Order status error

Meaning in simple words:

- the current order state does not allow the action being attempted

Check:

- whether the order is already completed, expired, or still processing

### 40906 Duplicate or repeated request case

Meaning in simple words:

- the same request may have been sent again with conflicting data

Check:

- whether the same merchant order number is being reused
- whether retries send the exact same payload

## Webhook-Specific Checks

If the webhook does not work:

- first test with `https://webhook.cool`
- confirm the webhook URL is publicly reachable
- confirm the callback handler reads the raw request body if signature verification depends on it
- confirm `X-Webhook-Timestamp`, `X-Webhook-Event-Id`, and `X-Webhook-Signature` are read correctly
- confirm the verification string uses `{timestamp}.{event_id}.{payload_body}`
- confirm the server clock is correct

## Sandbox Test Checks

If sandbox order creation works but the full flow does not:

- confirm the returned `checkout_url` opens correctly
- confirm the user completed the test payment, not just opened the page
- confirm the user has test tokens in the sandbox flow
- confirm the payment was actually completed in sandbox
- confirm your webhook endpoint received the callback
- confirm your backend updated the order after receiving a valid webhook


path: references/workflow.md
content: # 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


path: agents/openai.yaml
content: interface:
  display_name: "Infini API"
  short_description: "Guide Infini API and webhook integration."
  default_prompt: "Use $infini-api to guide me through Infini API integration step by step."


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)