Skip to content
Developer
/Transaction Status API/
/Operations

Order Status OpenAPI specification (version 1)

The Order Status API enables merchants to provide their customers and service agents with Ratepay's payment details at any customer contact point. This allows the merchant to remain the face to customers while gaining additional supplier services. The Order Status API is built around RESTful principles. It is HTTPS-based and uses JSON as the request and response format. It delivers standard HTTP response types.

Download OpenAPI description
operations.json
operations.yaml
Languages
Servers
Production environment

http://api.ratepay.com/

Get order status

Request

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.

Security
Bearer Authentication
Path
transaction-idstringrequired

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
includeArray of strings

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: include=all
Headers
Content-Typestringrequired
Example: application/json
Authorizationstringrequired

For each request, a valid access token must be provided in the Authorization header. See Authentication API for obtaining a valid token.

curl -i -X GET \
  'http://api.ratepay.com/order/status/v2/transactions/12-3456789123456789?include=all' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json'

Responses

Is returned if order status information is returned for the given transaction_id

Bodyapplication/json;charset=UTF-8
general_order_informationobject(GeneralOrderInformationDto)

These attributes are always returned if a valid request is sent.

basketobject(BasketInformationDto)

This object is returned if include contains basket

payment_informationobject(PaymentInformationDto)

These fields are returned if include contains atleast one of these values:
payment_status, dunning_status, payment_method

Response
application/json;charset=UTF-8
{
  "general_order_information": {
    "transaction_id": "12-3456789123456789",
    "shop_order_id": "test-shop-order-id",
    "order_creation_date": "2020-03-10T18:06:52.438+01:00",
    "shop_buyer_id": "test-shop-buyer-id",
    "currency": "EUR"
  },
  "basket": {
    "initial_order_amount_gross": 170,
    "current_order_amount_gross": 145,
    "last_updated": "2020-03-12T18:06:52.438+01:00",
    "current_items": [ … ],
    "current_special_items": { … }
  },
  "payment_information": {
    "maximum_processing_offset_in_hours": 0,
    "payment_method": { … },
    "payment_status": { … },
    "dunning_status": { … }
  }
}

Get order correspondence

Request

This endpoint allows you to get correspondence

Source of information


All parameters needed for the request can be obtained via webhooks. This is a service that is only available for registered merchants. The service informs the merchant when a new transaction has been made and further information such as invoices are available for retrieval. How to activate this service can be found at the following link: Subscription webhooks

Receivable information and its format


As you can see, the successful response does not contain information in form of a JSON structure. All the information that can be received is received in form of an invoice file. You can choose whether to receive the invoices as pdf, html or via e-mail depending on your request. This information to access the different formats is contained in the payload of the webhook.

Security
Bearer Authentication
Path
transaction_idstringrequired

The transaction id of the order for which the correspondence is requested

Example: 12-34567890123456789
correspondence_idstringrequired

The id of the requested correspondence

formatstringrequired

The response format of the requested correspondence. Possible values:
pdf and eml

Example: eml
Headers
Authorizationstringrequired

For each request, a valid access token must be provided in the Authorization header. See Authentication API for obtaining a valid token.

Content-Typestringrequired
Example: application/json
curl -i -X GET \
  'http://api.ratepay.com/api/order/12-34567890123456789/correspondences/invoices/{correspondence_id}/eml' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json'

Responses

Is returned if the requested artifact is returned