Make payouts to customers' bank accounts without actions required from them
Overview
You can use the AccountPayout API method to transfer money to customers' bank accounts. To specify receiving bank accounts, the call needs to include AccountID parameter.
The AccountPayout method is used together with API methods SelectAccount and RegisterAccount in these situations:
- When you do not have customers' bank account details, call SelectAccount so that customers can select their account for Trustly to respond with an accountid in an Account notification.
- When you have customers' bank account details, call RegisterAccount so that Trustly will register the account and respond with an accountid in the respons.
Request example
{
"method": "AccountPayout",
"params": {
"Signature": "K5+hjuMqbsH0Ku ... S16VbzRsw==",
"UUID": "258a2184-2842-b485-25ca-293525152425",
"Data": {
"AccountID": "1234567890",
"Amount": "800.00",
"Attributes": {
"ShopperStatement": "Trustly.com"
},
"Currency": "EUR",
"EndUserID": "123123",
"MessageID": "771463386074",
"NotificationURL": "https://mynotifications.com/listener/f346212d",
"Password": "*",
"Username": "your_username"
}
},
"version": "1.1"
}
{
"method": "AccountPayout",
"params": {
"Signature": "K5+hjuMqbsH0Ku ... S16VbzRsw==",
"UUID": "258a2184-2842-b485-25ca-293525152425",
"Data": {
"AccountID": "1234567890",
"Amount": "800.00",
"Attributes": {
"SenderInformation": {
"Address": "Street 1, 12345 Barcelona",
"CountryCode": "ES",
"CustomerID": "123456789",
"DateOfBirth": "1990-03-31",
"Firstname": "Steve",
"Lastname": "Smith",
"Partytype": "PERSON"
},
"ShopperStatement": "Trustly.com"
},
"Currency": "EUR",
"EndUserID": "123123",
"MessageID": "771463386074",
"NotificationURL": "https://mynotifications.com/listener/f346212d",
"Password": "*",
"Username": "your_username"
}
},
"version": "1.1"
}
{
"method": "AccountPayout",
"params": {
"Signature": "K5+hjuMqbsH0Ku ... S16VbzRsw==",
"UUID": "258a2184-2842-b485-25ca-293525152425",
"Data": {
"AccountID": "1234567890",
"Amount": "800.00",
"Attributes": {
"SenderInformation": {
"Address": "Street 1, 12345 Barcelona",
"CountryCode": "ES",
"Firstname": "merchant_name",
"Lastname": "",
"Partytype": "ORGANISATION"
},
"PSPMerchant": "merchant_name",
"PSPMerchantURL": "https://merchantURL.com/",
"MerchantCategoryCode": "1234",
"ShopperStatement": "merchant_name"
},
"Currency": "EUR",
"EndUserID": "123123",
"MessageID": "771463386074",
"NotificationURL": "https://mynotifications.com/listener/f346212d",
"Password": "*",
"Username": "your_username"
}
},
"version": "1.1"
}
Request parameters
| Parameter name | Description | Req. | Type | Example |
|---|---|---|---|---|
| Username | The username. | Yes | Text | joe |
| Password | The password. | Yes | Text | secret |
| NotificationURL | The URL to which notifications for this payment should be sent to. This URL should be hard to guess and not contain a ? ("question mark"). | Yes | Text | https://example.com/trustly/ notification/a2b63j23dj |
| AccountID | The AccountID received from an Account notification to which the money shall be sent. | Yes | Text | 1234567890 |
| EndUserID | ID, username, hash or anything uniquely identifying the end-user requesting the withdrawal. Preferably the same ID/username as used in the merchant's own backoffice in order to simplify for the merchant's support department. | Yes | Text | 123123 |
| MessageID | Your unique ID for the payout. If the MessageID is a previously initiated P2P order then the payout will be attached to that P2P order and the amount must be equal to or lower than the previously deposited amount. | Yes | Text | 12345678 |
| Amount | The amount to send. See format in Handling currencies. Only digits. Use dot (.) as decimal separator. If the end-user holds a balance in the merchant's system then the amount must have been deducted from that balance before calling this method. | Yes | Text | 98.02 |
| Currency | The currency of the amount to send. | Yes | Text | SEK |
| Attributes | Attributes for this method. See Attributes. | Yes | Object | {"ShopperStatement": "MyBrand.com"} |
Attributes
The parameter Attributes is an object of attributes. New attributes may be added in future versions of the API but existing attributes will never be removed.
| Attribute name | Description | Required. | Type | Example |
|---|---|---|---|---|
| ShopperStatement | The text to show on the end-user's bank statement after Trustly's own 10 digit reference (which always will be displayed first). The reference must let the end user identify the merchant based on this value. So the ShopperStatement should contain either your brand name, website name, or company name. If possible, try to keep this text as short as possible to maximise the chance that the full reference will fit into the reference field on the customer's bank since some banks allow only a limited number of characters. If the full ShopperStatement does not fit into the reference it will be truncated from the end. | Yes | Text | MyBrand.com |
| ExternalReference | The ExternalReference is a reference set by the merchant for any purpose and does not need to be unique for every API call. The ExternalReference will be included in version 1.2 of the settlement report. See ViewAutomaticSettlementDetailsCSV. | No | Text | 23423525234 |
| PSPMerchant | Human-readable identifier of the consumer-facing merchant (e.g. legal name or trade name) | Yes* | Text | Merchant Ltd. |
| PSPMerchantURL | URL of the consumer-facing website where the order is initiated | Yes* | Text | www.merchant.com |
| MerchantCategoryCode | VISA category codes describing the merchant's nature of business. | Yes* | Text | 5499 |
| SenderInformation | Information about the Payer (ultimate debtor). This is required for some merchants and partners, see below. | Yes** | Object | {"Firstname": "Steve"...} |
* PSPMerchant, PSPMerchantURL and MerchantCategoryCode
PSPMerchant, PSPMerchantURL and MerchantCategoryCode are mandatory attributes for Trustly Partners that are using Express Merchant Onboarding and aggregate traffic under a master processing account. It is also mandatory for E-wallets used directly in a merchant's checkout, whereby the purpose of a Trustly transaction is to pay for goods/services by placing funds on the payer's e-money account ("funding stage") following an immediate transfer into the e-money account of the payee ( "payment" stage).
** SenderInformation
SenderInformation{} is mandatory to send in Attributes{} for money transfer services (including remittance houses), e-wallets, prepaid cards, as well as for Trustly Partners that are using Express Merchant Onboarding and aggregate traffic under a master processing account (other cases may also apply).
SenderInformation attributes
| Name | Description | Required | Type | Example |
|---|---|---|---|---|
| Partytype | Partytype can be "PERSON" or "ORGANISATION" (if the ultimate debtor is an organization/company). | Yes | Text | PERSON |
| Address | The Payer's address | Yes | Text | Street 1, 12345 Barcelona |
| CountryCode | The ISO 3166-1-alpha-2 code of the Payer's country. | Yes | Text | SE |
| Firstname | First name of the person (or the name of the organization) | Yes | Text | Steve |
| Lastname | Last name of the person (empty for organization) | Yes | Text | Smith |
| CustomerID | Payment account number or an alternative consistent unique identifier which allows to identify the Payer in the system of the PSP of the Payer. Note: this is not a transaction ID or similar. This identifier must stay consistent across all transactions relating to this Payer. | No | Text | 123456789 |
| DateOfBirth | Date of birth for the person (YYYY-MM-DD) or organisational number for the organization | No | Text | 1990-03-31 |
{
"method": "AccountPayout",
"params": {
"Signature": "K5+hjuMqbsH0Ku ... S16VbzRsw==",
"UUID": "258a2184-2842-b485-25ca-293525152425",
"Data": {
"AccountID": "1234567890",
"Amount": "800.00",
"Attributes": {
"ShopperStatement": "Trustly.com"
},
"Currency": "EUR",
"EndUserID": "123123",
"MessageID": "771463386074",
"NotificationURL": "https://mynotifications.com/listener/f346212d",
"Password": "*",
"Username": "your_username"
}
},
"version": "1.1"
}
{
"method": "AccountPayout",
"params": {
"Signature": "K5+hjuMqbsH0Ku ... S16VbzRsw==",
"UUID": "258a2184-2842-b485-25ca-293525152425",
"Data": {
"AccountID": "1234567890",
"Amount": "800.00",
"Attributes": {
"SenderInformation": {
"Address": "Street 1, 12345 Barcelona",
"CountryCode": "ES",
"CustomerID": "123456789",
"DateOfBirth": "1990-03-31",
"Firstname": "Steve",
"Lastname": "Smith",
"Partytype": "PERSON"
},
"ShopperStatement": "Trustly.com"
},
"Currency": "EUR",
"EndUserID": "123123",
"MessageID": "771463386074",
"NotificationURL": "https://mynotifications.com/listener/f346212d",
"Password": "*",
"Username": "your_username"
}
},
"version": "1.1"
}
{
"method": "AccountPayout",
"params": {
"Signature": "K5+hjuMqbsH0Ku ... S16VbzRsw==",
"UUID": "258a2184-2842-b485-25ca-293525152425",
"Data": {
"AccountID": "1234567890",
"Amount": "800.00",
"Attributes": {
"SenderInformation": {
"Address": "Street 1, 12345 Barcelona",
"CountryCode": "ES",
"Firstname": "merchant_name",
"Lastname": "",
"Partytype": "ORGANISATION"
},
"PSPMerchant": "merchant_name",
"PSPMerchantURL": "https://merchantURL.com/",
"MerchantCategoryCode": "1234",
"ShopperStatement": "merchant_name"
},
"Currency": "EUR",
"EndUserID": "123123",
"MessageID": "771463386074",
"NotificationURL": "https://mynotifications.com/listener/f346212d",
"Password": "*",
"Username": "your_username"
}
},
"version": "1.1"
}
{
"result": {
"signature": "K47hjudG6sH0Ku ... S16VbzfG8==",
"uuid": "258a2184-2842-b485-25ca-293525152425",
"method": "AccountPayout",
"data": {
"orderid": "7653345737",
"result": "1"
}
},
"version":"1.1"
}
Response example
{
"result": {
"signature": "K47hjudG6sH0Ku ... S16VbzfG8==",
"uuid": "258a2184-2842-b485-25ca-293525152425",
"method": "AccountPayout",
"data": {
"orderid": "7653345737",
"result": "1"
}
},
"version":"1.1"
}
Response attributes
The result returned is a hash with the following elements:
| Hash key | Description | Type | Example |
|---|---|---|---|
| orderid | The globally unique OrderID the account payout order was assigned in our system. | Text | 7653345737 |
| result | 1 if the payout could be accepted and 0 otherwise. | Text | 1 |
Failed payouts
In case an error occurs when processing the payout, a Credit notification or Cancel notification will be sent to the provided NotificationURL so that the merchant can flag the payout as failed in their system.
In case the end-user holds a balance on the merchant's system, the amount of the payout should be credited back to the end user's balance. Note that the credit notification will be sent AFTER the synchronous response containing "result":"1" has been sent, while a cancel notification can be sent at any point.
There are several reasons why an AccountPayout can fail after the "result":"1" response has been sent:
- There are not enough funds on the merchant's Trustly account. In this case the credit notification will be sent immediately after the AccountPayout request has been received.
- The funds are sent to the end user's bank account, but then later Trustly is notified by the bank that the transfer failed, for example if the recipient's bank account has been closed. This is usually very uncommon, but if it happens the credit notification can be sent several days after the AccountPayout request was sent.
- The transaction crashed, and was aborted before it was completed by Trustly.
Error codes
These error codes can be returned for AccountPayout calls. To handle errors, see Error handling.
| Error Number | Error Code | Description |
|---|---|---|
| 602 | ERROR_FUNCTION_ACCESS_DENIED | The merchant does not have access to this function. |
| 607 | ERROR_HOST_ACCESS_DENIED | The IP address of the merchant has not been added to Trustly's IP-whitelist. |
| 615 | ERROR_INVALID_AMOUNT | The Amount is invalid. The amount must be > 0 with 2 decimals. |
| 616 | ERROR_INVALID_CREDENTIALS | The username and/or password used in the API call is incorrect. |
| 620 | ERROR_UNKNOWN | There could be several reasons for this error, please reach out to your Trustly contact for details. |
| 623 | ERROR_INVALID_PARAMETERS | Some value or parameter in the API call does not match the expected format. |
| 624 | ERROR_INVALID_BANK_ACCOUNT_NUMBER | The specified AccountID does not exist. |
| 636 | ERROR_UNABLE_TO_VERIFY_RSA_SIGNATURE | The signature could not be verified using the merchant's public key. Either the wrong private key was used to generate the signature, or the the data object used to create the signature was serialized incorrectly. |
| 637 | ERROR_DUPLICATE_MESSAGE_ID | The MessageID has been used before. |
| 638 | ERROR_ENDUSER_IS_BLOCKED | The enduser that initiated the payment is blocked. |
| 639 | ERROR_NO_PUBLIC_KEY | No public key has been configured for the merchant on Trustly's side. |
| 688 | ERROR_DUPLICATE_UUID | This uuid has been used before. |
| 696 | ERROR_ENDUSERID_IS_NULL | The EndUserID sent in the request is null |
| 697 | ERROR_MESSAGEID_IS_NULL | The MessageID sent in the request is null |
| 704 | ERROR_MALFORMED_MESSAGEID | The MessageID sent in the request is malformed. |
| 705 | ERROR_MALFORMED_NOTIFICATIONURL | The NotificationURL sent in the request is malformed. It must be a valid https address. |
| 706 | ERROR_MALFORMED_ENDUSERID | The EndUserID sent in the request is malformed. |
| 717 | ERROR_INVALID_ORDER_ATTRIBUTE | One or more attributes are sent with the incorrect value. Please reach out to your Trustly contact for more information. |
| 718 | ERROR_DISABLED_USER | The merchant's user is disabled in Trustly's system. |
| 734 | ERROR_NOT_SECURE_NOTIFICATIONURL | The NotificationURL must be using HTTPS, not plain HTTP. |
New error codes can be added and existing error codes can be removed without notice.