Perform an authorization request for a transaction.
Idempotency-Key | string <= 64 characters ID generated by client to uniquely identify the request. It is highly recommended to use a UUID version 4. Do not reuse an idempotency key for different calls. See Idempotency for further details. |
Prefer | string According to RFC 7240: Provide |
authorization_expires | string <date-time> The date and time when remaining un-cancelled and un-captured authorized amount will be automatically cancelled. Timestamp with offset according to ISO 8601. If not given, a default expiry time is generated. |
required | object (BuyerDto) The buyer that wants to place the transaction. |
currency required | string[A-Z]{3} The currency of all amounts pertaining to the transaction. Upper-case alphabetic code in accordance with ISO 4217. |
object (DeliveryDto) The delivery address and additional delivery parameters. | |
object (DeviceDto) The device used to initiate the transaction. | |
object (OptionsDto) The options controlling transaction processing. | |
partner_operation_id | string [ 0 .. 255 ] characters Arbitrary ID of partner for the operation. This ID can be displayed in settlement reports. Get an overview of key identifiers used in payment API. |
partner_transaction_id | string [ 1 .. 50 ] characters The transaction ID generated by the partner. This field must be included in at least one of the following requests: authorization or capture.This ID can be displayed in settlement reports. Get an overview of key identifiers used in payment API. |
object (PaymentDetailsRequestDto) Provides details about the payment to be executed by Ratepay. Applicable only in case of transfer-type SEPA_DIRECT_DEBIT. | |
required | object (PaymentMethodDto) The payment method selected by the buyer. |
required | Array of objects (ShopBasketDto) One basket for each shop contained in the transaction. The definition of multiple shops is only relevant for marketplace integrations. If items and special items are included in the basket, gross amount must match the sum of all items. See basket amount validation page for additional details. |
Array of objects (ShopDto) Enables eligible partners, usually PSPs (payment service providers), to submit necessary information for registering a new shop when processing their first transaction authorization or updating information for an already registered shop. |
Transaction authorized
Bad request
Transaction declined
Technical problem
{- "authorization_expires": "2024-10-08T13:34:10.205+02:00",
- "buyer": {
- "billing_address": {
- "city": "Berlin",
- "country_code": "DE",
- "street": "Schönhauser Allee",
- "street_addition": "Seitenflügel, 2. HH",
- "street_number": "84",
- "zip_code": "10439"
}, - "company": null,
- "contact": {
- "email": "heinz.steeger@example.org",
- "phone": "+49 177 44455553"
}, - "language": "de",
- "person": {
- "date_of_birth": "1971-05-19",
- "first_name": "Heinz",
- "last_name": "Steeger",
- "title": "Dr."
}, - "shop_buyer_id": "shop-buyer-id-1234"
}, - "currency": "EUR",
- "delivery": {
- "address": {
- "city": "Berlin",
- "country_code": "DE",
- "street": "Schönhauser Allee",
- "street_addition": "Seitenflügel, 2. HH",
- "street_number": "84",
- "zip_code": "10439"
}, - "company": "Berlin Advertising Agency",
- "first_name": "Heinz",
- "full_name": null,
- "in_store_collect": null,
- "last_name": "Steeger",
- "pick_up_box": null,
- "pick_up_shop": null
}, - "device": {
- "browser": {
- "language": "de-DE",
- "name": "Mozilla Firefox",
- "version": "94.0 (64-bit)"
}, - "finger_print": "bc47575c-7f93-4bae-84dc-282edf6a5d85",
- "geo_location": {
- "latitude": 52.518368,
- "longitude": 13.325109
}, - "http_forwarded_ip_address": "123.123.123.123",
- "risk": {
- "reasons": [
- "RISKY_DEVICE_BEHAVIOR"
], - "score": 123
}, - "screen": {
- "height": 1080,
- "width": 1920
}, - "source_ip_address": "10.17.1.1",
- "token": "ade028c1-d2a2-4189-9214-e21089cd47f1"
}, - "options": {
- "sales_channel": "POINT_OF_SALE"
}, - "partner_operation_id": "partner-operation-id-1234",
- "partner_transaction_id": "partner-transaction-id-1234",
- "payment_details": null,
- "payment_method": {
- "payment_option": "OPEN_INVOICE",
- "transfer_type": "BANK_TRANSFER"
}, - "shop_baskets": [
- {
- "gross_amount": 67.6,
- "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"
}
], - "partner_shop_id": "partner-shop-id-1",
- "shop_merchant_id": "ratepay-merchant-id-123",
- "shop_transaction_id": "shop-transaction-id-1234",
- "special_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,
- "type": "RETURN_FEE",
- "unit": "piece"
}
], - "vats": [
- {
- "net_amount": 56.81,
- "tax_amount": 10.79,
- "tax_rate": 19
}
]
}
], - "shops": [
- {
- "correspondence_settings": {
- "branding_settings": {
- "highlight_color": "#badb11",
- "logo_position": "RIGHT",
}, - "slangs": {
- "de": {
- "customer_service_contact": [
- "You can reach our customer service Mon - Sun 7 am to 8 pm",
- "by mail: customer-service@example.com",
- "by phone: 030 / 123 456 789",
- "contact form: example.com/contact"
], - "formal_tone": "INFORMAL",
- "name_format": "FIRST_LAST_NAME",
- "salutation": "Hello",
- "transaction_type": "ORDER"
}, - "en": {
- "customer_service_contact": [
- "You can reach our customer service Mon - Sun 7 am to 8 pm",
- "by mail: customer-service@example.com",
- "by phone: 030 / 123 456 789",
- "contact form: example.com/contact"
], - "formal_tone": "INFORMAL",
- "name_format": "FIRST_LAST_NAME",
- "salutation": "Hello",
- "transaction_type": "ORDER"
}, - "fr": {
- "customer_service_contact": [
- "You can reach our customer service Mon - Sun 7 am to 8 pm",
- "by mail: customer-service@example.com",
- "by phone: 030 / 123 456 789",
- "contact form: example.com/contact"
], - "formal_tone": "INFORMAL",
- "name_format": "FIRST_LAST_NAME",
- "salutation": "Hello",
- "transaction_type": "ORDER"
}, - "nl": {
- "customer_service_contact": [
- "You can reach our customer service Mon - Sun 7 am to 8 pm",
- "by mail: customer-service@example.com",
- "by phone: 030 / 123 456 789",
- "contact form: example.com/contact"
], - "formal_tone": "INFORMAL",
- "name_format": "FIRST_LAST_NAME",
- "salutation": "Hello",
- "transaction_type": "ORDER"
}
}
}, - "legal": {
- "commercial_register_number": "HRB 12345FF",
- "legal_form": "GmbH",
- "name": "Fruits and more GmbH"
}, - "merchant": {
- "merchant_id": "ratepay-merchant-id-123",
- "merchant_name": "Merchant XYZ"
}, - "merchant_category_code": "5499",
- "name": "fruits and more",
- "partner_shop_id": "partner-shop-id-1"
}
]
}
{- "_links": {
}, - "authorization_expires": "2019-08-24T14:15:22Z",
- "created": "2019-08-24T14:15:22Z",
- "payment_details": {
- "deposit_bank_account": {
- "bank_name": "Example Bank",
- "bic": "EXBANKXXX",
- "iban": "DE12345678901234567890",
- "owner": "Ratepay GmbH"
}, - "ratepay_payment_reference": "ET1285368M8",
- "ratepay_payment_references": [
- {
- "partner_shop_id": "partner-shop-id-1",
- "ratepay_payment_reference": "ET1285368M8"
}
]
}, - "ratepay_transaction_id": "scwBgARW-nE93I7_ywhp"
}