Payment protocol reference

The signed requests, responses, fields, and reliability rules for payment protocol 1.

This reference describes payment protocol 1. Tringify selects this version for new declarations. All provider endpoints receive JSON over HTTPS.

Signed request headers#

Header	Purpose
`X-Tringify-Signature`	Hex HMAC-SHA256 signature.
`X-Tringify-Timestamp`	Unix timestamp included in the signature.
`X-Tringify-Request-ID`	Unique identifier for this delivery attempt.
`X-Tringify-Store-ID`	Store that owns the connection.
`X-Tringify-App-ID`	App receiving the request.

Compute the expected signature as HMAC-SHA256 with your app signing secret over the timestamp string followed immediately by the exact raw request body. Compare signatures in constant time and reject stale timestamps before doing provider work.

Connection check request#

Field	Type	Required	Description
`binding_id`	string	Yes	Identifies the connected merchant account.
`store_id`	string	Yes	Identifies the store that owns the connection.
`app_id`	string	Yes	Identifies your app.
`service_type`	string	Yes	The requested provider service; `payment` for this contract.
`connection_key`	string	Yes	Your stable key for this merchant connection.
`declaration_revision_id`	string	Yes	The approved declaration this connection must follow.

Connection check response#

Field	Type	Required	Description
`status`	string	Yes	Whether the account is ready, needs merchant action, or cannot be used.
`status_reason_code`	string	No	Optional stable reason code supplied by your app.
`mode`	string	No	Whether the connected credentials are `test` or `live`.
`health`	string	No	Whether the ready account is healthy or temporarily degraded.
`account_country`	string	No	ISO country code for the connected provider account.
`account_hint`	string	No	Safe, masked text that helps the merchant recognize the account.
`operations`	array of string	No	Operations this account can perform now.
`presentment_currencies`	array of string	No	ISO currency codes this account can process now.

Start-payment request#

Field	Type	Required	Description
`session_id`	string	Yes	Tringify payment-session ID and idempotency key.
`protocol_version`	string	Yes	Payment protocol version for this request.
`declaration_revision_id`	string	Yes	Approved declaration revision that governs this request.
`store_id`	string	Yes	Store accepting the payment.
`market_id`	string	Yes	Market whose payment-provider assignment selected this connection.
`store_name`	string	No	Optional store name for the provider experience.
`order_id`	string	Yes	Order being paid.
`order_number`	string	No	Optional merchant-facing order number.
`amount`	string	Yes	Exact decimal amount as a string; never a floating-point number.
`currency_code`	string	Yes	ISO currency code for the amount.
`customer_email`	string	No	Customer email when available and needed for payment.
`customer_phone`	string	No	Customer phone when available and needed for payment.
`billing_address`	object	No	Normalized billing address when available and needed for payment.
`return_url`	string	Yes	Tringify URL to return to after the provider experience.
`cancel_url`	string	No	Optional Tringify URL used when the customer cancels.
`expires_at`	ISO 8601 timestamp	Yes	Time after which the payment session can no longer be completed.

Start-payment response#

Field	Type	Required	Description
`success`	boolean	Yes	Whether the provider payment was created or retrieved.
`launch_url`	string	No	Gateway-hosted HTTPS URL Tringify opens for the customer; mutually exclusive with browser_action.
`browser_action`	object	No	Reviewed browser adapter and public per-session configuration; mutually exclusive with launch_url.
`provider_session_id`	string	No	Optional provider-owned identifier for this attempt.
`error_code`	string	No	Stable, non-sensitive error code when the request is rejected.
`error_message`	string	No	Safe developer-facing detail when the request is rejected.

Refund request#

Field	Type	Required	Description
`refund_id`	string	Yes	Tringify refund ID and idempotency key.
`session_id`	string	Yes	Original Tringify payment-session ID.
`store_id`	string	Yes	Store requesting the refund.
`order_id`	string	Yes	Order being refunded.
`provider_transaction_id`	string	Yes	Provider transaction previously reported for the payment.
`amount`	string	Yes	Exact refund amount as a decimal string.
`currency_code`	string	Yes	ISO currency code for the refund amount.
`reason`	string	No	Optional merchant-provided reason for the refund.

Refund response#

Field	Type	Required	Description
`success`	boolean	Yes	Whether the refund request was accepted.
`provider_refund_id`	string	No	Optional provider-owned refund identifier.
`status`	string	No	Current result: `refunded`, `pending`, or `failed`.
`error_code`	string	No	Stable, non-sensitive error code when the request fails.
`error_message`	string	No	Safe developer-facing detail when the request fails.

Reliability rules#

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; an uncertain provider result after customer interaction is reconciled through the Store API. Refund and off-session operation timeouts remain ambiguous and must be queried before repeating money movement.

Sensitive data#

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.