Authorize transaction

Perform an authorization request for a transaction.

Idempotency-Keystring

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'return=representation'

According to RFC 7240: Provide return=representation if you prefer that the response to a request includes the current state of the resource. If not provided, the response will only contain the minimal set of attributes .

X-Partnerstring

The partner ID for the operation is required only when using a single credential set for multiple integrations, such as countries or brands associated with one company.

Request body

authorization_expiresstring 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.

currencystring required

The currency of all amounts pertaining to the transaction. Upper-case alphabetic code in accordance with ISO 4217.

partner_operation_idstring

The unique ID generated by the partner or shop to identify an API operation. This ID can be displayed in settlement reports to allow relating settlement report items to API operations. Get an overview of key identifiers used in payment API.

partner_transaction_idstring

The transaction ID generated by the partner (i.e. Partner Order ID). Use the same value as shop_transaction_id unless the shop and integration partner manage separate transaction IDs, such as in PSP (payment service provider) integrations. 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.

Example request

{
  "authorization_expires": "2025-04-02T16:15:18.823+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"
    },
    "contact": {
      "email": "heinz.steeger@example.org",
      "phone": "+49 177 44455553"
    },
    "language": "de",
    "shop_buyer_id": "shop-buyer-id-1234",
    "person": {
      "date_of_birth": "1971-05-19",
      "first_name": "Heinz",
      "last_name": "Steeger",
      "title": "Dr."
    }
  },
  "currency": "EUR",
  "delivery": {
    "first_name": "Heinz",
    "last_name": "Steeger",
    "address": {
      "city": "Berlin",
      "country_code": "DE",
      "street": "Schönhauser Allee",
      "street_addition": "Seitenflügel, 2. HH",
      "street_number": "84",
      "zip_code": "10439"
    }
  },
  "device": {
    "browser": {
      "language": "de-DE",
      "name": "Mozilla Firefox",
      "version": "94.0 (64-bit)"
    },
    "geo_location": {
      "latitude": 52.518368,
      "longitude": 13.325109
    },
    "http_forwarded_ip_address": "123.123.123.123",
    "risk": {
      "reasons": [
        "HIGH_RISK_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_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": "SHIPPING_001",
          "category": "shipping",
          "description": "Standard shipping via DHL",
          "gross_total_price": 5.95,
          "gross_unit_price": 5.95,
          "name": "Shipping costs",
          "net_total_price": 5,
          "net_unit_price": 5,
          "quantity": 1,
          "tax_rate": 19,
          "unit": "shipment"
        }
      ],
      "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": {
        "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"
    }
  ]
}

Response

Transaction authorized

v1

Authorize transaction

Headers

Request body

Example request

Response