Skip to main content

Overview

Checkout can be used in several different ways to start accepting payments. These solutions share the same Checkout APIs and have a lot in common in terms of integration. You can find the integration paths shown in this page.

Hosted Payments Page (HPP)

With this approach the shopper is redirected to a payment page hosted by Verifone to complete the payment. Upon completion of the payment process, the shopper is redirected back to a URL of the merchant.

Iframe

Iframe allows for merchants to display a payment form component as part of their own website, without having to redirect the shopper. *For card payments*: The form is still securely hosted by Verifone, so there are no additional PCI scope required for the merchant with this solution.

Required fields

To configure Checkout for accepting payments the following fields are required:

  • entity_id - This value can be found in the portal or provided to you by a Verifone employee.
  • currency_code
  • amount
  • merchant_reference
  • return_url - URL of the Merchant website to which the shopper would be redirected back
  • configurations - Object with one or more payment method configurations

Optional checkout fields

  • expiry_time - Expiry time of the Checkout page. Defaults to 15 min from creation time. If a user tries to visit or use an expired Checkout, there will be an error
  • i18n - Language preferences for the page. Read Localisation for details.
  • line_items - List of shopping cart items, to be displayed on the page.
  • display_line_items - Indicates whether line items should be displayed on the page
  • interaction_type - Indicates the type of integration

Creating a Checkout

Here is an example body creating a Checkout to be used as a Hosted Payments Page (default interaction_type)

{
  "amount": 74.55,
  "currency_code": "EUR",
  "entity_id": "{{entity_id}}",
  "configurations": {
    "{{payment_method}}": {
      // varies per payment_method
    }
  },
  "merchant_reference": "SNKRS-7001",
  "return_url": "https://merchantwebsite.com/order/1234",
  "interaction_type": "HPP" // also default value
}

The response for creating the checkout will look like this.

{
  "id": "38615263-ed67-4774-bddd-7407edc0b700",
  "url": "{{host}}/v2/checkout/38615263-ed67-4774-bddd-7407edc0b700/view"
}

 

Here is an example body for creating a Checkout to be used as Iframe.

{
  "amount": 74.55,
  "currency_code": "EUR",
  "entity_id": "{{entity_id}}",
  "configurations": {
    "{{payment_method}}": {
      // varies per payment_method
    }
  },
  "merchant_reference": "SNKRS-7001",
  "return_url": "{{merchant_return_url}}",
  "interaction_type": "IFRAME"
}

The response for creating the checkout will look like this.

{
  "id": "38615263-ed67-4774-bddd-7407edc0b700",
  "url": "{{host}}/v2/loader.js?checkoutId=38615263-ed67-4774-bddd-7407edc0b700"
}

Displaying payment to the shopper

Redirect the shopper to the url received as response of creating a Checkout. They will see a ready to use payment page, displaying a summary of the payment details and the option to do a payment
 1. Inject <script> inline

The url from the response above can be used to place a <script> tag as direct child of an HTML element where the iframe should be displayed. This way the script would automatically render the payment form in the same place of the HTML document as it's included.

<html>
    <head>
    ...
    </head>
    <body>
    ...
    <div id="payment_form_container">
         <script defer src="{{host}}/v2/loader.js?checkoutId=38615263-ed67-4774-bddd-7407edc0b700"></script>
    </div>     
    </body>
</html>
2. Inject script anywhere on the page

The script can also be included anywhere in the merchant's HTML, as long as there is a containerId query parameter provided pointing to the ID of the parent HTML element in which the form should be displayed. So, if the desired parent element is a <div> with id "payment_form_container", this can can look like:

<html>
    <head>
    ...
        <script defer src="{{host}}/v2/loader.js?checkoutId=38615263-ed67-4774-bddd-7407edc0b700&containerId=payment_form_container"></script>  
    </head>
    <body>
    ...
    <div id="payment_form_container">
    </div>     
    </body>
</html>

 

Handling payment response

Whenever a payment is performed by a shopper through an HPP or Iframe, it will result in a redirection to the return_url specified by the merchant when creating a Checkout. Depending on the result the redirection would include transaction_id if a transaction is created and/or error_code if an error has occurred. The redirection URL for a successful transaction would look like this:

https://merchantwebsite.com/order/1234?transaction_id={transaction_id}&checkout_id={checkout_id}

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

Note: The return_url 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 return_url 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 return_url 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?transaction_id={transaction_id}&checkout_id={checkout_id}
  • 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 /v2/checkout/{checkout_id} using the id of the Checkout stored earlier and inspect the events field
  • Note*: To ensure that the redirection request was not tampered with, always check that the transaction_id received as query parameter in the redirection matches the transaction_id property of the retrieved Checkout. If those are not matching, this is indication of either an incorrect integration, that the redirection to your return_url did not originate from Verifone or it was tampered with.
  • You can now store the transaction_id value together with the order 1234 in your system to link the two together.
Read Checkout

In order to determine the final outcome of the Checkout, the merchant should query the checkout by doing a Server-to-Server call to GET /v2/checkout/{checkout_id}
In the response, they would find a field events.

Successful transaction response:

[
  ...
  {
      "type": "TRANSACTION_SUCCESS",
      "id": "f2041250-4fc2-4b3a-bc94-651ba099541a",
      "timestamp": "2020-07-08T12:42:37.974Z",
      "details": {
         // varies per payment method
      }
  }
  ...
]

Failed transaction response:

[
  ...
  {
      "type": "TRANSACTION_FAILED",
      "id": "f2041250-4fc2-4b3a-bc94-651ba099541a",
      "timestamp": "2020-07-08T12:42:37.974Z",
      "details": {
         // varies per payment method
      }
  }
  ...
]

The exact list of event types and the keys in the details object vary per payment method.

 Next steps

- Card payments
- Card payments with 3D Secure

About us

Verifone logo

Contact

Support

 

Facebook  Twitter  Linkedin