logo
Trustly Docs
BETA
Integration guide for E-commerce

How to get started with Recurring payments for E-commerce

Provide Trustly as a payment method to customers in your checkout process.

Common scenarios

Trustly's payment integrations cover the following scenarios:

  • Accept one-time payments

  • Accept recurring payments (only available in Sweden at the moment)

  • Let customers Pay by invoice.

  • Let customers Pay by link.

  • Provide a Refund.

Common functions

API methods and notifications to implement in your e-commerce system are shown in the following table:

API method/notificationFunctionPurpose
DepositPaymentLets a customer make a one-time payment from their bank account.
RefundRefundRefunds a previous Deposit.
SelectAccountRecurring paymentLets a customer register a direct debit mandate.
ChargeRecurring paymentTo charge a customer’s bank account that has an active direct debit mandate.
CancelChargeRecurring paymentCancels a Charge transaction with a future payment date.
Pending notificationNotificationTo notify you when the user has completed all the steps in the Trustly checkout (Deposit and SelectAccount) or when a Charge request has been received.
Cancel notificationNotificationTo notify you when a Deposit, SelectAccount or Charge order has been canceled.
Credit notificationNotificationTo notify you when a Deposit or Charge has been confirmed.
Debit notificationNotificationTo notify you that a Deposit has failed, even though a credit notification has already been sent.
Account notificationNotification (Optional)To let you know the status of a direct debit mandate (active or inactive). Can also be sent for Deposits to provide additional information about the bank account that was used by the customer.

Accept recurring payments

Build integration for customers to register mandate and make recurring payments with Trustly

Before you start

  • Make sure that you have completed Sign up and received a Trustly test account.

  • If you have a native app implementation, integrate Trustly SDKs.

Recurring payment flow

Accepting recurring payments require you to make mandate registration and provide payment methods.

Mandate registration

A mandate means that a customer authorises you to access their bank account.

To provide Trustly as a payment method for recurring payment, you need to register a mandate and get customers' approval before accepting payments.

You can register a mandate with Trustly in these ways:

If you want to let customers approve a mandate for future payments

Register mandate using SelectAccount. Send a SelectAccount call with attribute "RequestDirectDebitMandate" : "1".


If you want to let customers make a one-time payment and approve the mandate for future payments at the same time

Send a Deposit call with attribute "RequestDirectDebitMandate" : "1".


Charge flow


In a typical Charge flow:

  1. Your system sends an API call to Charge.

  2. Trustly starts to process the payment with the customer's bank account that they have authorised access.

    • If the payment is processed successfully, Trustly will send a Credit notification to your system on the following bank day. Note that cut-off time is 18.48 CET on bank days.

    • If the payment is not processed successfully but you have requested Trustly to configure retries, Trustly will retry up to three times. Trustly will send a Credit notification for processing the payment successfully. Otherwise, Trustly will send a Cancel notification, once all retries have been attempted.

    • If the payment is not processed successfully and retries are not configured, Trustly will send a Cancel notification to your system.

  3. Your system responds to the received notifications.

Step 1: Integrate your system with Trustly

Develop business logic according to the charge flow.

  1. Make sure that your integration follows security requirements. See Security.

  2. Register the mandate for a customer.

    • If you only want to register the mandate without accepting payments, send a call to SelectAccount with attribute"RequestDirectDebitMandate" : "1".

    • If you want to register the mandate when accepting a one-time payment, send a call to Deposit with attribute "RequestDirectDebitMandate" : "1".

  3. If the mandate registration is successful, Trustly will send an Account notification with attribute "directdebitmandate": "1" to your system.

    1. If the mandate registration fails, Trustly will send an Account notification with attribute "directdebitmandate": "0" to your system.


      Note: The payment transaction made by a Deposit call will not be affected.

  4. When it is the scheduled time to charge the customer as per their agreement with you, your system calls Charge.

  5. If you send a Charge call with a future pay date, you can cancel this scheduled charge with a call to CancelCharge, up to the day before the scheduled pay date.

  6. Mandate management:

    • You can remove access to the mandate in Trustly Back Office.

    • When a mandate is revoked, Trustly will send an Account notification with attribute "directdebitmandate": "0" to your system.


      Note: Your customers can revoke the mandate manually through their internet bank.

  7. Make sure that your integration logs and handles error codes that are returned from API calls. See Error handling.

  8. Make sure that your integration responds correctly to Trustly notifications.

Step 2: Design service presentation

When your integration presents a Trustly URL to customers, the presentation must follow Trustly checkout guidelines.

Step 3: Do acceptance testing

Prior to going live, the Trustly Integration Specialist will perform Acceptance testing. Make sure your integration has passed all test cases, including:

  • Mandate registration

  • Charge API calls

  • CancelCharge API calls, if you are sending future pay date

  • Mandate cancellation via Trustly Back Office

  • Built-in test cases of acceptance testing: D1 to D5, DD1 to DD3, and G1 to G3

  • Verify that your app has correct responses to notifications. See Notification tool.

Step 4: Verify and go live

Follow the instructions to go live.

Refund

Build integration to refund customers with Trustly

Before you start

  • Make sure that you have completed Sign up and received a Trustly test account.

  • If you have a native app implementation, integrate Trustly SDKs.

Refund flow

In a typical Refund flow:

  1. Your system sends an API call to Refund.

  2. Trustly responds with "result" : "1" to acknowledge the call is received.

  3. Trustly checks whether the funds have been settled.

    • If the funds are not settled, Trustly will process the refund request when the funds are settled.

    • If the funds are settled, Trustly will process the refund request.

  4. Trustly sends a Payout confirmation when the funds are successfully sent from Trustly.

    Note: The Payout confirmation is not enabled by default. Contact Trustly Integration Support, if you need it.

  5. If the refund fails, Trustly will send a Credit notification.

  6. Your system responds to the received notifications.

Step 1: Integrate your system with Trustly

Develop business logic according to the charge flow.

  1. Make sure that your integration follows security requirements. See Security.

  2. Make sure that you have sufficient funds in your Trustly account. You can schedule API call to Balance to ensure that your balance is sufficient.

  3. When a customer requests a refund, you system sends a call to Refund.

  4. Make sure that your integration logs and handles error codes that are returned from API calls. See Error handling.

  5. Make sure that your integration responds correctly to Trustly notifications.

Step 2: Do acceptance testing

Prior to going live, the Trustly Integration Specialist will perform Acceptance testing. Make sure your integration has passed all test cases, including:

  • Refund API calls, both full and partial

  • Verify that your integration has the correct responses to notifications. See Notification tool.

Step 3: Verify and go live

Follow the instructions to go live.