Managing the timeout

Processing a web service query revolves around a series of asynchronous events such as:

  • sending the query via the network of the merchant website,
  • transmitting information on the Internet,
  • payment processing by the payment gateway,
  • soliciting bank servers, etc.

An incident may occur at any of these steps which would slow down the processing (and, therefore, the delay for the buyer).

The response to a query may be slowed down for several reasons:

  • The response from the cardholder's card issuer is taking a long time (in case of foreign cards, periods of heavy workload, e.g. during sales, etc.).
  • The response from the acquirer when transmitting and receiving the authorization request is taking a long time.
  • The response from your application is taking a long time due to heavy workload.
  • The response from the payment gateway is taking a long time.
  • A peering problem on the Internet which may lead to losing messages, etc.

Depending on the configured timeouts, you may have to wait for an answer while the asynchronous processing is still performed by the payment gateway.

Long processing time should not be considered a declined payment.

For this reason, you must configure your code to handle potential problems that may occur when connecting to the SOAP API.


The average time for processing a payment request by the payment gateway is less than 5 seconds.

You must configure a timeout of 20 to 30 seconds between:

  • the merchant server and the payment gateway,
  • the mobile application and the merchant server.

During the waiting time, a message must clearly state to the buyer that their payment is in progress.

Once the timeout expires, you must indicate to the buyer that their payment has been rejected.

In order to correctly generate these timeout cases, we recommend 2 solutions:

  • Creating your transactions in manual validation mode
    The merchant server must return a request to validate each successful transaction.
    The transactions made after the timeout will not be validated and will expire (after 7 days for a payment performed within the CB network).
    Once expired, they will not be able to be captured at the bank.
    The buyer will not be debited.

  • Creating your transactions in automatic validation mode
    The merchant server must interrogate the payment gateway to cancel the transaction or refund the buyer for each request received after the timeout.
    For this, the merchant server will have to make sure to transmit a unique order identifier in the payment requests.
    Then, for each transaction received after the timeout, the merchant server must
    • interrogate the payment gateway to retrieve the UUID and the status of the corresponding transaction (findPayments method)
      If the UUID does not exist, it means that a technical error has made creating the transaction impossible.
      If the transaction has a REFUSED status, no action is necessary.
    • cancel or refund the transaction (using the cancelPayment or refundPayment methods) if the authorization request was accepted during the timeout.