Skip to content
API requests
/
/
Example requests for merc...

Example requests for merchants (one shop entity per transaction)

Credentials

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.

Meanwhile, you can use our general OAuth credentials for the Ratepay Test environment:

Please consider, that no real personal data should be transmitted with the general OAuth credentials!

Client IDClient Secretpartner_shop_id
snbFcxD4Rxt2O4YqeGqDls9yrGWYhmQ0IHa7jiW0hMlH0VsoxDTZ03XH76NED7RwFvJLsmmUXg9fkowhiVQqp7EA84WoYT1QINTEGRATION_TE_DACH

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}

  3. Prepare the payload:

    • Buyer data
    • Currency
    • Delivery details
    • Device details
    • Payment details
    • Shopping cart details (including the 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",
      "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}

  3. Prepare the payload:

    • Shopping cart details (including the 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",
  "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}

  3. Prepare the payload:

    • Shopping cart details (including the 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",
  "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}

  3. Prepare the payload:

    • Shopping cart details (including the 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",
  "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