Authorize 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 `return=representation` if you prefer that the response to a request includes the current state of the resource. Value: "return=representation"

Request Body schema: application/json

authorization_expires	string <date-time> The date and time at which remaining uncancelled and uncaptured authorized amount should be cancelled. If not given, a default expiry time is generated. Timestamp with offset according to ISO 8601.
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 transaction creation operation
partner_transaction_id required	string [ 1 .. 50 ] characters The transaction ID generated by the partner. This ID can be displayed in the settlement files.
	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.
	Array of objects (ShopDto) The shops contained in the transaction.

Responses

201

Transaction authorized

400

Bad request

405

Method Not Allowed

406

Not Acceptable

422

Transaction declined

500

Technical problem

post/v2/transactions

Request samples

Payload
curl
JavaScript
Java
Python

application/json

{"authorization_expires": "2023-11-15T10:11:43.930+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_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",
"logo_url": "https://cdn.example.com/a/b/c/logo-fruits-and-more_400x65.png"
},
"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_category_code": "5499",
"name": "fruits and more",
"partner_shop_id": "partner-shop-id-1"
}
]
}

Response samples

application/hal+json

{"_links": {"self": {"href": "https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp"
}
},
"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"
}