Preparation

Before using the HPP API, you must request a OAuth token via the Authentication API and use this in the headers for further HPP API requests.

Please contact your technical contact person at Ratepay or send an e-mail to integration@ratepay.com. You will then receive a Client ID and a Client Secret, each for the Ratepay Test- and the Live environment.

Usage

Request an OAuth token from the Authentication API .
Prepare your headers as follows:
- Content-Type: application/json
- Authorization: Bearer {oauthToken}
Prepare the payload:
- Buyer data
- Currency
- Delivery details
- Shopping cart details (including one or multiple partner_shop_id , which will be provided by Ratepay)
Make a POST request to the following URL:
https:// {environment} /pps/api/v1/session
Redirect the user to the page in landing_page .

B2C and B2B examples

B2CB2B

Copy

Copied

{
  "order_data": {
	  "buyer": {
		"person": {
		  "title": "Dr.",
		  "first_name": "Heinz",
		  "last_name": "Steeger",
		  "date_of_birth": "1971-05-19"
		},
		"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 177 44455553"
		},
		"language": "de"
	  },
	  "currency": "EUR",
	  "delivery": {
		"first_name": "Heinz",
		"last_name": "Steeger",
		"address": {
		  "city": "Berlin",
		  "country_code": "DE",
		  "street": "Schönhauser Allee",
		  "street_addition": "Seitenflügel, 2. HH",
		  "street_number": "84",
		  "zip_code": "10439"
		}
	  },
	  "partner_transaction_id": "partner-transaction-id-1234",
	  "shop_baskets": [
		{
		  "partner_shop_id": "PROVIDED_BY_RATEPAY_1",
		  "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": [
			{
			  "net_amount": 36.8,
			  "tax_amount": 7,
			  "tax_rate": 19
			}
		  ]
		}
	  ]
   }
}

Copy

Copied

{
  "buyer": {
    "company": {
       "name": "Berlin Advertising Agency",
       "vat_id": "DE123456789"
    },
    "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 177 44455553"
    },
    "language": "de"
  },
  "currency": "EUR",
  "delivery": {
    "company": "Berlin Advertising Agency",
    "first_name": "Heinz",
    "last_name": "Steeger",
    "address": {
      "city": "Berlin",
      "country_code": "DE",
      "street": "Schönhauser Allee",
      "street_addition": "Seitenflügel, 2. HH",
      "street_number": "84",
      "zip_code": "10439"
    }
  },
  "partner_transaction_id": "partner-transaction-id-1234",
  "shop_baskets": [
    {
      "partner_shop_id": "PROVIDED_BY_RATEPAY_1",
      "shop_transaction_id": "shop-transaction-id-1234",
      "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": [
        {
          "net_amount": 36.8,
          "tax_amount": 7,
          "tax_rate": 19
        }
      ]
    }
  ]
}

Different types of delivery address

Regular addressIn-Store CollectPick-Up BoxPick-Up Shop

Copy

Copied

{
  "buyer": {
    "company": {
       "name": "Berlin Advertising Agency",
       "vat_id": "DE123456789"
    },
    "billing_address": {
      "city": "Berlin",
      "country_code": "DE",
      "street": "Schönhauser Allee",
      "street_addition": "Seitenflügel, 2. HH",
      "street_number": "84",
      "zip_code": "10439"
    },
    "language": "de"
  },
  "currency": "EUR",
  "delivery": {
    "company": "Berlin Advertising Agency",
    "first_name": "Heinz",
    "last_name": "Steeger",
    "address": {
      "city": "Berlin",
      "country_code": "DE",
      "street": "Schönhauser Allee",
      "street_addition": "Seitenflügel, 2. HH",
      "street_number": "84",
      "zip_code": "10439"
    }
  },
  "partner_transaction_id": "partner-transaction-id-1234",
  "shop_baskets": [
    {
      "partner_shop_id": "PROVIDED_BY_RATEPAY_1",
      "shop_transaction_id": "shop-transaction-id-1234",
      "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": [
        {
          "net_amount": 36.8,
          "tax_amount": 7,
          "tax_rate": 19
        }
      ]
    }
  ]
}

Copy

Copied

{
  "buyer": {
    "company": {
       "name": "Berlin Advertising Agency",
       "vat_id": "DE123456789"
    },
    "billing_address": {
      "city": "Berlin",
      "country_code": "DE",
      "street": "Schönhauser Allee",
      "street_addition": "Seitenflügel, 2. HH",
      "street_number": "84",
      "zip_code": "10439"
    },
    "language": "de"
  },
  "currency": "EUR",
  "delivery": {
    "company": "Berlin Advertising Agency",
    "first_name": "Heinz",
    "last_name": "Steeger",
    "in_store_collect": {
      "city": "Berlin",
      "country_code": "DE",
	  "location_name": "Your store",
      "street": "Schönhauser Allee",
      "street_addition": "Seitenflügel, 2. HH",
      "street_number": "84",
      "zip_code": "10439"
	}
  },
  "partner_operation_id": "partner-operation-id-1234",
  "partner_transaction_id": "partner-transaction-id-1234",
  "shop_baskets": [
    {
      "partner_shop_id": "PROVIDED_BY_RATEPAY_1",
      "shop_transaction_id": "shop-transaction-id-1234",
      "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": [
        {
          "net_amount": 36.8,
          "tax_amount": 7,
          "tax_rate": 19
        }
      ]
    }
  ]
}

Copy

Copied

{
  "buyer": {
    "company": {
       "name": "Berlin Advertising Agency",
       "vat_id": "DE123456789"
    },
    "billing_address": {
      "city": "Berlin",
      "country_code": "DE",
      "street": "Schönhauser Allee",
      "street_addition": "Seitenflügel, 2. HH",
      "street_number": "84",
      "zip_code": "10439"
    },
    "language": "de"
  },
  "currency": "EUR",
  "delivery": {
    "company": "Berlin Advertising Agency",
    "first_name": "Heinz",
    "last_name": "Steeger",
    "pick_up_box": {
	  "carrier_name": "DHL",
      "city": "Berlin",
      "country_code": "DE",
	  "location_id": "123456789",
      "zip_code": "10439"
	}
  },
  "partner_transaction_id": "partner-transaction-id-1234",
  "shop_baskets": [
    {
      "partner_shop_id": "PROVIDED_BY_RATEPAY_1",
      "shop_transaction_id": "shop-transaction-id-1234",
      "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": [
        {
          "net_amount": 36.8,
          "tax_amount": 7,
          "tax_rate": 19
        }
      ]
    }
  ]
}

Copy

Copied

{
  "buyer": {
    "company": {
       "name": "Berlin Advertising Agency",
       "vat_id": "DE123456789"
    },
    "billing_address": {
      "city": "Berlin",
      "country_code": "DE",
      "street": "Schönhauser Allee",
      "street_addition": "Seitenflügel, 2. HH",
      "street_number": "84",
      "zip_code": "10439"
    },
    "language": "de"
  },
  "currency": "EUR",
  "delivery": {
    "company": "Berlin Advertising Agency",
    "first_name": "Heinz",
    "last_name": "Steeger",
    "pick_up_shop": {
      "city": "Berlin",
      "country_code": "DE",
	  "location_name": "Späti Kauf",
      "street": "Schönhauser Allee",
      "street_addition": "Seitenflügel, 2. HH",
      "street_number": "84",
      "zip_code": "10439"
	}
  },
  "partner_transaction_id": "partner-transaction-id-1234",
  "shop_baskets": [
    {
      "partner_shop_id": "PROVIDED_BY_RATEPAY_1",
      "shop_transaction_id": "shop-transaction-id-1234",
      "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": [
        {
          "net_amount": 36.8,
          "tax_amount": 7,
          "tax_rate": 19
        }
      ]
    }
  ]
}