# Trufill Payments

Hosted crypto checkout for merchants. Russian product and integration documentation.

- Product: https://payments.trufill.xyz/
- API documentation: https://payments.trufill.xyz/docs/
- OpenAPI: https://payments.trufill.xyz/openapi.json
- Pilot onboarding: https://payments.trufill.xyz/connect/
- Contact: hello@trufill.xyz

## Integration

1. Register the merchant webhook URL and HTTPS return origin with Trufill. Receive an API key and webhook secret for the pilot.
2. Create a payment server-side with POST /v1/payments, Authorization: Bearer <merchant-key>, Idempotency-Key (16–128 safe characters), Content-Type: application/json.
3. Body: {"amount":{"value":"10.00","currency":"USD"},"merchant_order_id":"order-123","description":"Hosting","return_url":"https://registered-shop.example/return"}.
4. Persist payment.id with the order, then redirect the buyer to confirmation.confirmation_url.
5. Verify payment.succeeded webhook signature against the exact raw body, then GET /v1/payments/:id with the same merchant key. Compare ID, order, amount, currency, test mode and succeeded status. Fulfill once transactionally.
6. Browser return is informational. It receives payment_id after success.

## Webhook signature

x-trufill-idempotency-key contains the event ID.
x-trufill-signature is t=<Unix seconds>,v1=<lowercase SHA-256 HMAC hex>.
HMAC input is timestamp + "." + event ID + "." + exact raw body, keyed by the merchant webhook secret. Verify timestamp within 300 seconds and compare digest in constant time. Deduplicate event/payment IDs and return 2xx after durable processing.

## Money and modes

Invoice currency is USD. amount.value is a decimal string with two places, default minimum 10.00 USD. Merchant processing fee is 0.5% of invoice amount. Buyer network recovery depends on network and is disclosed before payment. Wallet sending gas is separate. Server quote amounts can preserve up to six decimal places. Use the server amount without rounding.

Public demo uses POST /api/demo/payments with {} and has payment.test=true. Sandbox simulates approval without moving funds or providing real deposit addresses. Live activation is coordinated with Trufill, separate from sandbox. API keys and webhook secrets remain on the merchant server.