Accept Instant Payments

Trustly Instant Payments is a legacy workflow for processing one-time transfers. Unlike our modern flows, this one authorizes and captures funds in a single synchronous step without generating a reusable credential token. The “Instant” designation applies to the single-phase authorization workflow; it doesn’t guarantee immediate settlement through the Real-Time Payments (RTP) network.

Limitations

Before implementing the Instant Payments workflow, consider the following limitations:

• No Tokenization: You cannot save the user’s bank details. The user must log in and authorize every single transaction, which adds friction for returning customers.
• No Recurring Payments: You cannot use this flow for subscriptions or future “one-click” deposits.
• Risk and Acceptance: This legacy flow does not utilize the latest risk optimization models available in Trustly Pay.

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.

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

Initialize the payment

Modify the integrated SDK Trustly.establish() method in your frontend application 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 on your backend to secure the payload. Do not generate this on the frontend or you will expose your Access Key. Pass the generated string to your frontend for this call. See Generate request signatures.

Example SDK call

1
/* Define the transaction parameters */
2
var establishData = {
3
  accessId: 'YOUR_ACCESS_ID',
4
  merchantId: 'YOUR_MERCHANT_ID',
5
  description: 'Order #12345 - Sneakers',
6
  currency: 'USD',
7
  amount: '100.00',
8
  merchantReference: 'order_12345',
9
  paymentType: 'Instant', // Triggers immediate funds capture
10
  requestSignature: 'GENERATED_SIGNATURE', // Critical for security
11
  returnUrl: 'https://merchant.com/checkout/success',
12
  cancelUrl: 'https://merchant.com/checkout/cancel'
13
};
14
15
/* Open the Trustly Lightbox */
16
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

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.

Use the webhook payload to confirm the final transaction status. Look for the following statuses:

• 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.

• Test your integration: See Test your integration.
• Schedule Certification: Before moving to production, you’re required to complete a formal integration certification with the Trustly team. Contact your integration manager to schedule your review.