Partner Payment Portal

This guide describes how integration partners can send payers from their own product into the Truss Payment Portal checkout, straight to a specific inbound payment intent (invoice), and optionally return them to the partner when checkout finishes.

For how companies configure and share the Payment Portal in general, see How does the Payment Portal work?. For creating and managing intents via API, see Payment intents.

What is the Payment Portal?

The Payment Portal is the Truss-hosted experience where a payer authenticates (email verification), sees the invoices they can pay for a given company, chooses a payment method, and completes payment. Each Truss company has a checkout link embedded in their portal URL path.

Integration partners usually need two pieces of information to build a payer-facing link:

• Checkout link ID — Identifier in the portal path (same ID that appears in the company’s standard Payment Portal URL as /pay/<checkout_link_id>/...). You can read it from the checkout_link_id field returned by Get company (GET /v1/company/).
• Payment intent UID — The uid of the inbound payment intent from the Payment Intent API resource (and the value you use elsewhere in API calls).

Use the payer-facing Payment Portal hosts below—they match the OAuth authorize origins documented in OAuth Integration Guide.

Deep link to a specific invoice

Use one of these base URLs:

Production:

https://app.trusspayments.com

Sandbox:

https://app.staging.trusspayments.com

Send the payer to:

Production:

GET https://app.trusspayments.com/pay/{checkout_link_id}/paymentIntent/{payment_intent_uid}

Sandbox:

GET https://app.staging.trusspayments.com/pay/{checkout_link_id}/paymentIntent/{payment_intent_uid}

Example (production, illustrative identifiers):

https://app.trusspayments.com/pay/a1b2c3d4/paymentIntent/3dba9d05-bb20-423e-924e-4b19e50d6f3c

The app immediately routes them into the invoice detail step for that UID (query parameters on this URL, such as redirect_uri, are preserved).

Email address

The payer must complete the portal’s email verification using an email address registered as the primary or secondary contact email on the payment intent (see Payment intents — Contacts). If they use a different email, they may not see or open the correct invoice after signing in.

Optional return URL (redirect_uri)

What it is for

If you pass a validated redirect_uri, the portal can send the payer back to your application after a successful invoice payment (primary action on the receipt step), or when certain error paths offer “Close this page” action that retaurns early. Your server or SPA can read the query parameters Truss appends and reconcile state in your product.

Query parameter

Append a single absolute HTTPS URL (fully qualified), URL-encoded as one query parameter:

?redirect_uri=https%3A%2F%2Fwww.google.com

You may combine it with the deep link routes above, for example (production):

https://app.trusspayments.com/pay/{checkout_link_id}/paymentIntent/{payment_intent_uid}?redirect_uri=https%3A%2F%2Fwww.google.com

When it is accepted

• The value must be a valid URL.
• For cross-origin callbacks, the origin and path must match an entry on Truss’s allowlist for the deployed web app (see below). Matching is exact for the pathname (no extra path segments): for example, if allowlisted as https://partner.example.com/oauth/truss/callback, then https://partner.example.com/oauth/truss/callback/extra will not match.
• Trailing slashes are normalized when comparing to the allowlist.

If redirect_uri is present but not allowed, the payer sees an invalid link error and cannot continue into checkout until they use a URL without redirect_uri, or with an allowlisted redirect_uri.

If you omit redirect_uri, after payment, the payer remains in the portal (default Done navigates back to the payer’s invoice list for that company).

Query parameters on redirect

When a browser redirect to your redirect_uri is performed, Truss sets these query parameters on your URL:

Any query string you already placed on your redirect_uri is preserved; Truss appends these parameters in addition to them.

result values (integration-relevant):

• success — Used when the payer completes an invoice (non–custom-amount) payment and confirms the primary completion action on the receipt step. This is the main “payment completed” signal for deep-linked invoice checkout.
• incomplete — Used when the payer is returned early from certain error/closure flows (for example, closing the page via the offered action when checkout cannot proceed as linked).

The fail value exists in the checkout implementation for symmetry; partner flows should not rely on seeing it until Truss documents a specific user-facing path that sets it. For robust reconciliation, combine result with webhooks and/or API polls on the payment intent and transactions.

Allowlisting redirect URIs

Cross-origin redirect_uri values must be allowlisted in Truss’s configuration for the Payment Portal web application. Contact Truss with the exact HTTPS URLs (scheme, host, and path) you need for sandbox and production.

Until a URI is allowlisted, do not ship it to end users—it will block checkout when supplied.

Practical checklist for partners

1. Obtain checkout link ID via Get company and use the correct portal base URL for the environment (https://app.trusspayments.com or https://app.staging.trusspayments.com).
2. Store the uid of each inbound payment intent you expose in your UX.
3. Build: https://app.trusspayments.com/pay/{checkout_link_id}/paymentIntent/{uid} or the sandbox hostname (+ optional encoded redirect_uri).
4. Ensure payers know which email to use for portal sign-in (same email the merchant notified).
5. Register and test every redirect_uri path with Truss before go-live.
6. On your return endpoint, parse payment_intent_uid and result; confirm payment state via API/webhooks rather than trusting success alone for financial reconciliation where your risk model requires it.