To use Trustly to pay out your suppliers or users, first you need to tokenize their bank account details, submit a payout request, and then confirm or decline the payout.
Requirements
Before you can start sending payouts through Trustly, you need to:
- Contact our Support Team to enable payouts. Using the Payout API requires additional approval and configuration on our end.
- Have an existing integration that accepts Trustly payments. If you haven't integrated yet, refer to our integration guides.
Step 1: Tokenize Trustly payment details
To tokenize Trustly details for payouts, make a POST /payments request. In your request, additionally include:
Parameters | Description |
---|---|
amount |
The value (in minor units) and currency . Set the value to the payment value if you want to tokenize payment details while accepting a payment, or to 0 if you just want to tokenize and save Trustly details for future payouts. |
enablePayout |
Set this to true to tokenize the details for payout. |
shopperReference |
Your unique identifier for the supplier or user. |
In the example below, we send a request to tokenize the bank account details of a supplier with shopperReference
Supplier_JaneSmith:
curl https://checkout-test.adyen.com/v68/payments \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "amount":{ "value":0, "currency":"SEK" }, "paymentMethod":{ "type":"trustly" }, "enablePayOut":true, "shopperReference":"Supplier_JaneSmith", "reference":"YOUR_ORDER_NUMBER", "returnUrl": "https://your-company.com/checkout?shopperOrder=12xy..", "merchantAccount":"ADYEN_MERCHANT_ACCOUNT" }'
When the supplier's bank account details has been saved and tokenized, you receive a webhook containing:
eventCode
: RECURRING_CONTRACToriginalReference
: ThepspReference
of the payment request.
Step 2: Submit a payout request
When you are ready to send a payout, make a POST /submitThirdParty request, specifying the following parameters:
Parameters | Description |
---|---|
merchantAccount |
The merchant account identifier you want to process this payout transaction request with. |
amount |
The value (in minor units) and currency of the payout. |
shopperReference |
The unique identifier for the supplier or user, which matches what you sent when you tokenized their details in the /payments request. |
shopperEmail |
Email address of the supplier or user you are paying out to. |
recurring |
Set this to PAYOUT. |
reference |
Your identifier for this payout request. |
selectedRecurringDetailReference |
Set this to LATEST. |
dateOfBirth |
Date of birth of the supplier or user you are paying out to. |
socialSecurityNumber |
Social security number of the supplier or user you are paying out to. |
shopperName |
Name of the supplier or user you are paying out to. |
curl https://pal-test.adyen.com/pal/servlet/Payout/v68/submitThirdParty \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "amount" : { "currency" : "EUR", "value" : "1000" }, "merchantAccount" : "ADYEN_MERCHANT_ACCOUNT", "recurring" : { "contract" : "PAYOUT" }, "reference" : "YOUR_PAYOUT_REFERENCE", "shopperEmail" : "supplierjanesmith@example.com", "shopperReference" : "Supplier_JaneSmith", "selectedRecurringDetailReference" : "LATEST", "dateOfBirth": "YYYY-MM-DD", "socialSecurityNumber": "SOCIAL_SECURITY_NUMBER", "shopperName":{ "firstName":"Jane", "lastName":"Smith" } }'
The response contains:
pspReference
- Unique identifier for this payout request. Save this, as you'll need this identifier to review the payout, and to know the payout result.resultCode
[payout-submit-received] - Confirmation that the payout request has been received. The result of the payout will be sent in a webhook.
{ "pspReference" : "WNS7WQ756L2GWR82", "resultCode" : "[payout-submit-received]" }
Step 3: Confirm or decline the payout
Review the payout and make either a POST /confirmThirdParty or POST /declineThirdParty request, specifying:
originalReference
: The PSP reference of the payout request, which you received in the /submitThirdParty response.
In the example below, we confirm the payout request with PSP reference WNS7WQ756L2GWR82:
curl https://pal-test.adyen.com/pal/servlet/Payout/v68/confirmThirdParty \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "merchantAccount" : "ADYEN_MERCHANT_ACCOUNT", "originalReference" : "WNS7WQ756L2GWR82" }'
The response contains:
pspReference
- Unique identifier for this confirm or decline request.resultCode
- Depending on the request that you made, you receive a [payout-confirm-received] or [payout-decline-received]. This is the confirmation that the payout confirm or decline request has been received.
{ "pspReference" : "QBQQ9DLNRHHKGK38", "resultCode" : "[payout-confirm-received]" }
Step 4: Confirm payout result
Wait for the webhook to confirm the payout result. The webhook contains:
originalReference
: The PSP reference of the payout request, which you received in the /submitThirdParty response.pspReference
: The PSP reference of the confirm or decline request, which you received in the /confirmThirdParty or /declineThirdParty response.-
eventCode
: Depending on the result of the payout request, you receive any of the following event codes.eventCode
Description PAYOUT_THIRDPARTY The user reviewing the payout confirmed it. The success
field indicates whether we received the payout request. Possible values of thesuccess
field:
- true - We received your payout request, and will send it to the financial institution. When approved, the funds are paid out within 2 business days. In case the financial institution rejects the request, you will receive a webhook with
eventCode
: PAIDOUT_REVERSED. - false - The request failed. The reason field includes a short description of the issue. Review the reason, fix the issue if possible, and resubmit the payout request.
PAYOUT_DECLINE The user reviewing the payout declined it. The success
field of this webhook is always set to true.PAYOUT_EXPIRE 7 days have passed since the payout was submitted, and the reviewer has neither confirmed nor declined it. The success
field of this webhook is always set to true.PAIDOUT_REVERSED The financial institution rejected the payout. We will return the funds back to your account. Check with the supplier or user the status of their bank account. - true - We received your payout request, and will send it to the financial institution. When approved, the funds are paid out within 2 business days. In case the financial institution rejects the request, you will receive a webhook with
Below is an example of a successful payout request webhook, with eventCode
PAYOUT_THIRDPARTY:
{ "live" : "false", "notificationItems" : [ { "notificationRequestItem" : { "amount" : { "value" : 1000, "currency" : "EUR" }, "eventCode" : "PAYOUT_THIRDPARTY", "eventDate" : "2020-04-24T12:59:53+02:00", "merchantAccountCode" : "ADYEN_MERCHANT_ACCOUNT", "merchantReference" : "YOUR_PAYOUT_REFERENCE", "paymentMethod" : "trustly", "originalReference The PSP reference of the payout request in step 2" : "WNS7WQ756L2GWR82", "pspReferenceThe PSP reference of the confirm payout request in step 3" : "QBQQ9DLNRHHKGK38", "reason" : "Approved", "success" : "true" } } ] }