--- title: "Trustly" canonical_url: https://docs.connect.worldline-solutions.com/payment-product/trustly/integration --- * [Overview](https://docs.connect.worldline-solutions.com/payment-product/trustly/overview/globalcollect.md) * [Countries \& currencies](https://docs.connect.worldline-solutions.com/payment-product/trustly/countries-and-currencies/globalcollect.md) * [Integration](https://docs.connect.worldline-solutions.com/payment-product/trustly/integration/globalcollect.md) * [Process flows](https://docs.connect.worldline-solutions.com/payment-product/trustly/process-flows/globalcollect.md) * [Testing](https://docs.connect.worldline-solutions.com/payment-product/trustly/testing/globalcollect.md) * [Additional information](https://docs.connect.worldline-solutions.com/payment-product/trustly/additional-information/globalcollect.md) * [Consumer experience](https://docs.connect.worldline-solutions.com/payment-product/trustly/consumer-experience/globalcollect.md) * [Reporting](https://docs.connect.worldline-solutions.com/payment-product/trustly/reporting/globalcollect.md) * [FAQ](https://docs.connect.worldline-solutions.com/payment-product/trustly/faqs/globalcollect.md) # Integration * [Using MyCheckout hosted payment pages](https://docs.connect.worldline-solutions.com/payment-product/trustly/integration.md#mycheckout) * [Using your own checkout page](https://docs.connect.worldline-solutions.com/payment-product/trustly/integration.md#your-checkout-page) * [consumer redirection](https://docs.connect.worldline-solutions.com/payment-product/trustly/integration.md#customer-redirection) * [Cancellations](https://docs.connect.worldline-solutions.com/payment-product/trustly/integration.md#cancellations) * [Refund](https://docs.connect.worldline-solutions.com/payment-product/trustly/integration.md#refund) ## Before you begin To follow along with this guide, please ensure that you have the following ready: * The correct [API endpoint](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/json/endpoints.html?paymentPlatform=ALL) * A way to construct the [authorization header](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/json/authentication.html?paymentPlatform=ALL) (API Explorer, [SDKs](https://docs.connect.worldline-solutions.com/documentation/sdk/.md), etc.) * A way to send REST API calls (API Explorer, [SDKs](https://docs.connect.worldline-solutions.com/documentation/sdk/.md), etc.) ## Using MyCheckout hosted payment pages If you're looking for the quickest way to accept Trustly payments, our [MyCheckout hosted payment pages](https://epayments.developer-ingenico.com/documentation/hosted-payment-pages/) is the optimal solution. By using this product, you'll be able to smoothly process payments and provide your consumers with a convenient, hassle-free payment experience. To initiate the desired action, execute **POST /v1/{merchantId}/hostedcheckouts**API call. This request enables you to interact with the hosted checkouts functionality, allowing seamless integration and customization for an enhanced user experience. The minimum required data set for this request body includes two objects: **order** and **hostedCheckoutSpecificInput** . For this type of request, it is crucial to specify **order.customer.merchantCustomerId.** Here is an example of the request with the minimum data set: | Property | Optional | Description | |-----------------------------------|----------|--------------------------------------------------------------------------| | order | Required | | hostedCheckoutSpecificInput | Required | | order.customer.merchantCustomerId | Required | The minimum required data set for this request body includes two objects | Below, you'll find an example API call with the essential data. To add more information with additional properties, please visit to our [API Reference](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/hostedcheckouts/create.html?paymentPlatform=ALL). | Property | Data type | Required | |-----------------------------|-----------|----------| | order | object | yes | | amountOfMoney | object | yes | | currencyCode | string | yes | | amount | integer | yes | | customer | object | yes | | merchantCustomerId | string | yes | | billdingAddress | object | yes | | countryCode | string | yes | | hostedCheckoutSpecificInput | object | no | | locale | string | no | | variant | string | no | The below example allows the consumer to select a payment product on our hosted payment page and be redirected to the next page, where they select the bank with which they want to pay. CREATE A HOSTEDCHECKOUTCopy code ```hljs javascript language-javascript { "order": { "amountOfMoney": { "currencyCode": "EUR", "amount": "100" }, "customer": { "merchantCustomerId": "1234", "billingAddress": { "countryCode": "NL" } }, "hostedCheckoutSpecificInput": { "variant": "testVariant", "locale": "en_GB" } } ``` CREATE HOSTEDCHECKOUT RESPONSECopy code ```hljs javascript language-javascript { "RETURNMAC" : "8b86bada-ebf8-4ad2-ac64-e5956a141690", "hostedCheckoutId" : "06571c62-b6e1-71ff-900d-dda9bb899e64", "merchantReference" : "references", "partialRedirectUrl" : "pay2.preprod.checkout.worldline-solutions.com/checkout/9991-faa4d336e2384de3bde7ce62beb3f127:065e9dd7-b56e-71ff-8ded-48133a47970b:2dc35d06fa7a43c19b22cca466a50cdd" } ``` From the response, the important properties are: * hostedCheckoutId -- can be used in subsequent API calls to retrieve the transaction details, such as [GET/v1/{merchantId}/hostedcheckouts/{hostedCheckoutId}](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/hostedcheckouts/get.html?paymentPlatform=ALL) * partialRedirectUrl -- is used to create the URL to which the consumer needs to be redirected. By default, we configure every account with the subdomain payment, so you can always connect https://payment. with the partialRedirectUrl, for example: https://payment.pay1.preprod.checkout.worldline-solutions.com/checkout/9991-0fb6755f00ac4064b85ca105bde20d0a:06605658-14a6-71ff-93d1-f43298dbb339:06d234ee7dae4930ba4c6331ac231aa3 For more information on customizing the MyCheckout hosted payment pages, please [refer to our detailed guide](https://docs.connect.worldline-solutions.com/documentation/hosted-payment-pages/.md). The hostedCheckoutId is only valid for 2 hours, please ensure to store the createdPaymentOutput.payment.id from the [GET /v1/{merchantId}/hostedcheckouts/{hostedCheckoutId}](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/hostedcheckouts/get.html?paymentPlatform=ALL) response to be able to retrieve data after 2 hours have elapsed via the [GET /v1/{merchantId}/payments/{paymentId}](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/json/payments/get.html?paymentPlatform=ALL) API call. Alternatively, we can also optionally send a [webhook event](https://docs.connect.worldline-solutions.com/documentation/webhooks/.md) that will contain it. To selectively showcase specific products, you can simply enhance the **hostedCheckoutSpecificInput** by adding a paymentProductFiltersobject. This object should include a restrictTo object with either groupsor **products** array properties. This straightforward update enables you to fine-tune the display, ensuring that only the desired products are presented to users, thereby enhancing the precision and relevance of your showcased offerings. To exclude specific products from the list, modify the hostedCheckoutSpecificInput by introducing a paymentProductFilters object. Within this object, include an exclude object with either **groups** or **products**array properties. This adjustment empowers you to tailor the displayed products precisely, ensuring that undesired items are omitted from the list, thus providing a more refined and customized user experience. Create a hostedcheckout - payment product filter CREATE A HOSTED CHECKOUTCopy code ```hljs javascript language-javascript { "order": { "amountOfMoney": { "currencyCode": "EUR", "amount": "100" }, "customer": { "merchantCustomerId": "1234", "billingAddress": { "countryCode": "NL" }, "contactDetails": { "emailAddress": "test@test.com" } }, "references": { "merchantReference": "references" } }, "hostedCheckoutSpecificInput": { "paymentProductFilters": { "restrictTo": { "products": [806] } }, "variant": "testVariant", "locale": "en_GB" } } ``` ## Using your own checkout page You can build the integration using our [SDKs](https://docs.connect.worldline-solutions.com/documentation/sdk/index.md) (or integrate our API from scratch). Depending on your integration needs, there are several options available. ## Client encryption Our [Client API](https://apireference.connect.worldline-solutions.com/c2sapi/v1/en_US/index.html?paymentPlatform=ALL) allows you to perform various actions. All you need is to be able to create a session via the [POST/v1/{merchantId}/sessions](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/json/sessions/create.html?paymentPlatform=ALL) API call, which will grant you access to the Client API. It's highly recommended that you use our [Client SDKs](https://docs.connect.worldline-solutions.com/documentation/sdk/mobile/.md), provided for the following programming languages: * [JavaScript](https://docs.connect.worldline-solutions.com/documentation/sdk/mobile/javascript/.md) * [Java](https://docs.connect.worldline-solutions.com/documentation/sdk/mobile/android/.md) * [Swift](https://docs.connect.worldline-solutions.com/documentation/sdk/mobile/swift/.md) * [Objective-C](https://docs.connect.worldline-solutions.com/documentation/sdk/mobile/ios/.md) We also have reference implementations showing how to use these SDKs on [GitHub](https://github.com/Ingenico-ePayments). ## Non-encrypted data If you wish to do a direct server-to-server API call, go for this option. The difference with the other options mentioned before is that you don't need to submit the encryptedCustomerInputproperty. By using this integration type, you'll be able to smoothly process payments and provide your consumers with a convenient, hassle-free payment experience. To initiate the desired action, execute **POST /v1/{merchantId}/payments**API call. For this type of request, a minimal set of data is required. In the order object, it is essential to specify the customer.merchantCustomerId parameter. In the redirectPaymentMethodSpecificInput object, the paymentProductId must be indicated, and for this product, the value will always be 806. In the paymentProduct806SpecificInput object, the integrationType needs to be specified. Additionally, in the redirectionData object, the returnUrl should be provided as the link to redirect the user after completing the payment. Below, you'll find an example of the request body containing not only the minimal required data set. For a comprehensive understanding of API requests, you can refer to this link and supplement the request body with any additional necessary information. CREATE PAYMENT REQUESTCopy code ```hljs javascript language-javascript { "order": { "amountOfMoney": { "currencyCode": "EUR", "amount": "100" }, "customer": { "merchantCustomerId": "1234", "personalInformation": { "name": { "firstName": "Johan", "surname": "Cruijff" } }, "billingAddress": { "countryCode": "NL" }, "contactDetails": { "emailAddress": "test@test.com" } } }, "redirectPaymentMethodSpecificInput": { "paymentProductId": "806", "paymentProduct806SpecificInput": { "integrationType": "link" }, "redirectionData": { "returnUrl": "https://www.example.com" } } } ``` ## Consumer redirection If you use [POST /v1/{merchantId}/payments](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/json/payments/create.html?paymentPlatform=ALL) API call, you also need to take care of the consumer redirection (in the case of [POST /v1/{merchantId}/hostedcheckouts](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/hostedcheckouts/create.html?paymentPlatform=ALL), we handle it ourselves). We'll return a merchantAction object. While there are several different actionType values, for Trustly transactions, we consistently return the actionType value as REDIRECT. Along with this, a redirectData object is included, containing a redirectURL. You'll need to direct your consumer to this URL to complete their payment. Be aware that the merchantAction is only returned in the response to [POST /v1/{merchantId}/payments](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/json/payments/create.html?paymentPlatform=ALL) and looks like this: CREATE PAYMENT RESPONSECopy code ```hljs javascript language-javascript { "creationOutput" : { "additionalReference" : "00000880050000041139", "externalReference" : "000008800500000411390000100001" }, "merchantAction" : { "actionType" : "REDIRECT", "redirectData" : { "RETURNMAC" : "775a1acc74584ab48a9d5b86abd30af5", "redirectURL" : "https://orb.gc.sandbox.gi.worldline-solutions.com/orb/orb?ACTION=DO_START&REF=000008800500000411390000100001&MAC=3c9bec1c84e54a48916a48f9b243ec46" }, "showData" : [ ] }, "payment" : { "id" : "000008800500000411390000100001", "paymentOutput" : { "amountOfMoney" : { "amount" : 100, "currencyCode" : "EUR" }, "references" : { "paymentReference" : "170108503200" }, "paymentMethod" : "redirect", "redirectPaymentMethodSpecificOutput" : { "paymentProductId" : 806 } }, "status" : "REDIRECTED", "statusOutput" : { "isCancellable" : true, "isRetriable" : false, "statusCategory" : "PENDING_PAYMENT", "statusCode" : 20, "statusCodeChangeDateTime" : "20231207161608", "isAuthorized" : false, "isRefundable" : false } } } ``` The merchantAction is omitted from the [GET /v1/{merchantId}/payments/{paymentId}](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/payments/get.html?paymentPlatform=ALL) API call and will return a response like this: GET PAYMENT RESPONSECopy code ```hljs javascript language-javascript { "id" : "000008800510000122030000100001", "hostedCheckoutSpecificOutput" : { "hostedCheckoutId" : "06571bcb-b4e1-71ff-ba29-c5fc950f0864", "variant" : "138" }, "paymentOutput" : { "amountOfMoney" : { "amount" : 100, "currencyCode" : "EUR" }, "references" : { "merchantReference" : "qiciS", "paymentReference" : "T88500048N8A" }, "paymentMethod" : "redirect", "redirectPaymentMethodSpecificOutput" : { "paymentProductId" : 806, "bankAccountIban" : { "accountHolderName" : "Iman Prijs", "iban" : "************311251" }, "paymentProduct806SpecificOutput" : { "billingAddress" : { "city" : "Cuijk", "street" : "Toermalijnlaan 106", "zip" : "5431 ZK" }, "customerAccount" : { "accountLastDigits" : "311251", "bankName" : "Rabobank", "clearinghouse" : "NETHERLANDS" } } } }, "status" : "CAPTURED", "statusOutput" : { "isCancellable" : false, "isRetriable" : false, "statusCategory" : "COMPLETED", "statusCode" : 900, "statusCodeChangeDateTime" : "20231207134500", "isAuthorized" : true, "isRefundable" : false } } ``` ## Cancellations To cancel payment, you need to send cancellation with [POST /v1/{merchantId}/payments/{paymentId}/cancel](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/payments/cancel.html?paymentPlatform=ALL) API call. The request doesn't have a body. The cancellation can only be performed when the status is PENDING_APPROVAL and statusOutput.isCancellable is true. ## Refund To start a refund process, you should use the API call [POST /v1/{merchantId}/payments/{paymentId}/refund](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/payments/refund.html?paymentPlatform=ALL). This action is only applicable if the payment status is PAID. If you wish to refund the full order amount, you can do so by sending a request using the same API call, but with an empty body. A basic refund payload only requires the amountOfMoney object specifying the amount and currencyCode: CREATE REFUND REQUESTCopy code ```hljs javascript language-javascript { "amountOfMoney": { "amount": 25, "currencyCode": "SEK" } } ``` You have the option to refund a part of the funds as well. For this, it's necessary to include a payload with the amountOfMoney object, where you specify the amount and the currencyCode. Additionally, if you want to view the details of your refund, you can use the API call [GET /v1/{merchantId}/refunds/{refundId}](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/refunds/get.html?paymentPlatform=ALL). ### Pre-authorization for refunds The pre-authorization feature allows you to choose when to capture refunds. This option is possible with the configured REFUNDACCEPTNEEDEDINDICATOR, that was set for you during the boarding process. So when you send a [POST/v1/{merchantId}/payments/{paymentId}/refund](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/payments/refund.html?paymentPlatform=ALL) API call, you'll receive a response like this: CREATE REFUND RESPONSECopy code ```hljs javascript language-javascript { "id" : "00000880051000012387000-100001", "refundOutput" : { "amountOfMoney" : { "amount" : 100, "currencyCode" : "DKK" }, "references" : { "paymentReference" : "T8850004DV2A" }, "paymentMethod" : "redirect", "eWalletRefundMethodSpecificOutput" : { "refundProductId" : 806, "totalAmountPaid" : 100, "totalAmountRefunded" : 0 } }, "status" : "PENDING_APPROVAL", "statusOutput" : { "isCancellable" : true, "statusCategory" : "PENDING_MERCHANT", "statusCode" : 600, "statusCodeChangeDateTime" : "20231220150231" } } ``` To authorize us to proceed with the capture, you must send your approval using [POST /v1/{merchantId}/refunds/{refundId}/approve](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/refunds/approve.html?paymentPlatform=ALL). The same API call can also be used to adjust the capture amount. To set a specific amount, submit the amount property in your API call, ensuring it's less than the initially authorized amount. The structure for the payload should be as follows: APPROVE PAYMENT REQUESTCopy code ```hljs javascript language-javascript { "amount": 50 } ``` To initiate a cancellation, you need to send a request using the API call [POST /v1/{merchantId}/refunds/{refundId}/cancel](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/refunds/cancel.html?paymentPlatform=ALL). Note that this request does not require a body. # Webhooks To track transaction status updates, you can subscribe to the following [webhooks notifications](https://docs.connect.worldline-solutions.com/documentation/webhooks/.md): * payment.created * payment.redirected * payment.pending_payment * payment.captured * payment.paid [Next Process flows](https://docs.connect.worldline-solutions.com/payment-product/trustly/process-flows/globalcollect.md)