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:
When the supplier's bank account details has been saved and tokenized, you receive a webhook containing:
eventCode: RECURRING_CONTRACToriginalReference: ThepspReferenceof 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. |
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.eventCodeDescription PAYOUT_THIRDPARTY The user reviewing the payout confirmed it. The successfield indicates whether we received the payout request. Possible values of thesuccessfield:
- 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 successfield 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 successfield 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: