Skip to main content

Both success and failure Checkout outcomes result in the customer being redirected back to the returnUrl provided when creating the Checkout. Query string parameters are appended to the returnUrl based on the outcome. These parameters need to be used to determine the outcome of the transaction.

Note: The returnUrl you have provided needs to be able to link the Checkout id with the order on your system in order to be able to reliably handle the response.

Example:

  • Customer places order and your system generates order ID 1234.
  • You create a Checkout for this order and set the returnUrl to https://merchantwebsite.com/order/1234
  • The API responds with id and url. You ensure that this id is linked to the order_id in your system, so that you can match them later.
  • You redirect the customer to the url
  • The customer completes the Checkout and is redirected to the returnUrl with query string parameters appended to it by Verifone. For a successful transaction, the final redirection URL would look like: https://merchantwebsite.com/order/1234?transactionId={transactionId}&checkoutId={checkoutId}
  • Because your return URL uniquely identifies the order_id you know which checkout belongs to the order
  • To determine the outcome, you can read back the Checkout by calling the GET /checkout/{checkoutId} using the id of the Checkout stored earlier and inspect the events field
    • When a transaction was processed successfully the events would look like this:
[
  ...
  {
      "type": "TRANSACTION_SUCCESS",
      "id": "f2041250-4fc2-4b3a-bc94-651ba099541a",
      "timestamp": "2020-07-08T12:42:37.974Z",
      "details": {
          "id": "e88a4127-4c9c-41b3-b0c0-6255ebbea8a7",
          "authorizationCode": "743929",
          "status": "AUTHORIZED",
          "reversalStatus": "NONE",
          "createdAt": "2020-07-08T13:42:28.332+01:00",
          "additionalData": {
              "acquirerResponseCode": "00",
              "initiatorTraceId": "001340",
              "referenceId": "ORDER-1234"
          }
      }
  }
  ...
]

When a transaction processing failed the events would look like this:

[
  ...
  {
      "type": "TRANSACTION_FAILED",
      "id": "f2041250-4fc2-4b3a-bc94-651ba099541a",
      "timestamp": "2020-07-08T12:42:37.974Z",
      "details": {
          "id": "e88a4127-4c9c-41b3-b0c0-6255ebbea8a7",
          "status": "FAILED",
          "reversalStatus": "NONE",
          "createdAt": "2020-07-08T13:42:28.332+01:00"
      }
  }
  ...
]

When a transaction has been declined the events would look like this:

[
  ...
  {
      "type": "TRANSACTION_DECLINED",
      "id": "f2041250-4fc2-4b3a-bc94-651ba099541a",
      "timestamp": "2020-07-08T12:42:37.974Z",
      "details": {
          "id": "e88a4127-4c9c-41b3-b0c0-6255ebbea8a7",
          "status": "DECLINED",
          "reversalStatus": "NONE",
          "createdAt": "2020-07-08T13:42:28.332+01:00",
          "additionalData": {
              "acquirerResponseCode": "05",
              "initiatorTraceId": "001340",
              "referenceId": "ORDER-1234"
          }
      }
  }
  ...
]
  • Note*: To ensure that the redirection request was not tampered with, always check that the transactionId received as query parameter in the redirection matches the transactionId property of the retrieved Checkout. If those are not matching, this is indication of either an incorrect integration, that the redirection to your returnUrl did not originate from Verifone or it was tampered with.
  • You can now store the transactionId value together with the order 1234 in your system to link the two together.

Scenarios

The table below describes the different outcomes of a Checkout. Examples for reproducing the scenarios can be found in the section below it. A full list error codes are available.

Description 3D-Secure Configured Transaction Configured Result Merchant action
Failed transaction* N Y Redirect: checkoutId={checkoutId} & transactionId={transactionId} & errorCode=123 Unsuccessful payment (technical reason), do not display order confirmation.
Failed 3D-Secure Y Y Redirect: checkoutId={checkoutId} & errorCode=140 3DS failed due to technical reason, do not display order confirmation.
Declined transaction N Y Redirect: checkoutId={checkoutId} & transactionId={transactionId} & errorCode=121 Payment reached the acquirer, but was declined (e.g. Insufficient Funds), do not display order confirmation.
Successful transaction Test card: 4000000000001091, expiry: 01/any, cvv: any N Y Redirect: checkoutId={checkoutId} & transactionId={transactionId} Display order confirmation.
Successful 3D-Secure and transaction. Test card: 4000000000001091, expiry: 01/any, cvv: any Y Y Redirect: checkoutId={checkoutId} & transactionId={transactionId} Display order confirmation.
Customer visits the URL of an already completed Checkout - - Redirect: checkoutId={checkoutId} & errorCode=168 Display corresponding message to customer. Checkout is completed whenever there was a single successful payment processed through it.
Customer visits the URL of an expired Checkout - - Redirect: checkoutId={checkoutId} & errorCode=169 Display corresponding message to customer. Checkout is expired whenever the expiryTime is reached
Customer visits the URL of a Checkout which has reached the maximum of failed payment attempts - - Redirect: checkoutId={checkoutId} & errorCode=165 Display corresponding message to customer. Payments through a single Checkout can be attempted up to 3 times unsuccessfully.
Form validation errors / Other service failures on the Checkout page - - Displays error alert to Customer on the page Customer is prompted to correct their form input and retry the payment or try using alternate card or payment method

*** Failed transaction - Depending on which step in the payment process failed, the transactionId might not always be present as the query parameter

About us

Verifone logo

Contact

Support

 

Facebook  Twitter  Linkedin