Accept recurring payments
Please note - Trustly Direct Debit (TDD) is no longer offered to new merchants
Please see Merchant Direct Debit (MDD) instead.
Overview
Charges a specific AccountID using direct debit. A previously approved direct debit mandate must exist on the AccountID (see SelectAccount for details).
Request example
{
"method":"Charge",
"params":{
"Signature":"f4ThjuMqbsdG6u ... S16VbzD4h==",
"UUID":"258a2184-2842-b485-25ca-293525152425",
"Data":{
"AccountID":"1234567890",
"Amount":"25.00",
"Attributes":{
"Email":"[email protected]",
"ShopperStatement":"Trustly"
},
"Currency":"SEK",
"EndUserID":12345,
"MessageID":"your_unique_deposit_id",
"NotificationURL":"https://URL_to_your_notification_service",
"Password":"merchant_password",
"Username":"merchant_username"
}
},
"version":"1.1"
}
{
"method": "Charge",
"params": {
"Signature": "f4ThjuMqbsdG6u ... S16VbzD4h==",
"UUID": "258a2184-2842-b485-25ca-293525152425",
"Data": {
"AccountID": "1234567890",
"Amount": "25.00",
"Attributes": {
"PSPMerchant": "merchant_name",
"PSPMerchantURL": "https://merchantURL.com/",
"MerchantCategoryCode": "1234",
"Email": "[email protected]",
"ShopperStatement": "Trustly"
},
"Currency": "SEK",
"EndUserID": 12345,
"MessageID": "your_unique_transaction_id",
"NotificationURL": "https://URL_to_your_notification_service",
"Password": "merchant_password",
"Username": "merchant_username"
}
},
"version": "1.1"
}
Request parameters
| Parameter name | Description | Req. | Type | Example |
|---|---|---|---|---|
| Username | The username. | Yes | Text | joe |
| Password | The password. | Yes | Text | secret |
| AccountID | The AccountID received from an Account notification which shall be charged. | Yes | Text | 1234567890 |
| 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/a2b63j23dj23883jhfhfh |
| EndUserID | ID, username, hash or anything uniquely identifying the end-user being charged. 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 charge. | Yes | Text | 12345678 |
| Amount | The amount to charge. See format in Handling currencies. Only digits. Use dot (.) as decimal separator. | Yes | Text | 98.02 |
| Currency | The currency of the amount to charge. | Yes | Char(3) | SEK |
| Attributes | Attributes for this method. | Yes | Hash | {"ShopperStatement":"Flowers"} |
Attributes
| Attribute name | Description | Req. | Type | Example |
|---|---|---|---|---|
| ShopperStatement | The text to show on the end-user's bank statement as well as in end-user e-mail communication. On the bank statement, only the first seven characters (along with Trustly's reference) will be shown. Allowed characters: A-Z (both upper and lower case), 0-9, ".", "-", "_", " " (dot, dash, underscore, space). | Yes | Text | Shopperstatement: "Sport Shop". Will result in "T Sport S xyz" in bank statement and "Sport Shop" in e-mails. |
| The email address of the end user. | Yes | Text | [email protected] | |
| PaymentDate | The date when the funds will be charged from the end user's bank account. If this attribute is not sent, the charge will be attempted as soon as possible. | No | Text | 2019-06-25 |
| ExternalReference | The ExternalReference is a reference set by the merchant for any purpose and does not need to be unique for every API call. For example, it can be used for invoice references, OCR numbers and also for offering end users the option to part-pay an invoice using the same ExternalReference. The ExternalReference will be included in version 1.2 of the settlement report. See ViewAutomaticSettlementDetailsCSV. | No | Text | 32423534523 |
| 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 |
* PSPMerchant, PSPMerchantURL and MerchantCategoryCode
PSPMerchant, PSPMerchantURL and MerchantCategoryCode are mandatory attributes for Trustly Partners that are using Express Merchant Onboarding (EMO) and aggregate traffic under a master processing account.
Response example
{
"method":"Charge",
"uuid":"258a2184-2842-b485-25ca-293525152425",
"data":{
"result":"1",
"rejected":null,
"orderid":"1234512345"
},
"signature":"QBuLx ... JDGM/GVq5EBaPnGmvxA=="
}
Response attributes
The returned result is a hash with the following attributes.
| Hash key | Description | Type | Example |
|---|---|---|---|
| result | 1 if the charge was accepted for processing, 0 otherwise. Note that this is an acceptance of the order, no money has been charged from the account until you receive notifications thereof. | Boolean | 1 |
| orderid | The globally unique OrderID the charge order was assigned in our system, or null if the charge was not accepted. The order has no end-user interaction; it is merely used as a reference for the notifications delivered regarding the charge. See section "Notifications" below for details. | BigInt | 7653345737 |
| rejected | If the charge was NOT accepted, a textual code describing the rejection reason, null otherwise. The possible rejected codes are: ERROR_MANDATE_NOT_FOUND - the AccountID does not have an active mandate ERROR_DIRECT_DEBIT_NOT_ALLOWED - Trustly Direct Debit is not enabled on the merchant's account in Trustly's system. ERROR_ACCOUNT_NOT_FOUND - the specified AccountID does not exist. | Text | ERROR_MANDATE_NOT_FOUND |
Notifications
The notifications delivered for Charge orders are as follows:
- Immediately after the Charge has been accepted for processing, a Pending notification is sent.
- If the Charge could not be processed, a Cancel notification is sent.
- Once the Charge has been successfully processed, a Credit notification is sent.
Error codes
These error codes can be returned for Charge calls. To handle errors, see Error handling.
The Charge method can also return a number of "rejected" messages. See rejected in Response attributes.
| 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. |
| 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 serialised incorrectly. |
| 637 | ERROR_DUPLICATE_MESSAGE_ID | The MessageID has been used before. |
| 638 | ERROR_ENDUSER_IS_BLOCKED | The end-user that initiated the payment is blocked. |
| 639 | ERROR_NO_PUBLIC_KEY | No public key has been configured for the merchant on Trustly's side. |
| 642 | ERROR_INVALID_EMAIL | The email attribute is missing or invalid (this is a requirement when using Trustly Direct Debit). |
| 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. |
| 712 | ERROR_DIRECT_DEBIT_NOT_ALLOWED | Trustly Direct Debit (TDD) is not enabled on the merchant's user in Trusty's system. If you want to use TDD, please reach out to your Trustly contact. |
| 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. |