The file-format used via SFTP is Comma Separated Values (CSV) which is a standard widely used. It’s however important to care about the character-set as well as separators etc, the table below describes what to use.
| Data | Description | Example |
|---|---|---|
| Record separator | New line or carriage return + newline, eg both unix and windows standard \n or \r\n | \n |
| Separator char | This is the character used to separate the values, and should always be the comma char | , |
| Escape char | If for any reason a comma must be used in any value, the char must be escaped so that it’s not interpreted as a separator. The escape char is the back-slash character | \ |
| Quotation char | Mostly for text blocks where eg a comma may be included. Everything within the quotations will be interpreted as the value for the column. | " |
| Decimal separator | For all numeric values, always use the dot character as decimal separator | . |
| Character set | Always use UTF-8 for the content in the file, even if non-ASCII is not to be used. | UTF-8 |
Please note that Trustly may add more columns to the right of this.
| Data | Description | Type | Example |
|---|---|---|---|
| Type | Describes the instruction type, DEBIT or CREDIT | Text | DEBIT |
| AccountID | The mandate to be used. Note that for Bankgiro, this is not mandatory if one refers to an imported mandate. | Text | 123123123 |
| Amount | The amount for the instruction | Numeric | 12.50 |
| MessageID | A unique identifier for each charge | Text | 123123 |
| CollectionType | [Bacs]: Only valid for BACS debit. | Text | INITIAL |
| ShopperStatement | Statement that appear on the end users bank account | Text | Invoice-23231 |
| MandateMerchantReference | The mandate identification | Text | 197012131234 |
| The email address of the end user. | Text | joe@example.com | |
| NationalID | The national identification number.Format is yyyyMMddxxxx. Only applicable for Bankgiro(SE) | Text | 197105130355 |
| EndUserId | For CREDIT it’s required, for other types it will be ignored and taken from the mandate it self. | Text | 12345678 |
| Firstname | For MANDATE it’s required, for other types it will be ignored. | Text | John |
| Lastname | For MANDATE it’s required, for other types it will be ignored | Text | Doe |
| NotificationURL | For MANDATE it’s required and is which url we’ll notify changes on the mandate for | Text | https://example.trustly.com/notification/ |
| ImportType | For MANDATE, as of now, only CREATE is possible for importing. | Text | CREATE |
| Country | For MANDATE, the country for the mandate | Text | SE |
| MobilePhone | For MANDATE, optionally add the debtors mobile phone | Text | +4670000000 |
| AddressLine1 | For MANDATE, if the debtors address is available. Note that in SEPA, this is mandatory | Text | Rådmansgatan 40 |
| AddressLine2 | For MANDATE, if eg building name etc is in the address | Text | Fantastic Building |
| AddressCity | For MANDATE, the city for the debtor | Text | Stockholm |
| AddressPostalCode | For MANDATE, the postal code of the debtor | Text | 113 12 |
| AddressCountry | For MANDATE, the debtor’s country | Text | SE |
| Locale | For MANDATE, the debtor’s preferred locale. | Text | sv_SE |
Debit
"Type","AccountID","Amount","MessageID","CollectionType","ShopperStatement","MandateMerchantReference","Email","NationalID","EndUserId"
"DEBIT","1231",125.50,"ClientTxId-1",,"Faktura-1234","merchantRef-1","joe1@trustly.com","197012131231","MyUser-1"
"DEBIT","1232",388.50,"ClientTxId-2",,"Faktura-1235","merchantRef-2","joe2@trustly.com","197012131232","MyUser-1"
"DEBIT","1233",388.50,"ClientTxId-4",,"Faktura-1235","merchantRef-2","joe3@trustly.com","197012131232","MyUser-1"
Credit
"DEBIT","12312313",12.50,"ClientTxId1",,"Faktura-1234","197012131231","joe@example.com","197012131231","MyUserJoe"
"DEBIT","12312314",21.00,"ClientTxId2",,"Faktura-2345","ClientTxId2","197012131232","joe@example.com","197012131232","MyUserJoe"
"DEBIT","12312315",39.70,"ClientTxId3",RECURRING,"Invoice-3456","ClientTxId3"
"DEBIT","12312316",99.10,"ClientTxId4",,"Invoice-5678","ClientTxId4"
"CREDIT","12312313",9.50,"ClientTxId5",INITIAL,"Invoice-8901","ClientTxId5","joe@example.com",,"1234567"
Mandate
"Type","AccountID","Amount","MessageID","CollectionType","ShopperStatement","MandateMerchantReference","Email","NationalID","EndUserId","Firstname","Lastname","NotificationURL","ImportType","Country","MobilePhone","AddressLine1","AddressLine2","AddressCity","AddressPostalCode","AddressCountry","Locale"
"MANDATE",,,"ClientTxId-1",,,"merchantRef-1","john-1@example.com","197012131231","John-1","John","Doh","https://example.trustly.com/notification/merchantRef-1","CREATE",,"SE","+46703000000","Rådmansgatan 40",,"Stockholm","113 57,"SE","sv_SE"
"MANDATE",,,"ClientTxId-2",,,"merchantRef-2","john-2@example.com","197012131232","John-2","John","Doh","https://example.trustly.com/notification/merchantRef-2","CREATE",,"SE","+46703000000","Rådmansgatan 40",,"Stockholm","113 57,"SE","sv_SE"
"MANDATE",,,"ClientTxId-3",,,"merchantRef-3","john-3@example.com","197012131233","John-3","John","Doh","https://example.trustly.com/notification/merchantRef-3","CREATE",,"SE","+46703000000","Rådmansgatan 40",,"Stockholm","113 57,"SE","sv_SEDebit
"DEBIT","12312313",12.50,"345678901",INITIAL,"Invoice-1234","reference1"
"DEBIT","12312314",21.00,"345678902",,"Invoice-2345","reference2"
"DEBIT","12312315",39.70,"345678903",RECURRING,"Invoice-3456","reference3"
"DEBIT","12312316",99.10,"345678904",,"Invoice-5678","reference4"
"CREDIT","12312313",9.50,"345678901",INITIAL,"Invoice-8901","reference5","joe@example.com",,"1234567"
Credit
"Type","AccountID","Amount","MessageID","CollectionType","ShopperStatement","MandateMerchantReference","Email","NationalID","EndUserId"
"CREDIT","1231",88.50,"ClientTxId-1",,"Refund-invoice-1231","merchantRef-1","joe-1@trustly.com",,"Joe-1"
"CREDIT","1232",188.50,"ClientTxId-2",,"Refund-invoice-1232","merchantRef-2","joe-2@trustly.com",,"Joe-2"
"CREDIT","1233",388.50,"ClientTxId-3",,"Refund-invoice-1233","merchantRef-3","joe-3@trustly.com",,"Joe-3"
Mandate
"Type","AccountID","Amount","MessageID","CollectionType","ShopperStatement","MandateMerchantReference","Email","NationalID","EndUserId","Firstname","Lastname","NotificationURL","ImportType","Country","MobilePhone","AddressLine1","AddressLine2","AddressCity","AddressPostalCode","AddressCountry","Locale"
"MANDATE",,,"ClientTxId-1",,,"merchantRef-1","john-1@example.com",,"John-1","John","Doh","https://example.trustly.com/notification/merchantRef-1","CREATE",,"GB","+44703000000"," 80 Clerkenwell Rd",,"London","EC1M 5RJ,"GB","en_GB"
"MANDATE",,,"ClientTxId-2",,,"merchantRef-2","john-2@example.com",,"John-2","John","Doh","https://example.trustly.com/notification/merchantRef-2","CREATE",,"GB","+44703000001"," 80 Clerkenwell Rd",,"London","EC1M 5RJ,"GB","en_GB"
"MANDATE",,,"ClientTxId-3",,,"merchantRef-3","john-3@example.com",,"John-3","John","Doh","https://example.trustly.com/notification/merchantRef-3","CREATE",,"GB","+44703000002"," 80 Clerkenwell Rd",,"London","EC1M 5RJ,"GB","en_GB"Debit
"Type","AccountID","Amount","MessageID","CollectionType","ShopperStatement","MandateMerchantReference","Email","NationalID","EndUserId"
"DEBIT","1231",125.50,"ClientTxId-1",,"Invoice-1234","merchantRef-1","john.doh-1@trustly.com",,"John-1"
"DEBIT","1232",388.50,"ClientTxId-2",,"Your insurance-1234","merchantRef-2","john.doh-2@trustly.com",,"John-2"
"DEBIT","1233",388.50,"ClientTxId-3",,"Payment for TV, receipt 1231231","merchantRef-3","john.doh-3@trustly.com",,"John-3"
Credit
"Type","AccountID","Amount","MessageID","CollectionType","ShopperStatement","MandateMerchantReference","Email","NationalID","EndUserId"
"CREDIT","1231",88.50,"ClientTxId-1",,"Re-payment-invoice-1231","merchantRef-1","joe-1@trustly.com",
"CREDIT","1232",188.50,"ClientTxId-2",,"Re-payment-invoice-1232","merchantRef-2","joe-2@trustly.com",,"Joe-2"
"CREDIT","1233",388.50,"ClientTxId-3",,"Re-payment-invoice-1233","merchantRef-3","joe-3@trustly.com",,"Joe-3"
Mandate
"Type","AccountID","Amount","MessageID","CollectionType","ShopperStatement","MandateMerchantReference","Email","NationalID","EndUserId","Firstname","Lastname","NotificationURL","ImportType","Country","MobilePhone","AddressLine1","AddressLine2","AddressCity","AddressPostalCode","AddressCountry","Locale"
"MANDATE",,,"ClientTxId-1",,,"merchantRef-1","john-1@example.com",,"John-1","John","Doh","https://example.trustly.com/notification/merchantRef-1","CREATE",,"FR","+33703000000","12 Rue Godot de Mauroy",,"Paris","75009,"FR","fr_FR"
"MANDATE",,,"ClientTxId-2",,,"merchantRef-2","john-2@example.com",,"John-2","John","Doh","https://example.trustly.com/notification/merchantRef-2","CREATE",,"IT","+39703000001","Some street",,"Italy","123 123,"IT","it_IT"
"MANDATE",,,"ClientTxId-3",,,"merchantRef-3","john-3@example.com",,"John-3","John","Doh","https://example.trustly.com/notification/merchantRef-3","CREATE",,"DE","+49703000002","Kaiser-Wilhelm-Ring 40",,"Köln","50672,"DE","de_DE"| Data | Description | Type | Example |
|---|---|---|---|
| Type | Describes the instruction type | Text | DEBIT |
| AccountID | The mandate to be used | Text | 123123123 |
| Amount | The amount for the charge | Numeric | 12.50 |
| MessageID | A unique identifier for each charge | Text | 123123123 |
| CollectionType | [Bacs]: Only valid for BACS debit. | Text | INITIAL |
| ShopperStatement | Statement that appear on the end users bank account | Text | Invoice-23231 |
| MandateMerchantReference | The mandate identification | Text | 197012131234 |
| The email address of the end user. | Text | john@example.com | |
| NationalId | The national identification number. Format is yyyyMMddxxxx. Only applicable for Bankgiro(SE) | Text | 197105130355 |
| EndUserId | The merchant’s identifier of the user. [Sepa-DD] This field is limited to 35 characters [BACS/Bankgiro] This field is limited to 63 characters | Text | 12345678 |
| Report timestamp | The instructions transition timestamp. Format yyyy-MM-ddTHH:mm:ss.SSSSSSZ | Text | 2023-05-31T09:19:30.066773Z |
| Status | The status of the instruction, either DONE or FAILED | Text | DONE |
| FailureReason | In case of failure status, a description of the failure | Text |
Below are some example response files for different markets and should exemplify how the response looks.
"Type","AccountID","Amount","MessageID","CollectionType","ShopperStatement","MandateMerchantReference","Email","NationalID","EndUserId","","","ReportTimestamp","Status","FailureReason","BankExecutionDay","First\
name","Lastname","NotificationURL","ImportType","Country","MobilePhone","AddressLine1","AddressLine2","AddressCity","AddressPostalCode","AddressCountry","Locale"
"MANDATE",,,"ClientTxId-1",,,"merchantRef-1","john-1@example.com","197012131231","John-1","2023-05-31T09:19:30.066773Z","DONE","","2023-05-31","John","Doh","https://example.trustly.com/notification/merchantRef-\
1","CREATE",,"SE","+46703000000","Rådmansgatan 40",,"Stockholm","113 57,"SE","sv_SE"
"DEBIT",12312312,10.40,"ClientTxId-1",,"Faktura-1","merchantRef-1","john-1@example.com","197012131231","John-1","2023-05-31T09:19:30.066773Z","DONE","","2023-05-31",,,,,,,,,,,,,
"DEBIT",12312312,10.40,"ClientTxId-1",,"Faktura-1","merchantRef-1","john-1@example.com","197012131231","John-1","2023-05-31T09:19:30.066773Z","FAILED","TK82_1(INSUFFICIENT FUNDS)","2023-05-31",,,,,,,,,,,,,