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:

warning

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

Client ID	Client Secret	partner_shop_id
`snbFcxD4Rxt2O4YqeGqDls9yrGWYhmQ0`	`IHa7jiW0hMlH0VsoxDTZ03XH76NED7RwFvJLsmmUXg9fkowhiVQqp7EA84WoYT1Q`	`INTEGRATION_TE_DACH`

Authorize transaction

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

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
- Device details
- Payment details
- Shopping cart details (including the partner_shop_id , which will be provided by Ratepay)
Make a POST request to the following URL:
https:// {environment} /transaction/management/v2/transactions
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",
      "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",
      "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",
      "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",
      "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

Request an OAuth token from the Authentication API .
Prepare your headers as follows:
- Content-Type: application/json
- Authorization: Bearer {oauthToken}
Prepare the payload:
- Shopping cart details (including the partner_shop_id , which will be provided by Ratepay)
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",
  "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",
  "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

Request an OAuth token from the Authentication API .
Prepare your headers as follows:
- Content-Type: application/json
- Authorization: Bearer {oauthToken}
Prepare the payload:
- Shopping cart details (including the partner_shop_id , which will be provided by Ratepay)
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",
  "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",
  "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

Request an OAuth token from the Authentication API .
Prepare your headers as follows:
- Content-Type: application/json
- Authorization: Bearer {oauthToken}
Prepare the payload:
- Shopping cart details (including the partner_shop_id , which will be provided by Ratepay)
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",
  "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",
  "partner_operation_id": "refund-id-1234",
  "gross_amount": 16.9
}

Copy

Copied

{
  "partner_shop_id": "PROVIDED_BY_RATEPAY",
  "partner_operation_id": "refund-id-1234",
  "gross_amount": 4.33,
  "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
    }
  ]
}