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.. The TaxationItem-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. The TaxationItem-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. The TaxationItem-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. The TaxationItem-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 2000 for credit card purchases with a fee of 50 SEK and a tax for the fee 12.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.