# Preparation

div
div
⏱ 5 min
div
👤 Onboarding Developer Team (Alexandre S.)
Before using the HPP API, you must request a OAuth token via the [Authentication API](/docs/developer/authentication/authentication/) 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](mailto:integration@ratepay.com).
You will then receive a **Client ID** and a **Client Secret**, each for the Ratepay **Test-** and the **Live environment**.

## Usage

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


### B2C and B2B examples


```json B2C
{
  "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 4445555"
		},
		"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
			}
		  ]
		}
	  ]
   }
}
```


```json B2B
{
  "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 4445555"
    },
    "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


```json Regular address
{
  "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
        }
      ]
    }
  ]
}
```


```json In-Store Collect
{
  "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
        }
      ]
    }
  ]
}
```


```json Pick-Up Box
{
  "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
        }
      ]
    }
  ]
}
```


```json Pick-Up Shop
{
  "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
        }
      ]
    }
  ]
}
```