Error handling

Do Not Try Again & Excessive Reattempts

In accordance with directives from Visa and Mastercard there are 2 different types of limitations in the amount of successive reattempts of previously failed transaction using unscheduled_purchase or recurring_purchase

One such limitation will be limiting the amount of successive reattempts of a previously failed transaction that can be done using creditcard based payment method within a specified period The limitation in question varies based on the card brand:

• MasterCard - 10 failed payment attempts allowed during a period of 24 hours.
• Visa - 15 failed payment attempts allowed during a period of 30 days.

Note that all of the attempts has to get a failed response to be added to the limit quota - if a transaction goes through successfully, the quota will reset.

The other limitation is in the case that Visa or Mastercard gives such a response that is flagged as “Do Not Retry” in accordance to Visa and MasterCard regulations. This response is given in the cases that they deem the transaction to never be possible to be valid - as an example, if the card no longer exists, and thus there is no point in retrying.

In these cases, the card will be blocked immediately and no further attempts are allowed.

Both of these limitations are based on the combination of the acquiring agreement that the transaction was initiated from, and the PAN of the card that was used. That is, a card might be blocked because of "Excessive Reattempts" at a particular merchant, while being allowed more reattempts at another. Please note that in the case a new card is issued in place of an old expired one, the new card usually keeps the same PAN - meaning that if the old card was blocked, the new one will be as well (until the period resets). This marks the importance of having such a logic in place that limits reattempts before the block actually takes place - this is where the new, clearer response messages will help.

info

Merchant is resposible for managing their retry policy for payments that fails, and not retry when payment fails with DO_NOT_RETRY error. Insufficient error handling will cause cards to be blocked

payex.creditcard authorization error example

A 200 response will be returned if the pay request fail because of authorization error. The transaction will have status FAILED and more information about the cause can be found in the AUTHORIZE event

{
  "id": "...",
  "status": "FAILED",
  "events": [
    {
      "event": "INITIALIZE",
      "success": true
    },
    {
      "event": "AUTHORIZE",
      "success": false,
      "error": {
        "type": "REJECTED_BY_ACQUIRER_POSSIBLE_FRAUD",
        "code": "payex:errorCode:REJECTED_BY_ACQUIRER_POSSIBLE_FRAUD",
        "message": "payex:errorDescription:Wrong card-no check digit response-code: 34",
        "result_code": "34"
      }
    }
  ]
}

Prevent duplicate transactions

Use the Dintero-Feature-Toggles header to prevent creating duplicate transactions.

Including strict-merchant-reference value in the header will prevent creating duplicate transaction as it will require the merchant_reference to be unique within 24 hours

headers

Dintero-Feature-Toggles: strict-merchant-reference
Content-Type: application/json

body

{
  "session": {
    "url": {
      "callback_url": "https://example.com/callback?method=GET"
    },
    "customer": {
      "tokens": {
        "payex.creditcard": {
          "payment_token": "<token previously acquired>"
        }
      }
    },
    "order": {
      "amount": 29990,
      "currency": "NOK",
      "vat_amount": 6000,
      "merchant_reference": "order-1"
    },
    "configuration": {}
  },
  "payment": {
    "payment_product_type": "payex.creditcard",
    "operation": "unscheduled_purchase"
  }
}

A 400 response will be returned if merchant_reference was duplicated

{
    "session_id": "T11223445.5cyWnV68vzJ1kYjZPrKWWm",
    "error": {
        "message": "session.order.merchant_reference",
        "code": "DUPLICATE"
	}
}