# Get order status

This endpoint allows you to get order information for one transaction. The request can be configured to only return the data that is necessary for your specific use case.

Endpoint: GET /order/status/v2/transactions/{transaction-id}
Version: version 1
Security: Bearer Authentication

## Header parameters:

  - `Content-Type` (string, required)
    Example: "application/json"

  - `Authorization` (string, required)
    For each request, a valid access token must be provided in the Authorization header. See Authentication API for obtaining a valid token.

## Path parameters:

  - `transaction-id` (string, required)
    The transaction id of the order for which the order status is requested. (The Ratepay Payment API returns this when an order is created.)
    Example: "12-3456789123456789"

## Query parameters:

  - `include` (array)
    Comma separated list of strings. Each string identifies one block of information (e.g. basket information) that should be included in the response. If this parameter is missing, only basic order information are returned.Allowed values are (use comma to request more than one):
- payment_status
- payment_method
- dunning_status
- basket
- all = include all available data
    Example: ["all"]

## Response 200 fields (application/json;charset=UTF-8):

  - `general_order_information` (object)
    These attributes are always returned if a valid request is sent.

  - `general_order_information.transaction_id` (string)
    The transaction id as specified in the URL
    Example: "12-3456789123456789"

  - `general_order_information.shop_order_id` (string)
    The order id as transmitted by the shop to the Ratepay Payment API. Is null if the shop does not provide this information in the checkout process.
    Example: "test-shop-order-id"

  - `general_order_information.order_creation_date` (string)
    Timestamp of the Payment Request for this order (ISO 8601, YYYY-MM-DDThh:mm:ss.ffffff+hh:mm).
    Example: "2020-03-10T18:06:52.438+01:00"

  - `general_order_information.shop_buyer_id` (string)
    The buyer id as transmitted by the shop to the Ratepay Payment API. Is null if the shop does not provide this information in the checkout process.
    Example: "test-shop-buyer-id"

  - `general_order_information.currency` (string)
    The currency of the current order, e.g. EUR (ISO 4217 alphabetic currency code, 3 chars). All currency fields in the response hold values of this currency.
    Example: "EUR"

  - `basket` (object)
    This object is returned if include contains basket

  - `basket.initial_order_amount_gross` (number)
    The initial basket order amount including tax before any changes, refunds, cancellations. Only the basket is considered here. Separate Ratepay buyer fees are not included.
    Example: 170

  - `basket.current_order_amount_gross` (number)
    The current basket order amount including tax. Changes, refunds, cancellations are considered. Only the basket is considered here. Separate Ratepay buyer fees are not included.
    Example: 145

  - `basket.last_updated` (string)
    Timestamp that shows when the basket was last modified by the shop calling the Ratepay Payment API (ISO 8601, YYYY-MM-DDThh:mm:ss.ffffff+hh:mm)
    Example: "2020-03-12T18:06:52.438+01:00"

  - `basket.current_items` (array)
    A list containing all current items in their respective shipping status. For marketplaces this is a list of all shops that are part of the basket. For single shops this list only contains one element.

  - `basket.current_items.shop_id` (string)
    The id of the marketplace shop as provided by the marketplace through the Ratepay Payment API. In case of a single shop and not a marketplace this attribute is null.
    Example: "external-shop-id"

  - `basket.current_items.shop_items` (object)
    An object containing all items of the shop in their respective shipping status.

  - `basket.current_items.shop_items.open_items` (array)
    List of all items that are not yet shipped or processed in any other way.

  - `basket.current_items.shop_items.open_items.unit_price_gross` (number)
    The gross price (i. e. incl. tax) for one unit of this item as provided by the shop through the Ratepay Payment API.
    Example: 48

  - `basket.current_items.shop_items.open_items.tax_rate` (number)
    The tax rate in percent (e. g. 19.0) for this item as provided by the shop through the Ratepay Payment API
    Example: 19

  - `basket.current_items.shop_items.open_items.discount` (number)
    An item specific discount amount, not a percentage, but the actual calculated value as provided by the shop through the Ratepay Payment API. This attribute is either 0 or has a negative value.

  - `basket.current_items.shop_items.open_items.quantity` (integer)
    The quantity of this item in the basket as provided by the shop through the Ratepay Payment API
    Example: 3

  - `basket.current_items.shop_items.open_items.description` (string)
    The item description as provided by the shop through the Ratepay Payment API.
    Example: "basket-item"

  - `basket.current_items.shop_items.open_items.additional_description` (string)
    Optional. Additional item description as provided by the shop through the Ratepay Payment API.
    Example: "cooles basket-item"

  - `basket.current_items.shop_items.open_items.identification_number` (string)
    The shop's identification number for this item as provided by the shop through the Ratepay Payment API
    Example: "identifiy-me"

  - `basket.current_items.shop_items.open_items.unique_identification_number` (string)
    Optional. The shop's unique identification number for this item as provided by the shop through the Ratepay Payment API.
    Example: "12345"

  - `basket.current_items.shop_items.shipped_items` (array)
    List of all items that are shipped and not returned or cancelled.

  - `basket.current_items.shop_items.returned_items` (array)
    List of all returned items.

  - `basket.current_items.shop_items.cancelled_items` (array)
    List of all cancelled items.

  - `basket.current_special_items` (object)
    An object containing all current special items (e. g. shipping fees) in their respective shipping status. Even in case of a marketplace special items apply to the basket as a whole and not a single shop

  - `basket.current_special_items.open_items` (array)
    List of all special items that are not yet shipped or processed in any other way.

  - `basket.current_special_items.open_items.type` (string)
    The type of this special item. Possible values:- DISCOUNT = discount that is applied to the basket as a whole- SHIPPING = shipping costs
    Example: "SHIPPING"

  - `basket.current_special_items.open_items.price_gross` (number)
    The gross price (i. e. incl. tax) for this special item as provided by the shop through the Ratepay Payment API.
    Example: 1

  - `basket.current_special_items.open_items.tax_rate` (number)
    The tax rate in percent (e. g. 19.0) for this special item as provided by the shop through the Ratepay Payment API.
    Example: 19

  - `basket.current_special_items.shippedItems` (array)
    List of all special items that are shipped and not returned or cancelled.

  - `basket.current_special_items.returnedItems` (array)
    List of all returned special items.

  - `basket.current_special_items.cancelledItems` (array)
    List of all cancelled special items.

  - `payment_information` (object)
    These fields are returned if include contains atleast one of these values:payment_status, dunning_status, payment_method

  - `payment_information.maximum_processing_offset_in_hours` (integer)
    Events such as bank transfers need time to be processed inside Ratepay's systems. E.g. it takes some time before a received bank transfer is assigend to the order it belongs to. This field shows the maximum time in hours the processing for any information in this block could take. That means that events that occured in the last maximum_processing_offset_in_hours hours may or may not be represented in the API response.

  - `payment_information.payment_method` (object)
    This object is only part of the response if include contains payment_method.

  - `payment_information.payment_method.current_payment_method_details` (object)

  - `payment_information.payment_method.current_payment_method_details.prepayment` (object)
    This is only part of the response if a prepayment exists, i. e. if payment_method is PREPAYMENT.

  - `payment_information.payment_method.current_payment_method_details.prepayment.reference` (string)
    The reference for this prepayment.
    Example: "test-ref"

  - `payment_information.payment_method.current_payment_method_details.prepayment.reservation_end_date` (string)
    The date until which the prepayment has to be fully paid by the shopper (ISO 8601, YYYY-MM-DD).
    Example: "2020-03-24"

  - `payment_information.payment_method.current_payment_method_details.prepayment.amount` (number)
    The original amount that the prepayment was created for.
    Example: 170

  - `payment_information.payment_method.current_payment_method_details.prepayment.creation_date` (string)
    The date at which the prepayment was created at Ratepay (ISO 8601, YYYY-MM-DD).
    Example: "2020-03-10"

  - `payment_information.payment_method.current_payment_method_details.invoices` (array)
    A list of all currently active invoices of the current order. This is only part of the response if atleast one invoice exists. Most of the time this is only returned if payment_method is INVOICE. This list only contins more than one entry if more than one shipment for the order exists.

  - `payment_information.payment_method.current_payment_method_details.invoices.reference` (string)
    The Ratepay reference for this order, i. e. the reference that should be used when paying. This is always the same for all invoices of one order.
    Example: "test-ref"

  - `payment_information.payment_method.current_payment_method_details.invoices.amount` (number)
    The original amount that this invoice is created for. This amount is not changed after returns and cancellations. For the current claim amount refer to payment_status
    Example: 170

  - `payment_information.payment_method.current_payment_method_details.invoices.original_due_date` (string)
    The original due date for this invoice.
    Example: "2020-03-24"

  - `payment_information.payment_method.current_payment_method_details.invoices.current_due_date` (string)
    The current due date for this invoice. This only differs from original_due_date if the due date was moved by booking Pay Later (Pay Later is a separate Ratepay product and has to be explicitly configured for a shop).
    Example: "2020-03-24"

  - `payment_information.payment_method.current_payment_method_details.invoices.creation_date` (string)
    The date when the invoice was created at Ratepay, i. e. the date that the corresponding claim was created (ISO 8601, YYYY-MM-DD).
    Example: "2020-03-10"

  - `payment_information.payment_method.current_payment_method_details.invoices.clearing_reference_number` (string)
    The clearing reference as shown in the clearing file. This is the unique identifier for each invoice.
    Example: "test-clear-ref"

  - `payment_information.payment_method.current_payment_method_details.invoices.invoice_number` (string)
    Optional. The invoice number that is displayed on the physical invoice that the shopper receives. This is only available after items are shipped and only if the shop and not Ratepay creates the invoice and transmits this invoice_number to Ratepay.
    Example: "test-shop-invoice-id"

  - `payment_information.payment_method.current_payment_method_details.payment_method` (string)
    The payment method for the current order. Possible values:- INVOICE (including product 'Invoice' and 'Direct Debit' therefore see settlement_type)- INSTALMENT (including product 'Instalment' and 'Instalment Direct Debit' therefore see settlement_type)- PREPAYMENT
    Example: "INVOICE"

  - `payment_information.payment_method.current_payment_method_details.settlement_type` (string)
    The settlement type for this order, i. e. how settlements are done. Possible values:- BANK_TRANSFER- DIRECT_DEBIT
    Example: "DIRECT_DEBIT"

  - `payment_information.payment_method.current_payment_method_details.instalment_plans` (array)
    A list of all currently active instalment plans for the current order. This is only part of the response if atleast one instalment plan exists. Most of the time this is only returned if payment_method is INSTALMENT.

  - `payment_information.payment_method.current_payment_method_details.instalment_plans.reference` (string)
    The reference of the instalment plan. This is the unique identifier for each instalment plan. This is not the clearing reference as each instalment plan may encompass more than one clearing_reference
    Example: "KK7709094U2"

  - `payment_information.payment_method.current_payment_method_details.instalment_plans.creation_date` (string)
    The date at which the instalment plan was created at Ratepay. This may change if e. g. a new instalment plan is created because of unscheduled payments.
    Example: "2020-04-08"

  - `payment_information.payment_method.current_payment_method_details.instalment_plans.amount_total` (number)
    The sum of amount_credit and amount_fees.
    Example: 200.47

  - `payment_information.payment_method.current_payment_method_details.instalment_plans.amount_credit` (number)
    The amount without considering fees, interests etc. This amount changes with returns.
    Example: 186.07

  - `payment_information.payment_method.current_payment_method_details.instalment_plans.amount_fees` (number)
    The sum of all fees.
    Example: 14.4

  - `payment_information.payment_method.current_payment_method_details.instalment_plans.interest_rate` (number)
    The annual interest rate for this instalment plan.
    Example: 5.99

  - `payment_information.payment_method.current_payment_method_details.instalment_plans.effective_interest_rate` (number)
    The effective annual interest rate for this instalment plan, i. e. including interests and all other costs.
    Example: 3.33

  - `payment_information.payment_method.current_payment_method_details.instalment_plans.number_of_instalments` (integer)
    The number of instalments for this instalment plan.
    Example: 6

  - `payment_information.payment_method.current_payment_method_details.instalment_plans.instalments` (array)
    A list containing details about each individual instalment. This list has number_of_instalments elements.

  - `payment_information.payment_method.current_payment_method_details.instalment_plans.instalments.amount_total` (number)
    The total amount of this instalment, i. e. the amount that has to be paid.
    Example: 31.01

  - `payment_information.payment_method.current_payment_method_details.instalment_plans.instalments.due_date` (string)
    The due date of this instalment (ISO 8601, YYYY-MM-DD).
    Example: "2020-04-08"

  - `payment_information.payment_method.current_payment_method_details.instalment_plans.instalments.amount_interest` (number)
    The interest amount that is paid with this instalment.
    Example: 1.3

  - `payment_information.payment_method.current_payment_method_details.instalment_plans.instalments.amount_repayment` (number)
    The repayment amount that is paid with this instalment.
    Example: 27.31

  - `payment_information.payment_method.current_payment_method_details.instalment_plans.instalments.amount_fee` (number)
    Optional. The amount of fees that is paid with this instalment.
    Example: 2.4

  - `payment_information.payment_method.current_payment_method_details.instalment_plans.instalments.amount_unscheduled` (number)
    Optional. The amount of unscheduled repayment that was paid with this instalment.
    Example: 1.6

  - `payment_information.payment_method.current_payment_method_details.instalment_plans.instalments.residual_debt` (number)
    The residual debt left after this instalment is paid. null for the last instalment as residual debt is 0.
    Example: 186.07

  - `payment_information.payment_method.current_payment_method_details.instalment_plans.instalments.instalment_number` (integer)
    The number of this instalment as part of the instalment plan. Starts with 1 and is incremented by one for each instalment until number_of_instalments for the last instalment.
    Example: 1

  - `payment_information.payment_status` (object)
    This object is only part of the response if include contains payment_status.

  - `payment_information.payment_status.order_payment_status` (string)
    The payment status of the current order. It is based on the current open amount (open_claim.amount). Possible values are:
- OPEN
- UNDERPAID
- BALANCED
- OVERPAID
    Example: "UNDERPAID"

  - `payment_information.payment_status.open_claim` (object)

  - `payment_information.payment_status.open_claim.amount` (number)
    The amount that the shopper would have to pay Ratepay at this moment, i.e. current_claim.amount minus settlements.amount.
    Example: 100

  - `payment_information.payment_status.open_claim.current_claim` (object)

  - `payment_information.payment_status.open_claim.current_claim.amount` (number)
    The sum of all shop_claims and ratepay_buyer_fees and therefore the amount the shopper has to pay Ratepay at this moment without considering existing settlements:shop_claims.amount + ratepay_buyer_fees.amount.grossThis is based on the actual financial claims in Ratepay's possesion and not on the basket value. Example: For invoices a claim is created when items are shipped. Before the shipment the open amount could be 0 even though the basket value is greater than 0.
    Example: 150

  - `payment_information.payment_status.open_claim.current_claim.shop_claims` (object)
    An object containing all claims that originate from the shop through the basket.

  - `payment_information.payment_status.open_claim.current_claim.shop_claims.claims` (array)
    A list of all claims for the current order.

  - `payment_information.payment_status.open_claim.current_claim.shop_claims.claims.type` (string)
    The type of claim. Possible values:- SHIPMENT = items are shipped- RETURN = items are returned- CANCEL = items are cancelled

  - `payment_information.payment_status.open_claim.current_claim.shop_claims.claims.date` (string)
    The date that the claim was created (ISO 8601, YYYY-MM-DD).

  - `payment_information.payment_status.open_claim.current_claim.shop_claims.claims.amount` (number)
    The amount of the claim.Positive for claims against the shopper (type is SHIPMENT).Negative for claims against Ratepay (type is RETURN or CANCEL)

  - `payment_information.payment_status.open_claim.current_claim.shop_claims.amount` (number)
    The sum of all existing claims. The claims originate from the shop. Examples include the price for items in the shopper's basket and shipping fees.
    Example: 145

  - `payment_information.payment_status.open_claim.current_claim.ratepay_buyer_fees` (object)
    An object containing all fees that originate from Ratepay.

  - `payment_information.payment_status.open_claim.current_claim.ratepay_buyer_fees.buyer_fees` (array)
    A list of fees for the current order.

  - `payment_information.payment_status.open_claim.current_claim.ratepay_buyer_fees.buyer_fees.type` (string)
    The type of fee. Possible values:
amount.gross is positive:    - PAY_LATER_FEE = Pay Later was booked- SERVICE_CHARGE = May be created with an instalment plan- DUNNING_FEE- RETURN_DEBIT_NOTE_FEE- INTEREST = Interest amount for instalment plansamount.gross is negative:- PAY_LATER_WITHDRAWN- SERVICE_CHARGE_RETURN- DUNNING_FEE_RETURN- RETURN_DEBIT_NOTE_FEE_RETURN
    Example: "RETURN_DEBIT_NOTE_FEE"

  - `payment_information.payment_status.open_claim.current_claim.ratepay_buyer_fees.buyer_fees.date` (string)
    The date that the fee was created (ISO 8601, YYYY-MM-DD).
    Example: "2020-03-10"

  - `payment_information.payment_status.open_claim.current_claim.ratepay_buyer_fees.buyer_fees.amount` (object)

  - `payment_information.payment_status.open_claim.current_claim.ratepay_buyer_fees.buyer_fees.amount.gross` (number)
    The amount of the fee:Positive for new feesNegative for cancelled fees
    Example: 5

  - `payment_information.payment_status.open_claim.settlement` (object)

  - `payment_information.payment_status.open_claim.settlement.settlements` (array)
    A list of containing all settlements for the current order.

  - `payment_information.payment_status.open_claim.settlement.settlements.type` (string)
    The type of settlement. Possible values:- CREDIT = buyer received money / Ratepay paid money- DEBIT = buyer paid money / Ratepay received money

  - `payment_information.payment_status.open_claim.settlement.settlements.date` (string)
    The date that the settlement was done (ISO 8601, YYYY-MM-DD) i. e. the ate that money arrived in Ratepay's bank account (type is DEBIT) or the date the money was send from Ratepay's bank account (type is CREDIT).

  - `payment_information.payment_status.open_claim.settlement.settlements.amount` (number)
    The amount of the settlement.Positive for CREDITNegative for DEBIT.

  - `payment_information.payment_status.open_claim.settlement.amount` (number)
    The sum of all existing settlements by the shopper.
    Example: 50

  - `payment_information.dunning_status` (object)
    This object is only part of the response if include contains dunning_status.

  - `payment_information.dunning_status.current_order_dunning_level` (string)
    The current dunning level for the order as a whole. Possible values are:- NO_DUNNING- PAYMENT_REMINDER- FIRST_DUNNING- LAST_DUNNING- COLLECTION- COLLECTION_FINISHED
    Example: "PAYMENT_REMINDER"

  - `payment_information.dunning_status.order_dunning_date` (string)
    The date the current_order_dunning_level was set (ISO 8601, YYYY-MM-DD). This is null if the current_order_dunning_level is NO_DUNNING
    Example: "2020-03-24"

  - `payment_information.dunning_status.current_dunning_fee` (number)
    The sum of all dunning fees up to now. For details about the dunning fee see payment_status.open_claim.current_claimratepay_buyer_fees.buyer_fees

  - `payment_information.dunning_status.dunning_block` (object)
    Contains the details of the currently existing dunning block. Is null if no dunning block currently exists.

  - `payment_information.dunning_status.dunning_block.blocked_from` (string)
    The date from which dunnings are blocked (ISO 8601, YYYY-MM-DD).
    Example: "2020-03-25"

  - `payment_information.dunning_status.dunning_block.blocked_until` (string)
    The data until when dunnings are blocked (ISO 8601, YYYY-MM-DD).
    Example: "2020-04-01"

  - `payment_information.dunning_status.dunning_block.blocking_reason` (string)
    The reason why this dunning block was set.
    Example: "Zahlungsaufschub aus Kulanz"


## Response 404 fields

## Response 405 fields

## Response 406 fields

## Response 415 fields

## Response 500 fields