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

Open Invoice (B2C)Open Invoice (B2B)Direct Debit (B2C)Direct Debit (B2B)
Copy
Copied
{
  "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",
    "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
        }
      ]
    }
  ]
}
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",
    "shop_buyer_id": "shop-buyer-id-1234"
  },
  "currency": "EUR",
  "delivery": {
    "company": "Berlin Advertising Agency",
    "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
        }
      ]
    }
  ]
}
Copy
Copied
{
  "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",
    "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_details": {
    "debit_bank_account": {
      "iban": "DE44100500001654698497",
      "owner": "Heinz Steeger"
    }
  },
  "payment_method": {
    "payment_option": "PAY_NOW",
    "transfer_type": "SEPA_DIRECT_DEBIT"
  },
  "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
        }
      ]
    }
  ]
}
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",
    "shop_buyer_id": "shop-buyer-id-1234"
  },
  "currency": "EUR",
  "delivery": {
    "company": "Berlin Advertising Agency",
    "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_details": {
    "debit_bank_account": {
      "iban": "DE44100500001654698497",
      "owner": "Heinz Steeger"
    }
  },
  "payment_method": {
    "payment_option": "PAY_NOW",
    "transfer_type": "SEPA_DIRECT_DEBIT"
  },
  "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

With items (recommended)Without items
Copy
Copied
{
  "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
    }
  ]
}
Copy
Copied
{
  "partner_shop_id": "PROVIDED_BY_RATEPAY_1",
  "partner_operation_id": "cancel-id-1234",
  "gross_amount": 16.9
}

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

With items (recommended)Without items
Copy
Copied
{
  "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
    }
  ]
}
Copy
Copied
{
  "partner_shop_id": "PROVIDED_BY_RATEPAY_1",
  "partner_operation_id": "capture-id-1234",
  "gross_amount": 16.9
}

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

With itemsWithout itemsWith items and buyer return fee
Copy
Copied
{
  "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
    }
  ]
}
Copy
Copied
{
  "partner_shop_id": "PROVIDED_BY_RATEPAY_1",
  "partner_operation_id": "refund-id-1234",
  "gross_amount": 16.9
}
Copy
Copied
{
  "gross_amount": 4.33,
  "partner_shop_id": "PROVIDED_BY_RATEPAY_1",
  "partner_operation_id": "refund-id-1234",
  "items": [
    {
      "article_number": "444",
      "name": "clothes",
      "description": "Use it to feel way better",
      "category": "Lifestyle",
      "tax_rate": 19.0,
      "quantity": 0.9,
      "unit": "refund unit 1",
      "net_unit_price": 8.61,
      "gross_unit_price": 10.25,
      "gross_unit_discount": -1.25,
      "net_unit_discount": -1.05,
      "net_total_price": 6.81,
      "gross_total_price": 8.1
    },
    {
      "article_number": "555",
      "name": "clothes-2",
      "description": "Use it to feel way better-2",
      "category": "Lifestyle_2",
      "tax_rate": 7.0,
      "quantity": 0.6,
      "unit": "refund unit 2",
      "net_unit_price": 3.71,
      "gross_unit_price": 3.97,
      "net_unit_discount": -0.23,
      "gross_unit_discount": -0.25,
      "net_total_price": 2.08,
      "gross_total_price": 2.23
    }
  ],
  "special_items": [
    {
      "article_number": "delivery-in-eu",
      "name": "delivery costs DHL",
      "description": "delivery costs DHL standard",
      "category": "delivery costs",
      "tax_rate": 7.0,
      "quantity": 1,
      "unit": "refund special items fee",
      "net_unit_price": -4.68,
      "gross_unit_price": -6.0,
      "net_unit_discount": -1.32,
      "gross_unit_discount": 0,
      "net_total_price": -5.58,
      "gross_total_price": -6.0,
      "type": "RETURN_FEE"
    }
  ],
  "vats": [
    {
      "net_amount": 2.08,
      "tax_amount": 0.15,
      "tax_rate": 7.0
    }
  ]
}