Accept Instant Payments

Trustly Instant Payments allow you to accept one-time payments directly from a user's bank account. The funds are authorized and captured in a single step, making this workflow ideal for e-commerce, digital goods, and guest checkout experiences.

Compare Instant Payments and Trustly Pay

Use Instant Payments if...	Use Trustly Pay if...
You need a one-time checkout payment.	You need recurring deposits or withdrawals.
You charge a fixed amount immediately.	You want to store an authorization for reuse.
You sell a single good or service.	You operate a wallet or gaming balance.

Prerequisites

Client-side SDK: You must integrate the JavaScript SDK (Web) or Mobile SDK to launch the Trustly UI. See Integrate the Client-Side SDK.
Sandbox credentials: You need your accessId and accessKey. Contact Trustly Support if you do not have them.
Legal agreement: Ensure your non-disclosure agreement (NDA) and commercial agreements are signed.

Payment workflow

The following diagram illustrates the single-phase lifecycle of an Instant Payment. The user authorizes the transfer, and the funds are authorized and captured immediately.

sequenceDiagram
  participant User
  participant Client as Merchant Frontend
  participant Server as Merchant Backend
  participant Trustly

  Note over User, Trustly: Single Phase: Auth & Transfer
  User->>Client: A
  Client->>Trustly: B
  Trustly-->>User: C
  User->>Trustly: D
  Trustly-->>Client: E
  Client->>Server: F
  Trustly-)Server: G

The following table details each step of the instant payment workflow, corresponding to the lettered annotations in the diagram.

Workflow Step	Action	Description
A	User initiates payment	The user clicks a button, such as Pay Now, on your frontend application.
B	Client calls Establish	Your frontend calls `Trustly.establish` with `paymentType="Instant"`.
C	Trustly launches UI	Trustly presents the Trustly Lightbox to the user.
D	User authorizes	The user logs into their bank through the Trustly Lightbox and confirms the transfer immediately.
E	Redirect to `returnUrl`	Trustly redirects the user back to the `returnUrl` specified in your establish data.
F	Client verifies ID	Your frontend passes the `transactionId` (from the URL) to your backend for verification.
G	Webhook confirmation	Trustly sends an asynchronous webhook notification (usually `Completed`) to your backend confirming the funds are processing.

Important: Although Instant Payments authorize and capture funds in a single step, settlement confirmation is still asynchronous. Always wait for the webhook before fulfilling irreversible actions, such as shipping goods.

Initialize the payment

Modify the integrated SDK Trustly.establish() method to include the following parameters for a one-time payment:

paymentType: Must be set to 'Instant'. If you copied the example from the Integrate the client-side SDK topic, you'll need to change this value from 'Deferred' to 'Instant' to capture funds immediately.
amount: The exact amount to charge the customer. For example, '100.00'.
merchantReference: Your unique order ID or session reference.
requestSignature: You must generate a signature to secure the payload and prevent tampering. See Generate request signatures.

Example SDK call

/* Define the transaction parameters */
var establishData = {
  accessId: 'YOUR_ACCESS_ID',
  merchantId: 'YOUR_MERCHANT_ID',
  description: 'Order #12345 - Sneakers',
  currency: 'USD',
  amount: '100.00',
  merchantReference: 'order_12345',
  paymentType: 'Instant', // Triggers immediate funds capture
  requestSignature: 'GENERATED_SIGNATURE', // Critical for security
  returnUrl: 'https://merchant.com/checkout/success',
  cancelUrl: 'https://merchant.com/checkout/cancel'
};

/* Open the Trustly Lightbox */
Trustly.establish(establishData, TrustlyOptions);

To configure TrustlyOptions, see Integrate the Client-Side SDK.

Handle the redirect

Once the customer completes the payment at their bank, Trustly closes the Lightbox and redirects the customer to your returnUrl.

Trustly appends the transaction result to the URL parameters. You must parse these parameters to verify the outcome.

Example Return URL: https://merchant.com/checkout/success?transactionId=1002633191&status=2

Return parameters

Parameter	String	Description
`transactionId`	String	The unique Trustly ID for this payment. For example, 1002633191.
`status`	Integer	The final status of the customer's interaction.

Status verification

Check the status parameter immediately to show the correct page to your customer. The following are the status codes that are returned:

2 (Authorized): Success. The customer approved the payment. You can display your thank you page and rely on the webhook for final confirmation.
7 (Canceled or Declined): The customer cancelled the transaction, or the bank declined the transaction. Redirect them back to the checkout page to try again.

Event notifications

Trustly relies on webhooks to confirm the final status of a payment. You must configure a webhook listener to receive these updates. This ensures your database remains synchronized with the Trustly system, even if a customer closes their browser before the redirect completes.

Key events for Instant Payments include:

COMPLETED: Confirms the funds have been successfully collected.
FAILED: Confirms the payment was declined or reversed.

See Handle webhooks.

Refunds

To refund a completed Instant Payment, use the Refund API. See Refund transaction.

Refunds are processed asynchronously. You must wait for the webhook to confirm completion.

Next steps

Once you've implemented the payment flow, you must verify that your application handles success and error states correctly. See Test your integration.