Embed Token Sandbox API enables developers to generate secure, temporary embed tokens for testing frontend integrations in the Swift Sandbox environment.

By sending a POST request to the /embed-token endpoint with a set of custom properties, authenticated applications can obtain a JWT-based embed token that can be used to securely authenticate and authorise access to embedded frontend components. The API returns the generated token along with its type and expiration information, allowing developers to simulate and validate embedded user experiences before deploying to production. Designed for secure token management, the API supports standard bearer authentication and provides clear error handling for invalid requests and server-side issues.

Use Case: Payment Tracking iFrame

A bank may choose to embed the Payment Tracking iFrame directly into its online banking portal to give retail customers real-time visibility into the status of their cross-border payments without leaving the bank's digital channels. Instead of building and maintaining a dedicated payment tracking interface, the bank can integrate the iFrame into its existing payment details or transaction history pages, where customers can securely view the latest payment status, timestamps, and any exceptions or delays. This seamless integration provides a consistent user experience, reduces development effort, and enables the bank to offer enhanced payment transparency while leveraging the tracking capabilities provided by the GPI Tracker.

Before You Begin

Before integrating the Payment Tracking iFrame, ensure that you have an app created with access to Tracker Frontend API.

Step 1: Authenticate your application

Your online banking portal should first authenticate with the Tracker Frontend API using the OAuth 2.0 Password flow. For sandbox, you can use dedicated sandbox credentials for this flow. The authentication request is performed application-to-application.

Step 2: Create an iFrame Session

Once authenticated, use the access token to create a secure viewing session for a specific payment with its unique identifier such as the UETR. Refer to the Embed Token Sandbox API Reference for detailed API specification.

You can view, fork or download the Postman collection which includes Embed Token Sandbox API calls. Also refer to access sandbox where dedicated sandbox credentials are provided.

Example Request

Example Response

The returned embed token is short-lived and should only be used for the current customer session.

Step 3: Generate the iFrame URL

Construct the iFrame URL using the URL or session information returned by the API.

Example (sandbox)

Do not manually construct additional parameters unless documented by the API.

Step 4: Embed the iFrame

Add the iFrame to the desired location within your banking portal, such as:

• Payment Details page
• Transaction History
• Payment Confirmation page
• Customer Service portal

The embedded experience provides customers with payment status updates without navigating away from your portal.

Step 5: Secure the Integration

To protect customer information, implement the following security best practices.

• Server-side authentication, perform OAuth authentication exclusively on your backend.

• HTTPS, use HTTPS for all requests and for the page hosting the iFrame.

• Content Security Policy, configure your Content Security Policy (CSP) to allow the Payment Tracking domain.

Step 6: Token Management

• Do not cache expired session tokens.
• Generate a new session whenever a customer starts viewing a payment.

Example UETRs

After successfully integrated using the UETR provided in the example in Step 2, try the following UETRs to see how the metro map would look like for other payment statuses.