Settlement Report
Read about the record type Settlement Report before going through the examples below.
The reportId must be unique and a Settlement Report can only contain data for one currency.
Fields
The following fields are used:
reportDay,reportId,currency- These fields are required. In the example the report will be for 2022-01-02 with the reportId=1. The reportId can contain any string as long as it is unique per reportDay.
The fields below are divided into four logical sections:
paid- Money transferred from Customer to PSP.refunded- Money transferred from Merchant to Customer.deposited- Money transferred from PSP to Merchant.credited- Money transferred from Merchant to PSP.
See more about the concept in Settlement Report
Paid
paidPerPaymentMethod- As the name suggest this is the paid amount per payment method. A reference is needed for the payment method that has been created in the integration platform e.g. the payment method must exist before the call.
totalPaid- A money object with the total paid amount. The value should equal the sum of the amounts in
paidPerPaymentMethod. paymentFeesPerPaymentMethod- An object that contains information about the fee amount and the tax for the fee related to starting a payment action. The information is defined per payment method.
totalPaymentFeeExclTax- An amount for the total fees for starting a payment action. The value should equal the sum of the amounts in
paymentFeesPerPaymentMethod. totalPaymentFeeTaxes- The total payment fees taxes per tax rate, should match sum of taxes in
paymentFeesPerPaymentMethod.. TheTaxationItem-model supports both VAT and sales tax. See Tax model for more information about the tax model.
Refunded
refundedPerPaymentMethod- As the name suggest this is the refunded amount per payment method. A reference is needed for the payment method that has been created in the integration platform e.g. the payment method must exist before the call.
totalRefunded- A money object with the total refunded amount. The value should equal the sum of the amounts in
refundedPerPaymentMethod. refundFeesPerPaymentMethod- An object that contains information about the fee amount and the tax for the fee related to refunds. The information is defined per payment method.
totalRefundFeeExclTax- An amount for the total fees for refunds. The value should equal the sum of the amounts in
refundedFeesPerPaymentMethod. totalRefundFeeTaxes- The total refund fees taxes per tax rate, should match sum of taxes in
refundFeesPerPaymentMethod. TheTaxationItem-model supports both VAT and sales tax. See Tax model for more information about the tax model.
Deposited
depositedPerPaymentMethod- As the name suggest this is the deposited amount per payment method. A reference is needed for the payment method that has been created in the integration platform e.g. the payment method must exist before the call.
totalDeposited- A money object with the total deposited amount. The value should equal the sum of the amounts in
depositedPerPaymentMethod. depositFeesPerPaymentMethod- An object that contains information about the fee amount and the tax for the fee related to deposits. The information is defined per payment method.
totalDepositFeeExclTax- An amount for the total fees for deposits. The value should equal the sum of the amounts in
depositFeesPerPaymentMethod. totalDepositFeeTaxes- The total deposit fees taxes per tax rate, should match sum of taxes in
depositFeesPerPaymentMethod. TheTaxationItem-model supports both VAT and sales tax. See Tax model for more information about the tax model.
Credited
creditedPerPaymentMethod- As the name suggest this is the credited amount per payment method. A reference is needed for the payment method that has been created in the integration platform e.g. the payment method must exist before the call.
totalCredit- A money object with the total credit amount. The value should equal the sum of the amounts in
creditedPerPaymentMethod. creditFeesPerPaymentMethod- An object that contains information about the fee amount and the tax for the fee related to starting a payment action. The information is defined per payment method.
totalCreditFeeExclTax- An amount for the total fees for starting a payment action. The value should equal the sum of the amounts in
creditFeesPerPaymentMethod. totalCreditFeeTaxes- The total payment fees taxes per tax rate, should match sum of taxes in
creditFeesPerPaymentMethod. TheTaxationItem-model supports both VAT and sales tax. See Tax model for more information about the tax model.
Example
Scenario
A Merchant makes some sales during a day and the customers pays with both credit cards and giftcards. A customer also make a return of a product. At the same day the payment provider (PSP) makes a payout (deposit) to the Merchants account but a fee is deducted from the payout.
The example below creates a report that represents the following events:
- Payments made by credit card for a total of
5000 SEK, there were no fees during these events. - Payments made by giftcard for a total of
1000 SEK, there were no fees during these events. - A total refund for credit card purchases of
500 SEK, there were no fees during these events. - The PSP deposited a total of
2000for credit card purchases with a fee of50 SEKand a tax for the fee12.50 SEK - there were no credits made in this example.
API-call
The call below represents the scenario described in the previous section.
Request body for the scenario above
{
"reportDay": "2022-01-01",
"reportId": "20220101-SEK-1",
"currency": "SEK",
"paidPerPaymentMethod": [
{
"paymentMethodId": "[payment method for credit card]",
"totalAmount": {
"currency": "SEK",
"amount": "5000.00",
"decimals": 2
}
},
{
"paymentMethodId": "[payment method for giftcard]",
"totalAmount": {
"currency": "SEK",
"amount": "1000.00",
"decimals": 2
}
}
],
"totalPaid": {
"currency": "SEK",
"amount": "6000.00",
"decimals": 2
},
"refundedPerPaymentMethod": [
{
"paymentMethodId": "[payment method for credit card]",
"totalAmount": {
"currency": "SEK",
"amount": "500.00",
"decimals": 2
}
}
],
"totalRefunded": {
"currency": "SEK",
"amount": "500.00",
"decimals": 2
},
"depositedPerPaymentMethod": [
{
"paymentMethodId": "[payment method for credit card]",
"totalAmount": {
"currency": "SEK",
"amount": "2000.00",
"decimals": 2
}
}
],
"totalDeposited": {
"currency": "SEK",
"amount": "2000.00",
"decimals": 2
},
"depositFeesPerPaymentMethod": [
{
"paymentMethodId": "[payment method for credit card]",
"totalExclTax": {
"currency": "SEK",
"amount": "50.00",
"decimals": 2
},
"taxes": [
{
"taxType": "vat",
"label": "Moms 25%",
"percentage": "25.00",
"taxableAmount": {
"currency": "SEK",
"amount": "50.00",
"decimals": 2
},
"tax": {
"currency": "SEK",
"amount": "12.50",
"decimals": 0
}
}
],
"totalAmount": {
"currency": "SEK",
"amount": "62.50",
"decimals": 2
}
}
],
"totalDepositFeeExclTax": {
"currency": "SEK",
"amount": "50.00",
"decimals": 2
},
"totalDepositFeeTaxes": [
{
"taxType": "vat",
"label": "Moms 25%",
"percentage": "25.00",
"taxableAmount": {
"currency": "SEK",
"amount": "50.00",
"decimals": 2
},
"tax": {
"currency": "SEK",
"amount": "12.50",
"decimals": 0
}
}
]
}
Example with curl
$ curl \
-u '<USERNAME>':'<PASSWORD>' \
-F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
-H 'X-Tenant: <TENANT CODE>' \
-H 'X-ConnectionId: <CONNECTION ID>' \
https://api.{HOSTNAME}/api/settlementreport \
-XPOST \
-d \
'{
"reportDay": "2022-01-01",
"reportId": "20220101-SEK-1",
"currency": "SEK",
"paidPerPaymentMethod": [
{
"paymentMethodId": "[payment method for credit card]",
"totalAmount": {
"currency": "SEK",
"amount": "5000.00",
"decimals": 2
}
},
{
"paymentMethodId": "[payment method for giftcard]",
"totalAmount": {
"currency": "SEK",
"amount": "1000.00",
"decimals": 2
}
}
],
"totalPaid": {
"currency": "SEK",
"amount": "6000.00",
"decimals": 2
},
"refundedPerPaymentMethod": [
{
"paymentMethodId": "[payment method for credit card]",
"totalAmount": {
"currency": "SEK",
"amount": "500.00",
"decimals": 2
}
}
],
"totalRefunded": {
"currency": "SEK",
"amount": "500.00",
"decimals": 2
},
"depositedPerPaymentMethod": [
{
"paymentMethodId": "[payment method for credit card]",
"totalAmount": {
"currency": "SEK",
"amount": "2000.00",
"decimals": 2
}
}
],
"totalDeposited": {
"currency": "SEK",
"amount": "2000.00",
"decimals": 2
},
"depositFeesPerPaymentMethod": [
{
"paymentMethodId": "[payment method for credit card]",
"totalExclTax": {
"currency": "SEK",
"amount": "50.00",
"decimals": 2
},
"taxes": [
{
"taxType": "vat",
"label": "Moms 25%",
"percentage": "25.00",
"taxableAmount": {
"currency": "SEK",
"amount": "50.00",
"decimals": 2
},
"tax": {
"currency": "SEK",
"amount": "12.50",
"decimals": 0
}
}
],
"totalAmount": {
"currency": "SEK",
"amount": "62.50",
"decimals": 2
}
}
],
"totalDepositFeeExclTax": {
"currency": "SEK",
"amount": "50.00",
"decimals": 2
},
"totalDepositFeeTaxes": [
{
"taxType": "vat",
"label": "Moms 25%",
"percentage": "25.00",
"taxableAmount": {
"currency": "SEK",
"amount": "50.00",
"decimals": 2
},
"tax": {
"currency": "SEK",
"amount": "12.50",
"decimals": 0
}
}
]
}'
Accounting
The settlement report can be used as a source for automatic accounting. The integration platform contains connectors to multiple accounting systems and ERP-systems, where the connector can be configured to book each amount to the correct account. The tutorial for Payment Transactions contains example for how the information can be used for accounting.
Note
The settlement report can contain information that is not related to an orders payment transactions. An example is when a PSP adds a fee that is not directly related to an order. The settlement report does not require that orders exists in the integration platform since there are no internal relation between settlement report and orders or payment transaction.