.CSV settlement report documentation
This section describes the structure and content of the .CSV Report
Introduction
The CSV format is designed to automate the reconciliation of payment transactions.
Note: Amounts are not in cents as in the API (e.g. amount from the API as 400 is presented as 4.00 in the .csv report)
File format - Content and Lines
The first column shows what kind of line it is. The possible lines are:
H-SE - Header for Settlement lines - Listing of all columns that will be included in SE - Settlement rows in this file.
H-PA - Header for Payment lines - Listing of all columns that will be included in PA - Payments rows in this file.
H-PO - Header for Payment Operations - Listing of all columns that will be included in PO - Payment Operation rows in this file.
SE - Settlements
Settlements are the funds that has been paid out to your bank account. It includes e.g. the amount that has been paid out and the transaction message equivalent to what you will see on your bank statements.
The settlement amount paid out is the sum of the PO:s (payment operations) amounts for CAPTURE and REFUND operations, and deducted potential transactions fees.
For full description of the Settlements line, see settlements table below.
PA - Payments
The settlement contains one or multiple Payments. The payment is the same as in the payment generated when you initiate a payment request towards the API platform.
For full description of the Payment line, see payments table below.
PO - Payment Operations
The payment operations is the operations made to the specific payment. The CSV report contain the most important operations that affect the settlement, such as CAPTURE and REFUND.
There can be multiple operations for a Payment.
Each CSV report contains one Settlement and only Payment Operations relevant for that Settlement, as well as the Payment that is parent for each Payment Operation. A Payment can therefore appear in multiple Settlements. E.g. if one Settlement contains a CAPTURE Payment Operation for a certain Payment and a later Settlement contains a REFUND Payment Operation for the same Payment.
For full description of the Payment Operations line, see payment operations table below.
File format message structure
Pass includeHeaders=true as a query parameter to include column headers at the beginning of the file.
The file format is structured as follows (optional when includeHeaders=true)
(Optional) H-SE(Optional) H-PA(Optional) H-POSE PA PO PO ... PA PO ...File message components
Settlement components
| Field name | Field description | Field Length |
|---|---|---|
| SE | Line type of settlement | String, 2 |
| payoutReference | Unique reference for the payout | String |
| marketCountryCode | Market country code (configured for the bank account) | String |
| currencyCode | Payout currency (ISO 4217) | String,3 |
| amount | The amount paid out to your account | Decimal |
| transactionMessage | Transaction message visible on your bank statement. Structured as the first 7 characters of the payoutReference + PAYER. This is to include a reference to the unique payoutReference that is to long for your bank to handle + the reference to PAYER so that you easily can locate from who the funds are from. E.g. "hya0373 PAYER" Note: Your bank might limit the length of this message and can cut off parts of the message. | String |
| bookingDate | The date funds was booked debited on Payer's bank account | Date |
| valueDate | The date funds was released from Payer's bank account | Date |
| payoutDate | The date Payout request was sent to the bank. | Date |
| schemeTotalFeeExcludingVat | Total card specific scheme fees for the transactions excluding Vat | Decimal |
| interchangeTotalFeeExcludingVat | Total card specific interchange fees for the transactions excluding Vat | Decimal |
| payerTotalFeeExcludingVat | Total fees deducted by Payer | Decimal |
| feeVatPercentage | Vat percentage for the fees (0 if reverse charge applies) | Decimal |
| totalFeesExcludingVat | The settlement total sum of all fees (above) | Decimal |
| totalFeesVatAmount | The settlement total Vat amounts for the Fees. | Decimal |
Payment components
| Field name | Field description | Field Length |
|---|---|---|
| PA | Line type for payments | String, 2 |
| id | The payment Id | Integer |
| uniqueId | The unique Id | String |
| initialAmount | The amount of the transaction when initiated | Decimal |
| externalPaymentReference | Your external payment reference when initiating the payment | String, max 40, min 0 |
| additionalReference | Your external payment reference when initiating the payment (optional) | String, max 40 min 0 |
| currencyCode | Payment Currency (ISO 4217) | String, 3 |
| type | Type of payment method (e.g. CARD, BANK etc.) | String |
Payment operation components
| Field name | Field description | Field Length |
|---|---|---|
| PO | Line type for payment operations | String, 2 |
| type | The type of operation CAPTURE: Captured funds for a payment REFUND: Refunded funds amount for a payment | String |
| amount | Amount of the operation Note: Can differ from the payment amount | Decimal |
| createdDate | Date when operation was created | Date |
| operationId | The id of the operation | String |
| expiryDate | Card specific expiry date for payment operations with Type=AUTH | Date |
| description | Your transactionDescription sent in when you Capture or Refund a payment | String |
| schemeTotalFeeExcludingVat | Card specific scheme fees for the transaction excluding Vat | Decimal |
| interchangeTotalFeeExcludingVat | Card specific interchange fee for the transaction excluding Vat | Decimal |
| payerTotalFeeExcludingVat | Payer Fee for the transaction excluding Vat | Decimal |
| feeVatPercentage | The Fee vat percentage | Decimal |
| cardSchemeName | Name of card scheme | String |
| cardUsage | Type of card | String |
| cardCategory | Card category | String |
| interchangeDomain | Card interchange domain | String |
| countryIssuer | Card country issuer, as an ISO 3166 numeric code | Integer |
File processing considerations
Note that we may add or remove fields from the CSV files in the future. When parsing a CSV file, we therefore advice you to use the header rows to identify which fields that are included for each row type in that particular file. I.e., on the H-SE row, if the first field after H-SE is payoutReference, then when parsing an SE row later, you should parse the first field after SE as payoutReference. Parsing this way will ensure that you will be able to parse files even if a field is added or removed.
Example file
Example file including headers (optional when includeHeaders=true)
H-SE,payoutReference,marketCountryCode,currencyCode,amount,transactionMessage,bookingDate,valueDate,payoutDate,schemeTotalFeeExcludingVat,interchangeTotalFeeExcludingVat,payerTotalFeeExcludingVat,feeVatPercentage,totalFeesExcludingVat,totalFeesVatAmountH-PA,id,uniqueId,initialAmount,externalPaymentReference,additionalReference,currencyCode,typeH-PO,type,amount,createdDate,operationId,expiryDate,description,schemeTotalFeeExcludingVat,interchangeTotalFeeExcludingVat,payerTotalFeeExcludingVat,feeVatPercentage,cardSchemeName,cardUsage,cardCategory,interchangeDomain,countryIssuerSE,5q4qsr24-kkn7-u8wy-4naw-veu04zx50rew,SE,SEK,4.00,5q4qsr2 PAYER,,,2021-04-08,0.96892300,0.00000000,0.01750000,25.00,0.99,0.01PA,3,e2b4ed44-0643-4679-8ec1-20f685f7859f,1.00,e714418c-29b6-475a-9f23-89b182cdae10,,SEK,CARDPO,CAPTURE,1.00,2021-04-08T09:58:02.096+02:00,318200920,,description,0.29688800,0.00000000,0.00250000,25.00,Mastercard,Debit,Consumer,Domestic,752PO,REFUND,1.00,2021-04-08T09:58:02.096+02:00,318202986,,,0.07290000,0.00000000,0.00250000,25.00PA,2,c4b28af0-a4ef-4537-8ca9-c131a091a60c,1.00,6b20781b-f633-43fb-9939-4f72f36ca1c8,,SEK,CARDPO,CAPTURE,1.00,2021-04-08T09:58:02.091+02:00,318974698,,description,0.29888900,0.00000000,0.00250000,25.00,Mastercard,Debit,Consumer,Domestic,752PA,1,cc5dab49-78f5-4f9e-aed7-d82a82005b74,4.00,5a596726-77f5-49f0-8e05-5c1d878acaef,,SEK,CARDPO,CAPTURE,4.00,2021-04-08T09:58:02.087+02:00,318975666,,description,0.30024600,0.00000000,0.01000000,25.00,Mastercard,Debit,Consumer,Domestic,752