RAratepay
Transaction management

Authorize transaction

Changed on

Perform an authorization request for a transaction.

post/v2/transactions

Request

  • Base URL
    https://api-integration.ratepay.com/transaction/management
  • URL
    https://api-integration.ratepay.com/transaction/management/v2/transactions
  • Auth
    HTTP bearer

Headers

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."
    }
  },
  "compliance_details": {
    "attestation_token": "eyJhbGciOiJSUzI1NiJ9..."
  },
  "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

authorization_expiresstring date-time required

The date and time when remaining un-cancelled and un-captured authorized amount will be automatically cancelled. Timestamp with offset according to ISO 8601.

createdstring date-time required

Timestamp with offset according to ISO 8601.

resultstring required

Indicates the outcome of the transaction request. Possible value : ACCEPTED – The transaction has been successfully authorized and can proceed to capture.

ratepay_transaction_idstring required

ID of transaction generated by Ratepay during authorization. A transaction ID is generated for both accepted and declined transactions. Get an overview of key identifiers used in payment API.

Example response

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

Changes

  • ede6eb0c55d8Revision changes
    • warning

      added the new BASKET_LIMIT_EXCEEDED_FOR_CREDIT_SCORE enum value to the // response property for the response status

    • warning

      added the new BUYER_LIMIT_EXCEEDED_FOR_CREDIT_SCORE enum value to the // response property for the response status

    • warning

      added the new BUYER_WITH_BAD_CREDIT_SCORE_REJECTED enum value to the // response property for the response status

    • warning

      added the new BUYER_WITH_NEGATIVE_CHARACTERISTIC_REJECTED enum value to the // response property for the response status

    • warning

      added the new COMPLIANCE_ATTESTATION_TOKEN_VALIDATION_FAILED enum value to the // response property for the response status

    • warning

      added the new CREDIT_RISK enum value to the / response property for the response status

    • info

      added the new optional request property

    • info

      added the optional property / to the response with the status