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/v68/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/checkout?shopperOrder=12xy..",
"merchantAccount":"YOUR_MERCHANT_ACCOUNT",
}'
# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen::Client.new
adyen.api_key = "YOUR_X-API-KEY"
response = adyen.checkout.payments({
:amount => {
:currency => "SEK",
:value => 0
},
:reference => "YOUR_ORDER_NUMBER",
:paymentMethod => {
:type => "trustly"
},
:returnUrl => "https://your-company.com/checkout?shopperOrder=12xy..",
:enablePayOut => true,
:shopperReference => "Supplier_JaneSmith",
:merchantAccount => "YOUR_MERCHANT_ACCOUNT"
})
// Set YOUR_X-API-KEY with the API key from the Customer Area.
// Change to Environment.LIVE and add the Live URL prefix when you're ready to accept live payments.
Client client = new Client("YOUR_X-API-KEY", Environment.TEST);
Checkout checkout = new Checkout(client);
PaymentsRequest paymentsRequest = new PaymentsRequest();
String merchantAccount = "YOUR_MERCHANT_ACCOUNT";
paymentsRequest.setMerchantAccount(merchantAccount);
Amount amount = new Amount();
amount.setCurrency("SEK");
amount.setValue(0L);
paymentsRequest.setAmount(amount);
DefaultPaymentMethodDetails paymentMethodDetails = new DefaultPaymentMethodDetails();
paymentMethodDetails.setType("trustly");
paymentsRequest.setPaymentMethod(paymentMethodDetails);
paymentsRequest.setEnablePayOut(true);
paymentsRequest.setShopperReference("Supplier_JaneSmith");
paymentsRequest.setReference("YOUR_ORDER_NUMBER");
paymentsRequest.setReturnUrl("https://your-company.com/checkout?shopperOrder=12xy..");
PaymentsResponse paymentsResponse = checkout.payments(paymentsRequest);
// Set your X-API-KEY with the API key from the Customer Area.
$client = new \Adyen\Client();
$client->setXApiKey("YOUR_X-API-KEY");
$service = new \Adyen\Service\Checkout($client);
$params = array(
"amount" => array(
"currency" => "SEK",
"value" =>0
),
"reference" => "YOUR_ORDER_NUMBER",
"paymentMethod" => array(
"type" => "trustly"
),
"returnUrl" => "https://your-company.com/checkout?shopperOrder=12xy..",
"enablePayOut" => true,
"shopperReference" => "Supplier_JaneSmith",
"merchantAccount" => "YOUR_MERCHANT_ACCOUNT"
);
$result = $service->payments($params);
#Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen.Adyen()
adyen.client.xapikey = 'YOUR_X-API-KEY'
result = adyen.checkout.payments({
'amount': {
'value': 0,
'currency': 'SEK'
},
'reference': 'YOUR_ORDER_NUMBER',
'paymentMethod': {
'type': 'trustly'
},
'shopperReference': 'Supplier_JaneSmith',
'enablePayOut': true,
'merchantAccount': 'YOUR_MERCHANT_ACCOUNT',
'returnUrl': 'https://your-company.com/checkout?shopperOrder=12xy..',
})
// Set your X-API-KEY with the API key from the Customer Area.
var client = new Client ("YOUR_X-API-KEY", Environment.Test);
var checkout = new Checkout(client);
var amount = new Adyen.Model.Checkout.Amount("SEK", 0);
var details = new Adyen.Model.Checkout.DefaultPaymentMethodDetails{
Type = "trustly"
};
var paymentsRequest = new Adyen.Model.Checkout.PaymentRequest
{
Reference = "YOUR_ORDER_NUMBER",
Amount = amount,
ReturnUrl = @"https://your-company.com/checkout?shopperOrder=12xy..",
MerchantAccount = "YOUR_MERCHANT_ACCOUNT",
EnablePayOut = true,
ShopperReference = "Supplier_JaneSmith",
PaymentMethod = details
};
var paymentResponse = checkout.Payments(paymentsRequest);
// Set your X-API-KEY with the API key from the Customer Area.
const {Client, Config, CheckoutAPI} = require('@adyen/api-library');
const config = new Config();
// Set your X-API-KEY with the API key from the Customer Area.
config.apiKey = '[API_KEY]';
config.merchantAccount = '[YOUR_MERCHANT_ACCOUNT]';
const client = new Client({ config });
client.setEnvironment("TEST");
const checkout = new CheckoutAPI(client);
checkout.payments({
amount: { currency: "SEK", value: 0 },
paymentMethod: {
type: 'trustly'
},
reference: "YOUR_ORDER_NUMBER",
merchantAccount: config.merchantAccount,
enablePayOut: true,
shopperReference: "Supplier_JaneSmith",
returnUrl: "https://your-company.com/checkout?shopperOrder=12xy..",
}).then(res => res);
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'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. |
dateOfBirth |
Date of birth of the supplier or user you're paying out to. |
socialSecurityNumber |
Social security number of the supplier or user you're paying out to. |
shopperName |
Name of the supplier or user you're paying out to. |
curl https://pal-test.adyen.com/pal/servlet/Payout/v68/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@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.
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:
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 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" : "YOUR_MERCHANT_ACCOUNT",
"merchantReference" : "YOUR_PAYOUT_REFERENCE",
"paymentMethod" : "trustly",
"{hint: The PSP reference of the payout request in step 2}originalReference{/hint}" : "WNS7WQ756L2GWR82",
"{hint:The PSP reference of the confirm payout request in step 3}pspReference{/hint}" : "QBQQ9DLNRHHKGK38",
"reason" : "Approved",
"success" : "true"
}
}
]
}