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
POSTrequest to the following URL:
https:// {environment} /transaction/management/v2/transactions -
Save the
ratepay_transaction_idfrom the response for further requests.
Payload
Open Invoice (B2C)Open Invoice (B2B)Direct Debit (B2C)Direct Debit (B2B)
{
"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
}
]
}
]
}{
"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
}
]
}
]
}{
"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
}
]
}
]
}{
"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)
-
Shopping cart details (including the
-
Make a
POSTrequest to the following URL:
https:// {environment} /transaction/management/v2/transactions/ {ratepayTransactionId} /cancellations
Payload
With items (recommended)Without items
{
"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
}
]
}{
"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)
-
Shopping cart details (including the
-
Make a
POSTrequest to the following URL:
https:// {environment} /transaction/management/v2/transactions/ {ratepayTransactionId} /captures
Payload
With items (recommended)Without items
{
"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
}
]
}{
"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)
-
Shopping cart details (including the
-
Make a
POSTrequest to the following URL:
https:// {environment} /transaction/management/v2/transactions/ {ratepayTransactionId} /refunds
Payload
With itemsWithout items
{
"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
}
]
}{
"partner_shop_id": "PROVIDED_BY_RATEPAY",
"partner_operation_id": "refund-id-1234",
"gross_amount": 16.9
}