Authorize transaction

Perform an authorization request for a transaction.

SecurityBearer Authentication
Request
header Parameters
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
required
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
required
string [ 1 .. 50 ] characters

The transaction ID generated by the partner. 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)

The shops contained in the transaction. Shop information is optional if shops are on-boarded beforehand and not dynamically during transaction authorization request.

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
application/json
{
  • "authorization_expires": "2024-02-25T14:43:24.863+02:00",
  • "buyer": {
    },
  • "currency": "EUR",
  • "delivery": {
    },
  • "device": {
    },
  • "options": {
    },
  • "partner_operation_id": "partner-operation-id-1234",
  • "partner_transaction_id": "partner-transaction-id-1234",
  • "payment_details": null,
  • "payment_method": {
    },
  • "shop_baskets": [
    ],
  • "shops": [
    ]
}
Response samples
application/hal+json
{
  • "_links": {},
  • "authorization_expires": "2019-08-24T14:15:22Z",
  • "created": "2019-08-24T14:15:22Z",
  • "payment_details": {
    },
  • "ratepay_transaction_id": "scwBgARW-nE93I7_ywhp"
}