On this page
Prepare your KYC integration with an agent
Choose a language and copy the instructions below into your development agent. The context includes public guides, complete examples and the contract reference. Prepare with synthetic data; the example .invalid base is not an execution environment.
Integration prompt and context
Instructions for your agent
Implement a Contrato.Cloud KYC backend integration in TypeScript / Node.js, using only the public documentation linked below.
1. Read the context and OpenAPI before writing code. Cite the pages used; ask for clarification when a field or behavior is undocumented. Do not invent a SIGN signature API, Admin routes or private Portal endpoints.
2. Use https://api.example.invalid as a synthetic base URL. Before any real execution, request the authorized environment base and load X-API-Key only from backend environment variables. Never put keys in the frontend, prompt, URL, logs or repository.
3. Create transactions with POST /v1/face-auth/transactions and a stable Idempotency-Key per logical operation. Persist transaction_id and external_id. Redirect the person using the returned links.webview_url; do not construct the journey URL.
4. Read GET /v1/face-auth/transactions/{transaction_id}. Handle status, decision and decision_reason together. pending and intermediate steps remain pending; manual_review_pending waits for review; approved requires decision=approved; rejected requires rejection handling; expired ends or restarts according to policy. Expiration does not imply decision=rejected.
5. Preserve exact raw body bytes in the webhook receiver. Validate X-Face-Auth-Timestamp and X-Face-Auth-Signature (sha256=<hex>) using HMAC SHA-256 over timestamp + '.' + raw_body, constant-time comparison and a time window. Only then parse JSON and validate the envelope.
6. Deduplicate event_id in durable storage, match the header event identifier to the body, and make business effects idempotent. Reconcile out-of-order events and missed deliveries by reading the current transaction; never downgrade a newer decision using an older event.
7. Deliver configuration, error handling, synthetic fixture tests and execution instructions. Cover approval, rejection, pending, expiration, manual review, duplicates, altered body, Unicode and stale timestamp. Do not execute real API calls or process personal data without explicit authorization.
8. cURL covers HTTP only. If cURL is preferred, use a supported backend language for the receiver/HMAC and explain the choice. The MCP below only reads public documentation: it does not create transactions, sign documents or charge.
Context: https://contrato.cloud/downloads/ai/en/context.md
OpenAPI: https://contrato.cloud/downloads/kyc/openapi.json
Index: https://contrato.cloud/llms.txt
MCP (Streamable HTTP): https://contrato.cloud/api/mcp
MCP prompt: integrate_kyc (locale=en, language=typescript)
MCP tools: search_docs, read_doc, get_example
Content revision: ab4c5635b7f0f446ba6cfcf3607f9fb94636e233074478aed2ea1a9c23f83ead
Connect the documentation with MCP
Add this URL as a remote MCP server in your agent, using Streamable HTTP. The documentation is public and requires no key or OAuth.
https://contrato.cloud/api/mcpList tools, resources and prompts. Use search_docs to find guides, read_doc to read Markdown and get_example for a code variant. Select the integrate_kyc prompt with your locale and language.
Example configuration for clients supporting mcpServers/url
{
"mcpServers": {
"contrato-docs": {
"url": "https://contrato.cloud/api/mcp"
}
}
}This MCP reads public KYC documentation. Transaction execution and credentials belong in your backend.
Validate before execution
Review the generated code, configure the authorized base in your backend, and test idempotency, HMAC, reconciliation, expiration and manual review. Read the production checklist. AI documentation and MCP do not receive KYC keys or customer data.