# For marketplaces (one or multiple shop entities per transaction)

Before using the Payment API, you must request a OAuth token via the [Authentication API](/docs/developer/authentication/authentication/) 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](mailto: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](/apis/payment/openapi/payment_api/transaction-management/createtransaction) you can find more informations about the endpoints, possible parameters and descriptions in detail.

### Usage

1. Request an OAuth token from the [Authentication API](/docs/developer/authentication/authentication/).
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


```json Open Invoice (B2C)
{
  "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
        }
      ]
    }
  ]
}
```


```json Open Invoice (B2B)
{
  "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
        }
      ]
    }
  ]
}
```


```json Direct Debit (B2C)
{
  "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
        }
      ]
    }
  ]
}
```


```json Direct Debit (B2B)
{
  "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](/apis/payment/openapi/payment_api/cancellation/canceltransaction) you can find more informations about the endpoints, possible parameters and descriptions in detail.

### Usage

1. Request an OAuth token from the [Authentication API](/docs/developer/authentication/authentication/).
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


```json With items (recommended)
{
  "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
    }
  ]
}
```


```json Without items
{
  "partner_shop_id": "PROVIDED_BY_RATEPAY_1",
  "partner_operation_id": "cancel-id-1234",
  "gross_amount": 16.9
}
```

## Capture transaction

[Here](/apis/payment/openapi/payment_api/capture/capturetransaction/) you can find more informations about the endpoints, possible parameters and descriptions in detail.

### Usage

1. Request an OAuth token from the [Authentication API](/docs/developer/authentication/authentication/).
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


```json With items (recommended)
{
  "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
    }
  ]
}
```


```json Without items
{
  "partner_shop_id": "PROVIDED_BY_RATEPAY_1",
  "partner_operation_id": "capture-id-1234",
  "gross_amount": 16.9
}
```

## Refund transaction

[Here](/apis/payment/openapi/payment_api/refund/refundtransaction) you can find more informations about the endpoints, possible parameters and descriptions in detail.

### Usage

1. Request an OAuth token from the [Authentication API](/docs/developer/authentication/authentication/).
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


```json With items
{
  "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
    }
  ]
}
```


```json Without items
{
  "partner_shop_id": "PROVIDED_BY_RATEPAY_1",
  "partner_operation_id": "refund-id-1234",
  "gross_amount": 16.9
}
```


```json With items and buyer return fee
{
  "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
    }
  ]
}
```