Connect a merchant account

Installation makes the reviewed payment app eligible for assignment. Tringify creates the app's payment binding during installation, in the same step that issues the installation token, so the binding already exists when app.installed reaches you. It is not offered at checkout until a connection check reports the account ready and the merchant enables the app's payment methods in a market. The app stores the merchant's provider credentials and uses its installation token only for Tringify Store API calls.

Call GET /api/2025-01/service-bindings?service_type=payment with the installation token. The response contains only bindings owned by the calling app. Use the binding ID and connection key to address the matching merchant configuration in your service.

After credential or account configuration is committed in your service, call POST /api/2025-01/service-bindings/{binding_id}/configuration-changed. Do not send readiness or currency claims in this request. Tringify calls the connection-check endpoint pinned to the installed declaration and validates its response.

Uninstalling a payment app first turns its payment methods off in every market, so no new checkout can select it, then checks the payments and refunds it still owns. Tringify refuses the uninstall while any of its payment sessions are pending, processing, or presented, or while any of its refunds are queued or pending (APP_UNINSTALL_PAYMENTS_IN_FLIGHT). A refused uninstall leaves the app installed with its token and scopes unchanged, so it can keep reporting results; the merchant retries once they finish and can switch the payment methods back on meanwhile. Only a clear check revokes the token and removes the bindings.

A session that ended failed, expired, or cancelled can still be captured by the provider later, and Tringify accepts that late paid result. So removal is also blocked for 7 days after the last activity of any such session, counted from the later of its last update and its expires_at. The merchant sees how many sessions are inside that window and when it ends (APP_UNINSTALL_PAYMENTS_SETTLEMENT_WINDOW). Keep reconciling those provider payments until the app is uninstalled.

Payment apps receive the same signed lifecycle events as every app, at the app's webhook URL. app.installed carries the installation's tpat_ Store API token, its scopes, and installation_id. app.token_rotated carries a replacement token, its scopes and rotated_at when the merchant approves an update that changes scopes or the store's token is rotated; the previous token stops working at once. It has no installation_id. app.uninstalled carries the installation_id of the removed installation; for a merchant's uninstall it is sent only after the uninstall preflight is clear, and when the store is deleted its reason is store_deleted. The token stops working.

Deliveries are retried and can arrive late, twice, or out of order. Process each event_id once. Key stored credentials by installation_id: a reinstall has a new one, so ignore an app.uninstalled whose installation_id is not the installation you hold, and never let it erase the newer installation's token or merchant configuration. Apply an app.token_rotated only if its rotated_at is later than when the token you hold was issued (its installed_at or rotated_at), and confirm the new token with a Store API call before discarding the old one. Keep the merchant's provider credentials until you receive the app.uninstalled for that installation: until then you still have to report late payments and refunds.

Verify the Tringify signature against the raw body, then load the merchant configuration identified by binding_id and connection_key.

Return ready only when the account can process the installed payment contract. Include the verified account mode, country, health, and complete presentment-currency set. Use requires_action for incomplete merchant configuration and error when the stored connection cannot be used. Operations come from the installed declaration and are not returned here.

Derive test or live from the verified provider account, not merchant-entered labels. Charges routed through a test binding carry test: true; Tringify records the resulting order as a test order.