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:

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:

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