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.
Before you begin
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/v66/payments \
-H "x-API-key: YOUR_X-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",
"merchantAccount":"YOUR_MERCHANT_ACCOUNT"
}'
When the supplier's bank account details has been saved and tokenized, you receive a notification webhook containing:
eventCode
: RECURRING_CONTRACToriginalReference
: ThepspReference
of the payment request.
Step 2: Submit a payout request
When you're 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're paying out to. |
recurring |
Set this to PAYOUT. |
reference |
Your identifier for this payout request. |
selectedRecurringDetailReference |
Set this to LATEST. |
curl https://pal-test.adyen.com/pal/servlet/Payout/v64/submitThirdParty \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
"amount" : {
"currency" : "EUR",
"value" : "1000"
},
"merchantAccount" : "YOUR_MERCHANT_ACCOUNT",
"recurring" : {
"contract" : "PAYOUT"
},
"reference" : "YOUR_PAYOUT_REFERENCE",
"shopperEmail" : "supplierjanesmith@email.com",
"shopperReference" : "Supplier_JaneSmith",
"selectedRecurringDetailReference" : "LATEST"
}'
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 notification webhook.
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 9913140798220028:
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.
Step 4: Confirm payout result
Wait for the notification webhook to confirm the payout result. The notification 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 notification 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 notification 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 notification 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 notification with
Below is an example of a successful payout request notification, 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" : "YOUR_MERCHANT_ACCOUNT",
"merchantReference" : "YOUR_PAYOUT_REFERENCE",
"paymentMethod" : "trustly",
"{hint: The PSP reference of the payout request in step 2}originalReference{/hint}" : "9913140798220028",
"{hint:The PSP reference of the confirm payout request in step 3}pspReference{/hint}" : "9911698825991739B",
"reason" : "Approved",
"success" : "true"
}
}
]
}