Skip to content
API requests
/
2. Hosted Payment Page AP...
/Session management API/
Creates a new session

OpenAPI definition (v0)

Download OpenAPI description
hpp_api.json
hpp_api.yaml
Languages
Servers
Integration environment
https://payment-integration.ratepay.com
Production environment
https://payment.ratepay.com

Session management API

Operations

Creates a new session

Request

Security
Bearer Authentication
Headers
Idempotency-Keystring<= 64 characters

Optional ID generated by client to uniquely identify the request. It is highly recommended to use a UUID version 4. Do not reuse an idempotency key for different calls. See Idempotency in HPP for further details.

Bodyapplication/jsonrequired
order_dataobject(OrderDataDto)required
url_dataobject(UrlData)
curl -i -X POST \
  https://payment-integration.ratepay.com/pps/api/v1/session \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: string' \
  -d '{
    "order_data": {
      "partner_transaction_id": "12345",
      "buyer": {
        "billing_address": {
          "city": "Berlin",
          "country_code": "DE",
          "street": "Schönhauser Allee",
          "street_addition": "Seitenflügel, 2. HH",
          "street_number": "84",
          "zip_code": "10439"
        },
        "contact": {
          "email": "heinz.steeger@example.org",
          "phone": "+49 170 1234567"
        },
        "person": {
          "title": "Dr.",
          "first_name": "Heinz",
          "last_name": "Steeger",
          "date_of_birth": "1971-05-19"
        }
      },
      "currency": "EUR",
      "delivery": {
        "full_name": "Max Mustermann",
        "address": {
          "city": "Berlin",
          "country_code": "DE",
          "street": "Schönhauser Allee",
          "street_addition": "Seitenflügel, 2. HH",
          "street_number": "84",
          "zip_code": "10439"
        }
      },
      "shop_baskets": [
        {
          "partner_shop_id": "demo-shop-1",
          "shop_transaction_id": "sale_order_35",
          "gross_amount": 43.8,
          "items": [
            {
              "article_number": "kitchen-utils-1",
              "category": "household",
              "description": "fruit knife with curved blade, 8 cm",
              "gross_total_price": 33.8,
              "gross_unit_discount": -1.55,
              "gross_unit_price": 18.45,
              "name": "fruit knife",
              "net_total_price": 28.4,
              "net_unit_discount": -1.3,
              "net_unit_price": 15.5,
              "quantity": 2,
              "tax_rate": 19,
              "unit": "piece"
            }
          ],
          "special_items": [
            {
              "article_number": "Shipping",
              "category": "shipping",
              "description": "Shipping",
              "gross_total_price": 10,
              "gross_unit_price": 10,
              "name": "Shipping",
              "net_total_price": 8.4,
              "net_unit_price": 8.4,
              "quantity": 1,
              "tax_rate": 19,
              "unit": "piece"
            }
          ],
          "vats": [
            {
              "tax_rate": 19,
              "net_amount": 21.01,
              "tax_amount": 3.99
            }
          ]
        }
      ]
    },
    "url_data": {
      "success_url": "https://localhost/success?storeTransactionId=123456",
      "failure_url": "https://localhost/failure?storeTransactionId=123456",
      "cancel_url": "https://localhost/cancel?storeTransactionId=123456",
      "webhook_url": "https://localhost/webhook?storeTransactionId=123456"
    }
  }'

Responses

Session created successfully

Bodyapplication/json
session_idstring
landing_pagestringrequired
Response
application/json
{
  "session_id": "6919e03b-08b7-4bcd-b8c4-7a6a225d3a20",
  "landing_page": "https://payment.ratepay.com/session/6919e03b-08b7-4bcd-b8c4-7a6a225d3a20?retrievalKey=e_5p43MMTCitRzQu8a7Wcw&v=ratepay&t=6919e03b08b74bcdb8c47a6a225d3a20"
}

Session Records API

Operations

Webhook format

Operations