# Get Transaction Status

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

Endpoint: GET /transaction/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 transaction for which the transaction status is requested. (The Ratepay Payment API returns this when an transaction is created.)
    Example: "12-3456789123456789"

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

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

  - `partner_transaction_id` (string)
    The transaction ID generated by the partner. This ID can be displayed in the settlement files.
    Example: "test-shop-transaction-id"

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

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

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

  - `shop_baskets` (array)
    One basket for each shop contained in the transaction. The definition of multiple shops is only relevant for marketplace integrations.

  - `shop_baskets.partner_shop_id` (string)
    The shop ID generated by the partner or provided upfront by Ratepay
    Example: "partner-shop-id-1"

  - `shop_baskets.partner_shop_name` (string)
    The name of the shop. May differ from legal name.
    Example: "fruits and more"

  - `shop_baskets.shop_transaction_id` (string)
    The transaction ID generated by the shop. This ID must be known to the buyer and is used for buyer communication, e.g. correspondences and buyer support.
    Example: "shop-transaction-id-1234"

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

  - `shop_baskets.items` (array)
    List of items contained in the transaction.

  - `shop_baskets.items.gross_unit_price` (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: 18.45

  - `shop_baskets.items.gross_unit_discount` (number)
    Gross discount on one item after taxes. Needs to be a negative value.
    Example: -1.55

  - `shop_baskets.items.gross_total_price` (number)
    Gross value including discount of these items after taxes. gross_total_price = (gross_unit_price + gross_unit_discount) * quantity
    Example: 33.8

  - `shop_baskets.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

  - `shop_baskets.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.

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

  - `shop_baskets.items.article_number` (string)
    The article number of the item, e.g. SKU. Not allowed to contain only whitespaces.
    Example: "kitchen-utils-1"

  - `shop_baskets.items.name` (string)
    Name of the item.
    Example: "fruit knife"

  - `shop_baskets.items.category` (string)
    Category for the item.
    Example: "household"

  - `shop_baskets.items.unit` (string)
    Arbitrary measurement unit of the item, e.g. kg, litre, pieces.
    Example: "piece"

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

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

  - `shop_baskets.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"

  - `shop_baskets.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"

  - `shop_baskets.items.net_total_price` (number)
    Net value including discount of these items before taxes. net_total_price = (net_unit_price + net_unit_discount) * quantity
    Example: 28.4

  - `shop_baskets.items.net_unit_discount` (number)
    Net discount on one item before taxes. Needs to be a negative value.
    Example: -1.3

  - `shop_baskets.items.net_unit_price` (number)
    Net value of one item before taxes.
    Example: 15.5

  - `shop_baskets.special_items` (array)
    List of special items contained in the transaction, e.g. shipping costs or discounts.

  - `shop_baskets.special_items.type` (string)
    The special item type the buyer selected.
    Example: "RETURN_FEE"

  - `payment_information` (object)
    Provides details about payment_method, payment_status, dunning_status

  - `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 transaction 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.payment_details` (object)

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

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

  - `payment_information.payment_method.payment_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.payment_details.prepayment.amount` (number)
    The original amount that the prepayment was created for.
    Example: 170

  - `payment_information.payment_method.payment_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.payment_details.invoices` (array)
    A list of all currently active invoices of the current transaction. 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 transaction exists.

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

  - `payment_information.payment_method.payment_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.payment_details.invoices.original_due_date` (string)
    The original due date for this invoice.
    Example: "2020-03-24"

  - `payment_information.payment_method.payment_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.payment_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.payment_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.payment_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.payment_details.payment_method` (string)
    The payment method for the current transaction. 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.payment_details.settlement_type` (string)
    The settlement type for this transaction, i. e. how settlements are done. Possible values:- BANK_TRANSFER- DIRECT_DEBIT
    Example: "DIRECT_DEBIT"

  - `payment_information.payment_method.payment_details.instalment_plans` (array)
    A list of all currently active instalment plans for the current transaction. 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.payment_details.instalment_plans.ratepay_payment_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: "test-ref"

  - `payment_information.payment_method.payment_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.payment_details.instalment_plans.amount_total` (number)
    The sum of amount_credit and amount_fees.
    Example: 200.47

  - `payment_information.payment_method.payment_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.payment_details.instalment_plans.amount_fees` (number)
    The sum of all fees.
    Example: 14.4

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

  - `payment_information.payment_method.payment_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.payment_details.instalment_plans.number_of_instalments` (integer)
    The number of instalments for this instalment plan.
    Example: 6

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

  - `payment_information.payment_method.payment_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.payment_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.payment_details.instalment_plans.instalments.amount_interest` (number)
    The interest amount that is paid with this instalment.
    Example: 1.3

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

  - `payment_information.payment_method.payment_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.payment_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.payment_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.payment_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)
    payment status of the current transaction.

  - `payment_information.payment_status.transaction_payment_status` (string)
    The payment status of the current transaction. 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 transaction.

  - `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 transaction.

  - `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 transaction.

  - `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` (array)
    A list of all shops dunnings.

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

  - `payment_information.dunning_status.transaction_dunning_date` (string)
    The date the current_transaction_dunning_level was set (ISO 8601, YYYY-MM-DD). This is null if the current_transaction_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 422 fields

## Response 500 fields