Disbursement API

SeQura will periodically transfer money to the merchant for orders that have been confirmed in the checkout. This transfer is called the disbursement. For every disbursement, a Disbursement Report is generated in the back-office system and made available in 3 ways:

  • Web: The reports can be downloaded from the back-office system.
  • Email: Merchants can register email addresses to which the reports will be sent.
  • API: Merchants can fetch the information used to render the reports through the API described below.

In short, the Disbursement Report tells a merchant how much money to expect in each transfer and how that money relates to the orders that SeQura handles.

The Disbursement API consists of two calls, one to get the list of available disbursements and the other to get all the details about a single disbursement.

Report configuration

By default, disbursements are calculated and reported per order. For merchants that need information on a sub-order level, SeQura can generate the reports per shipment reference. This option must be activated by SeQura and allows the merchant to reconcile order payments on the level that makes most sense from a business perspective.

For an explanation of this option, see Using Shipment References.

Getting the list of available disbursements

Getting the list of available disbursement reports is a simple GET to the disbursements endpoint:

$ SQPASS='yourAccountKey:yourAccountSecret'
$ curl -i -u $SQPASS https://sandbox.sequrapi.com/merchants/yourMerchantName/disbursements

The reply contains a list of disbursements, each with their key data and a path that you can use to get more details. Note that the example has been reformatted for easier reading:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
...

[
  {
    "disbursement": {
      "issue_date": "2014-12-02",
      "to_date": "2014-11-16",
      "currency": "EUR",
      "disbursed_amount": 34234,
      "adjustments_with_tax": 0,
      "adjustments": [],
      "reference": "0000008mlHWOC",
      "path": "/merchants/yourMerchantName/disbursements/c6105f92-5718-4355-9f5b-56b24fe19baa"
    }
  },
  {
    "disbursement": {
      "issue_date": "2014-11-25",
      "to_date": "2014-11-09",
      "currency": "EUR",
      "disbursed_amount": 54212,
      "adjustments_with_tax": 1210,
      "reference": "0000008mkTH4s",
      "path": "/merchants/yourMerchantName/disbursements/1e8c4c63-3b24-40f5-bbbb-b264835ff40c"
    }
  },
  {
    "disbursement": {
      "issue_date": "2014-11-18",
      "to_date": "2014-11-02",
      "currency": "EUR",
      "disbursed_amount": 4186,
      "adjustments_with_tax": 0,
      "reference": "0000008bljHA9",
      "path": "/merchants/yourMerchantName/disbursements/95121fac-c438-42b6-9dab-653b62c91f84"
    }
  }
]

Each disbursement contains the following information:

Field Description
issue_date The date when this disbursement was issued. Disbursements become available immediately after they are issued.
to_date The disbursement does not include any orders that were shipped (for the first time) after this date.
currency The currency used by all orders in this disbursement.
reference Unique identifier for the disbursement. Used in the bank transfer's concept field.
path The path part of the URL to fetch the disbursement details.
disbursed_amount The total amount to be transfer in cents after fees, taxes and retentions.
adjustments_with_tax Manual adjustments, if they are present, they are already included in the total disbursement amount.
adjustments List of adjustments made for the disbursement
adjustments[].type

Type of the adjustment.

  • owed_by_merchant: Adjustments created from previous negative disbursements
  • fee: Adjustment created for incorrect or compensated fees
  • other: Adjustment that do not suit any of the previous cases.
adjustments[].amount Amount of the adjustment
adjustments[].tax_amount Tax amount of the adjustment
state State of the disbursement. See Notes in order to learn more about possible states.

Notes

  • There will only ever be one disbursement report per date and currency.
  • Disbursement reports older than 13 months are not guaranteed to be available through the API.
  • Possible states are:
    • in_review : The disbursement has been generated but must be reviewed by SeQura staff
    • publishing : The disbursement has been reviewed and is being published
    • published : The disbursement is published and it will be included in the next payment
    • disbursed : The disbursement has been transferred or processed (keep in mind that if the amount is negative, there won’t be any transfer)

Errors

As long as your credentials are valid for the merchant you are accessing, there will be no errors. If your password is incorrect, you will see

HTTP/1.1 401 Unauthorized
Content-Type: text/html; charset=utf-8
...

If your password is correct but you are trying to access data for a merchant that you do not control, you will see

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8

{
  "errors": [
    "You do not have access to this URL"
  ]
}

Getting disbursement details

A disbursement consists of a list of settlements. The settlements contain the data you need to keep track of which of the merchant’s orders have been fully paid by SeQura and which still are awaiting part of their payment.

Please note that the same order may have more than one settlement in the same disbursement.

$ curl -i -u $SQPASS -H 'Accept: application/json' \
  https://sandbox.sequrapi.com/merchants/yourMerchantName/disbursements/c6105f92-5718-4355-9f5b-56b24fe19baa

The reply contains the disbursement data plus the list of settlements. Note that the example has been reformatted for easier reading:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "disbursement": {
    "issue_date": "2014-12-02",
    "to_date": "2014-11-16",
    "currency": "EUR",
    "disbursed_amount": 29535,
    "adjustments_with_tax": 0,
    "adjustments": [],
    "reference": "0000008mlHWOC",
    "path": "/merchants/yourMerchantName/disbursements/c6105f92-5718-4355-9f5b-56b24fe19baa",
    "settlements": [
      {
        "order_ref_1": "100001126",
        "order_ref_2": null,
        "order_date": "2014-11-12",
        "amount_with_tax": 0,
        "cost_of_credit": "0.0",
        "maximum_amount_with_tax": 5094,
        "product_name": "i1",
        "fixed_fee": "0.0",
        "variable_fee": "0.35",
        "shopper_fee": "0.0",
        "fee_vat": "0.0735",
        "vat_percentage": "21.0",
        "retention": "0.0"
      },
      {
        "order_ref_1": "100001118",
        "order_ref_2": null,
        "order_date": "2014-11-11",
        "amount_with_tax": 3974,
        "cost_of_credit": "0.0",
        "maximum_amount_with_tax": 3974,
        "product_name": "i1",
        "fixed_fee": "0.0",
        "variable_fee": "0.35",
        "shopper_fee": "0.0",
        "fee_vat": "0.0735",
        "vat_percentage": "21.0",
        "retention": "0.0"
      },
      {
        "order_ref_1": "100001123",
        "order_ref_2": null,
        "order_date": "2014-11-11",
        "amount_with_tax": 25870,
        "cost_of_credit": "0.0",
        "maximum_amount_with_tax": 25870,
        "product_name": "i1",
        "fixed_fee": "0.0",
        "variable_fee": "0.35",
        "shopper_fee": "0.0",
        "fee_vat": "0.0735",
        "vat_percentage": "21.0",
        "retention": "0.0"
      }
    ]
  }
}

Each settlement contains the following fields:

Field Description
order_ref_1 The merchant's primary order id.
order_ref_2 The merchant's secondary order id. If no secondary order id has been assigned, the value is `null`.
order_date Order confirmation date.
amount_with_tax

The amount (in cents) which is settled through this settlement. A positive value corresponds with order value that has been delivered to the shopper, and SeQura will pay this amount to the merchant. A negative value corresponds with an order value that has been cancelled or returned from the shopper, and the value will be deducted from the sum of the positive values.

The value might be 0 in two cases:

  1. If the order was cancelled before being disbursed. Such orders will be included once in a disbursement report with a 0 value.
  2. If the order has been subject to _retention_ of part of its value and this retention is now being released. The 0 here signals that there has been no change in delivered order value, and the value in the `retention` field signals the amount being released.
cost_of_credit Cost of credit for the merchant non-taxable.
maximum_amount_with_tax The maximum value (in cents) that SeQura has registered for the order until the disbursement. This might be used to calculate service fees.
Note that this value is only guaranteed to be present in the first settlement for an order. Subsequent settlements might report null, meaning that SeQura has not recalculated its service cost for the order.
product name SeQura product name used for the order.
fixed_fee Applied fixed fee for the settlement.
variable_fee Applied variable fee for the settlement.
shopper_fee Shopper fee (excluding VAT) included in the cart.
fee_vat Applied VAT for all the fees.
vat_percentage VAT percentage applied to all the fees.
retention in some cases, SeQura will retain part of the order value until certain conditions are met. The retention has negative sign when applied and positive when released.
shipment_ref The shipment to which the settlement applies, if `shipment_ref` has been supplied by the merchant.
ticket_ref The ticket to which the settlement applies. Only used if `ticket_ref` has been supplied by the merchant.
shop_ref The (physical) shop to which the settlement applies. Only used if `ticket_ref` has been supplied by the merchant.

Notes

  • Future extensions to the API may add more fields, but those documented here will not change.
  • Disbursement reports older than 13 months are not guaranteed to be available through the API.
  • Derived amounts like fees and retention are expressed as strings with up to 8 decimal places.
  • The total amount transferred in a disbursement is the sum of all amount_with_tax and retention fields minus the value of all “fee” fields (fixed_fee, variable_fee, shopper_fee, fee_vat).
  • Partial or total cancellations that were paid to the merchant in previous disbursements, create a negative settlement to balance that payment.

Errors

You may see the same permissions-related errors as above, and also

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{"status":"404","error":"Not Found"}