Disbursement API

seQura periodically transfers money to you for confirmed orders. This transfer is called a disbursement. Each disbursement generates a Disbursement Report, available in 3 ways:

Web: Download from the back-office system.
Email: Register email addresses to receive reports.
API: Fetch report data via the API described below.

The Disbursement Report tells you how much to expect in each transfer and how it relates to your orders.

The Disbursement API has two calls: one to list available disbursements, and one to get details for a single disbursement.

Report configuration

By default, disbursements are calculated per order. If you need sub-order level information, seQura can generate reports per shipment reference. Contact seQura to activate this option—it lets you reconcile payments at the level that makes most business sense.

See Using Shipment References for details.

Getting the list of available disbursements

Make a GET request to the disbursements endpoint:

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

The response contains a list of disbursements with key data and a path for details. (Example reformatted for readability.)

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

If your credentials are valid for the merchant, there are no errors. With an incorrect password:

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

If your password is correct but you're accessing a merchant you don't control:

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 settlements. Settlements show which orders seQura has fully paid and which are awaiting partial payment.

Note: the same order may have multiple settlements 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 response contains disbursement data plus settlements. (Example reformatted for readability.)

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: If the order was cancelled before being disbursed. Such orders will be included once in a disbursement report with a 0 value. 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"}