Partner integration

The official journey is:

Partner backend
→ B2B SDK
→ B2B API

The Partner's application talks to its own backend. That backend uses the official SDK to authenticate, create resources, request operations and query results.

At the infrastructure level, the connection depends on the environment:

• in sandbox or integration, the Partner backend consumes a test HTTPS endpoint, with credentials, data and resources scoped to that environment;
• in a future self-hosted real deployment, the B2B API, workers, observers, the webhook dispatcher and the Partner Signer Gateway are deployed inside the cloud project controlled by the Partner;
• the Partner backend reaches the B2B API through an HTTPS endpoint published and protected by its own infrastructure, typically behind a Load Balancer and a WAF;
• when both systems share a network controlled by the Partner, the endpoint can stay private; when the connection crosses different networks, the deployment defines TLS, optional mTLS, origin restrictions and access controls;
• OAuth authenticates the backend at the application layer regardless of whether the network connection is private or public;
• the webhook dispatcher needs HTTPS connectivity to the Partner's receiving endpoint to deliver signed events and run retries;
• workers need controlled egress to blockchain RPCs, LI.FI and the other providers enabled by the deployment.

The target journey for a real deployment is:

Partner app
→ Partner backend
→ private or protected HTTPS endpoint
→ Load Balancer / WAF
→ B2B API
→ workers and providers

Webhook Dispatcher
→ Partner HTTPS endpoint
→ Partner backend

Operation Worker
→ internal Partner Signer Gateway
→ software signer, HSM or MPC

ChatterPay delivers versioned images, contracts, manifests and infrastructure as code. The Partner imports those artifacts, configures networks and secrets, deploys the services in its environment and controls promotion to the real environment it approves.

The API defines the HTTP contract. The SDK saves each Partner from having to implement authentication, idempotency, type serialization, error handling, polling, event cursors and webhook verification on its own.

The SDK simplifies integration, but it does not replace the API. The API remains the contractual source.

Both channels use the same financial logic.

In Partner-first, the user starts the operation in the Partner's application and the backend uses the SDK.

In WhatsApp-first, the conversational channel gathers the data and requests the operation from the B2B API.

The platform applies the same identity, fee, limit, authorization, execution and reconciliation rules regardless of the channel.

The Partner normally keeps:

• the contractual relationship with the user;
• end-user authentication;
• KYC, AML and regulatory monitoring;
• commercial approval of the operation;
• control of the real deployment's cryptographic material;
• gas funds and treasury;
• operating its real environment when applicable.

ChatterPay provides:

• API and SDK: HTTP contracts, libraries and utilities to integrate authentication, idempotency, operations and webhooks;
• users and wallets model: resources to relate the Partner's identity to logical wallets and per-network accounts;
• operation orchestration: the durable lifecycle of transfers and swaps, from the quote and authorization through execution and final result;
• network and provider integration: adapters to prepare, submit and observe operations on each blockchain or external provider;
• technical validations: authentication and tenant checks, idempotency, network, asset, amount, destination, quote validity, balance or reservation, enabled policies and consistency of the payload being signed;
• operational ledger: an append-only record of internal movements and adjustments, including requested, reserved, sent and received amounts, fees, gas, refunds and compensations;
• reconciliation: comparing the requested operation, the operational ledger and blockchain/provider evidence to confirm the result and detect differences;
• events and webhooks: durable internal events and signed webhooks that communicate state changes and results to internal components and to the Partner;
• deployment and operation artifacts: versioned images, Helm charts, manifests, contracts, infrastructure modules and runbooks.

For a real backend-to-backend deployment, authentication uses OAuth 2.0 Client Credentials with the private_key_jwt method, and it is implemented.

During integration onboarding, the Partner registers a client_id and the public key ChatterPay will use to verify its identity. The corresponding private key stays in the Partner's backend or secure system.

To authenticate, the Partner backend:

1. builds a short-lived JWT called a client assertion;
2. includes its client_id, the token endpoint as audience, a short expiration and a unique identifier;
3. signs that JWT with the private key associated with its OAuth client;
4. sends the signed assertion to the token endpoint;
5. receives a short-lived access token after the platform verifies the signature with the registered public key.

The key used in private_key_jwt identifies the Partner's backend. It is independent from the blockchain keys the Partner Signer Gateway uses to authorize wallet operations.

mTLS can be added when the deployment requires certificate-bound authentication. The sandbox can use a client secret stored only in its BFF.