Skip to content
API requests
/
/
For marketplaces (one or...

For marketplaces (one or multiple shop entities per transaction)

Before using the Payment API, you must request a OAuth token via the Authentication API and use this in the headers for further Payment 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.

Authorize transaction

Here you can find more informations about the endpoints, possible parameters and descriptions in detail.

Usage

  1. Request an OAuth token from the Authentication API.

  2. Prepare your headers as follows:

    • Content-Type: application/json
    • Authorization: Bearer {oauthToken}
    • X-Partner: [your partner id] Optional

  3. Prepare the payload:

    • Buyer data
    • Currency
    • Delivery details
    • Device details
    • Payment 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}/transaction/management/v2/transactions

  5. Save the ratepay_transaction_id from the response for further requests.

Payload

{
  "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",
    "shop_buyer_id": "shop-buyer-id-1234"
  },
  "currency": "EUR",
  "delivery": {
    "first_name": "Heinz",
    "full_name": null,
    "last_name": "Steeger",
    "in_store_collect": null,
    "pick_up_box": null,
    "pick_up_shop": null,
    "address": {
      "city": "Berlin",
      "country_code": "DE",
      "street": "Schönhauser Allee",
      "street_addition": "Seitenflügel, 2. HH",
      "street_number": "84",
      "zip_code": "10439"
    }
  },
  "device": {
    "source_ip_address": "10.17.1.1",
    "token": "ade028c1-d2a2-4189-9214-e21089cd47f1"
  },
  "partner_operation_id": "partner-operation-id-1234",
  "partner_transaction_id": "partner-transaction-id-1234",
  "payment_method": {
    "payment_option": "OPEN_INVOICE",
    "transfer_type": "BANK_TRANSFER"
  },
  "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
        }
      ]
    },
    {
      "partner_shop_id": "PROVIDED_BY_RATEPAY_2",
      "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
        }
      ]
    }
  ]
}

Cancel transaction

Here you can find more informations about the endpoints, possible parameters and descriptions in detail.

Usage

  1. Request an OAuth token from the Authentication API.

  2. Prepare your headers as follows:

    • Content-Type: application/json
    • Authorization: Bearer {oauthToken}
    • X-Partner: [your partner id] Optional

  3. Prepare the payload:

    • 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}/transaction/management/v2/transactions/{ratepayTransactionId}/cancellations

Payload

{
  "partner_shop_id": "PROVIDED_BY_RATEPAY_1",
  "partner_operation_id": "cancel-id-1234",
  "gross_amount": 16.9,
  "items": [
    {
      "article_number": "kitchen-utils-1",
      "category": "household",
      "description": "fruit knife with curved blade, 8 cm",
      "gross_total_price": 16.9,
      "gross_unit_discount": -1.55,
      "gross_unit_price": 18.45,
      "name": "fruit knife",
      "net_total_price": 14.2,
      "net_unit_discount": -1.3,
      "net_unit_price": 15.5,
      "quantity": 1,
      "tax_rate": 19,
      "unit": "piece"
    }
  ],
  "vats": [
    {
      "net_amount": 14.2,
      "tax_amount": 2.7,
      "tax_rate": 19
    }
  ]
}

Capture transaction

Here you can find more informations about the endpoints, possible parameters and descriptions in detail.

Usage

  1. Request an OAuth token from the Authentication API.

  2. Prepare your headers as follows:

    • Content-Type: application/json
    • Authorization: Bearer {oauthToken}
    • X-Partner: [your partner id] Optional

  3. Prepare the payload:

    • 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}/transaction/management/v2/transactions/{ratepayTransactionId}/captures

Payload

{
  "partner_shop_id": "PROVIDED_BY_RATEPAY_1",
  "partner_operation_id": "capture-id-1234",
  "gross_amount": 16.9,
  "items": [
    {
      "article_number": "kitchen-utils-1",
      "category": "household",
      "description": "fruit knife with curved blade, 8 cm",
      "gross_total_price": 16.9,
      "gross_unit_discount": -1.55,
      "gross_unit_price": 18.45,
      "name": "fruit knife",
      "net_total_price": 14.2,
      "net_unit_discount": -1.3,
      "net_unit_price": 15.5,
      "quantity": 1,
      "tax_rate": 19,
      "unit": "piece"
    }
  ],
  "vats": [
    {
      "net_amount": 14.2,
      "tax_amount": 2.7,
      "tax_rate": 19
    }
  ]
}

Refund transaction

Here you can find more informations about the endpoints, possible parameters and descriptions in detail.

Usage

  1. Request an OAuth token from the Authentication API.

  2. Prepare your headers as follows:

    • Content-Type: application/json
    • Authorization: Bearer {oauthToken}
    • X-Partner: [your partner id] Optional

  3. Prepare the payload:

    • 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}/transaction/management/v2/transactions/{ratepayTransactionId}/refunds

Payload

{
  "partner_shop_id": "PROVIDED_BY_RATEPAY_1",
  "partner_operation_id": "refund-id-1234",
  "gross_amount": 16.9,
  "items": [
    {
      "article_number": "kitchen-utils-1",
      "category": "household",
      "description": "fruit knife with curved blade, 8 cm",
      "gross_total_price": 16.9,
      "gross_unit_discount": -1.55,
      "gross_unit_price": 18.45,
      "name": "fruit knife",
      "net_total_price": 14.2,
      "net_unit_discount": -1.3,
      "net_unit_price": 15.5,
      "quantity": 1,
      "tax_rate": 19,
      "unit": "piece"
    }
  ],
  "vats": [
    {
      "net_amount": 14.2,
      "tax_amount": 2.7,
      "tax_rate": 19
    }
  ]
}
Previous page
Next page