logo
Trustly Docs
BETA

Batch file format

Updated 4 days ago

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.

DataDescriptionExample
Record separatorNew line or carriage return + newline, eg both unix and windows standard \n or \r\n\n
Separator charThis is the character used to separate the values, and should always be the comma char,
Escape charIf 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 charMostly for text blocks where eg a comma may be included. Everything within the quotations will be interpreted as the value for the column."
Decimal separatorFor all numeric values, always use the dot character as decimal separator.
Character setAlways use UTF-8 for the content in the file, even if non-ASCII is not to be used.UTF-8

CSV format

Please note that Trustly may add more columns to the right of this.

DataDescriptionTypeExample
TypeDescribes the instruction type, DEBIT or CREDITTextDEBIT
AccountIDThe mandate to be used. Note that for Bankgiro, this is not mandatory if one refers to an imported mandate.Text123123123
AmountThe amount for the instructionNumeric12.50
MessageIDA unique identifier for each chargeText123123
CollectionType[Bacs]: Only valid for BACS debit.TextINITIAL
ShopperStatementStatement that appear on the end users bank accountTextInvoice-23231
MandateMerchantReferenceThe mandate identificationText197012131234
EmailThe email address of the end user.Textjoe@example.com
NationalIDThe national identification number.Format is yyyyMMddxxxx. Only applicable for Bankgiro(SE)Text197105130355
EndUserIdFor CREDIT it’s required, for other types it will be ignored and taken from the mandate it self.Text12345678
FirstnameFor MANDATE it’s required, for other types it will be ignored.TextJohn
LastnameFor MANDATE it’s required, for other types it will be ignoredTextDoe
NotificationURLFor MANDATE it’s required and is which url we’ll notify changes on the mandate forTexthttps://example.trustly.com/notification/
ImportTypeFor MANDATE, as of now, only CREATE is possible for importing.TextCREATE
CountryFor MANDATE, the country for the mandateTextSE
MobilePhoneFor MANDATE, optionally add the debtors mobile phoneText+4670000000
AddressLine1For MANDATE, if the debtors address is available. Note that in SEPA, this is mandatoryTextRådmansgatan 40
AddressLine2For MANDATE, if eg building name etc is in the addressTextFantastic Building
AddressCityFor MANDATE, the city for the debtorTextStockholm
AddressPostalCodeFor MANDATE, the postal code of the debtorText113 12
AddressCountryFor MANDATE, the debtor’s countryTextSE
LocaleFor MANDATE, the debtor’s preferred locale.Textsv_SE


Bankgirot example

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_SE


BACS example

Debit

"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"

SDD example

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"

CSV Report format

DataDescriptionTypeExample
TypeDescribes the instruction typeTextDEBIT
AccountIDThe mandate to be usedText123123123
AmountThe amount for the chargeNumeric12.50
MessageIDA unique identifier for each chargeText123123123
CollectionType[Bacs]: Only valid for BACS debit.TextINITIAL
ShopperStatementStatement that appear on the end users bank accountTextInvoice-23231
MandateMerchantReferenceThe mandate identificationText197012131234
EmailThe email address of the end user.Textjohn@example.com
NationalIdThe national identification number. Format is yyyyMMddxxxx. Only applicable for Bankgiro(SE)Text197105130355
EndUserIdThe merchant’s identifier of the user.

[Sepa-DD] This field is limited to 35 characters
[BACS/Bankgiro] This field is limited to 63 characters
Text12345678
Report timestampThe instructions transition timestamp. Format yyyy-MM-ddTHH:mm:ss.SSSSSSZText2023-05-31T09:19:30.066773Z
StatusThe status of the instruction, either DONE or FAILEDTextDONE
FailureReasonIn case of failure status, a description of the failureText


Below are some example response files for different markets and should examplify 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",,,,,,,,,,,,,