Basket Amount Validation

Many operations of the Payment API allow providing a list of items and special items. It is highly recommended to always include items and special items as item information, so it can be included in the Ratepay buyer communication. Item information is also important to resolve dispute cases promptly.

If items are included in a request body, their sum must match the overall gross amount given in the request. Otherwise, the Payment API rejects the request as unprocessable operation (HTTP status code 422) with one of the following decline reasons:

  • SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT - returned in case of authentication requests
  • SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT - returned in case of all other follow-up operations like capture or refund transaction

Marketplace Transactions

In case of a marketplace integration, multiple baskets may be provided in the transaction authentication request. Besides a basket specific gross amount, each basket may contain a list of items. The above described validation is always performed on basket level individually. The allowed divergence is therefore also only applied on each single basket, but not on the overall marketplace transaction.

Details of Amount Validation

The Payment API uses the following algorithm to compute the gross amount:

Copy
Copied
gross amount = sum[ round( (gross unit price - gross unit discount) * item quantity ) ]

Besides the formula used by the Payment API as shown above, there are other valid mathematical methods how to compute the overall sum of items. This might lead to slightly differing gross amounts. Therefore, the Payment API allows the gross amount given in the request to slightly diverge from the internally computed value.

The allowed difference is computed as follows:

Copy
Copied
allowed difference = sum[ item quantity ] * 0.02

Gross amount is considered to be valid if

  • it is up to allowed difference higher than amount computed by the Payment API or
  • it is up to allowed difference lower than amount computed by the Payment API.

Please note: The gross amount is the only considered value when the transaction is claimed. Diverging basket gross amounts do not influence the claim in any way.