Payment protocol reference

This reference describes payment protocol 1. Tringify selects the protocol for each declaration revision. Provider operations are HTTPS POST requests with JSON request and response bodies.

Read the raw request bytes before parsing them. Compute the lowercase hexadecimal HMAC-SHA256 of the timestamp, a period and the raw request bytes (<timestamp>.<raw body>) with the app's signing key, and compare it in constant time with each v1 value in the header; accept the request if any one of them matches. The key is used as the text shown in the Developer Portal, all 64 characters; do not hex-decode it. Check that t equals X-Tringify-Timestamp and reject a timestamp more than 5 minutes from your clock, in either direction, before creating provider state. This is the same check as for app webhooks.

With this signing key, timestamp and body, a correct verifier computes exactly this header. Use it as a test vector.

Today: immediate replacement. Generating a new key on the app's Webhooks page replaces the old one at once for every installation and every request Tringify signs. Provider calls and lifecycle events switch to the new key at once; other event deliveries follow within moments. Tringify stops signing with the old key immediately, so your verifier rejects every request until it has the new key. Rotate when traffic is low, and deploy the new key to your service immediately after generating it.

Coming: a 72-hour overlap. In a forthcoming change, Tringify will keep signing with the previous key for 72 hours after a rotation. During that time X-Tringify-Signature carries one v1 value per key, current first (t=<timestamp>,v1=<current>,v1=<previous>), so a service still holding either key keeps verifying while you deploy the new one. Until that change ships, rotation is the immediate replacement above.

Build your verifier for both now: accept a request when any v1 value in the header matches the signature you compute, and never assume the header has exactly one. A verifier that reads only the first v1, or rejects a header with more than one, will reject valid requests once the overlap ships.

A charge request is sent once. A refund request is repeated as described in Refund retries and deadlines.

Treat session and refund IDs as idempotency keys and reject a reused ID whose immutable request values changed. Return the original provider object for a repeated matching request. For a start-payment request, checkout must receive exactly one valid browser handoff before the customer can continue. When one provider object can contain several attempts, persist attempts separately and derive the Tringify session from the provider object's complete authoritative state. Reconcile uncertain and late results through the Store API. For a repeated refund request, return the latest state of the same provider refund instead of creating another refund. Use native provider idempotency with the same immutable refund ID; lookup followed by creation alone does not protect concurrent retries. A timeout or unavailable response is not proof of failure. Keep the refund pending and reconcile it until the provider confirms a terminal result. Preserve unresolved refund records across temporary disconnections. Validate provider-specific amount steps in addition to currency decimals, and never silently round a requested payment or refund.

Provider requests and Store API callbacks must not include card numbers, CVV or CVC values, cardholder data, wallet cryptograms, PINs, API keys, access tokens, or merchant credentials.