Accepting card payments

Overview

There are two different ways to integrate with the Checkout and start accepting card payments. Both solutions share the same Checkout APIs and have a lot in common in terms of integration. You can find both 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. The form is still securely hosted by Verifone, so there no additional PCI scope required for the merchant with this solution.

Required card processing fields

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

entityId - This value can be found in the portal or provided to you by a Verifone employee.
currencyCode
amount
merchantReference
returnUrl
configurations.card.paymentContractId - This id can be found in the portal or given to you by a Verifone employee. This id is used to determine what MID will be used for this Checkout.

Test cards might vary depending on the acquiring connection which is being configured as the Payment Contract.

Optional card processing fields

The configurations.card object stores the parameters required for making a card payment. In this object the fields are:

dynamicDescriptor - Value which is displayed as short text on the bank statement of the cardholder
captureNow - Used for separate authorisation and capture. Read Authorisation for details.
cvvRequired - Used to make CVV input field mandatory on the payment form. Defaults to false.
customer - Id of a Customer created via the Customer API. A customer object can be created and attached to a Checkout. The customer object can store relevant customer details. Some of these details might be required, depending on the payment method and/or authentication mechanisms (e.g. 3DS) used in the Checkout.
threedSecure - Used for 3D-Secure payments. Read Accepting 3-D Secure Payments for details.
authorizationType - Used to indicate what type of authorization is done. Support for this feature varies based on the Payment Contract used.

Optional checkout fields

expiryTime - You can configure Checkout to expire after a certain amount of time. Provide the time in UTC. If a user visits an expired Checkout a redirect will be done to the returnUrl including query parameter as errorCode=169
formSettings - Used to change the text on the Checkout page. Read Changing default text for details.
i18n - Used to configure the language of the Checkout page. Read Localisation for details.

Creating a Checkout

Here is an example POST request with the required fields that can be copied for creating a Checkout. Replace the entityId and paymentContractId with your own.

{
  "amount": 74.55,
  "currencyCode": "EUR",
  "entityId": "{{entityId}}",
  "configurations": {
    "card": {
      "paymentContractId": "{{paymentContractId}}"
    }
  },
  "merchantReference": "SNKRS-7001",
  "returnUrl": "{{merchantReturnUrl}}"
}

The response for creating the checkout will look like this.

{
  "id": "string",
  "url": "string"
}

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

Get loader.js URL

Use the id received by creating a checkout to construct a URL for the loader.js API:

https://checkout_cst.dimebox.com/v1/loader.js?checkoutId=0198563b-9b6f-4050-910c-6180e1bd121c&iframe=true

Note that the iframe query parameter is set to true, which indicates that the loader should inject the payment form as an iframe.

Based on merchant preference, there are 2 possible ways to use this URL. The final result would look identical whichever option is used.

1. Inject <script> inline

The URL created above can be used to place a <script> tag as direct child of an HTML element where the iframe should be rendered. This way the script would automatically create itself in the same place of the HTML document as it's included.

<html>
    <head>
    ...
    </head>
    <body>
    ...
    <div id="payment_form_container">
         <script defer src="https://checkout_cst.dimebox.com/v1/loader.js?checkoutId=0198563b-9b6f-4050-910c-6180e1bd121c&iframe=true"></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="https://checkout_cst.dimebox.com/v1/loader.js?checkoutId=0198563b-9b6f-4050-910c-6180e1bd121c&iframe=true&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 returnUrl specified by the merchant when creating a Checkout. Depending on the result the redirection would include transactionId if a transaction created and/or errorCode if an error has occurred (not present in the example below). The redirection URL for a successful transaction would look like this:

https://merchantwebsite.com/order/1234?transactionId={transactionId}&checkoutId={checkoutId}

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 /checkout/{checkoutId}
In the response, they would find a field events with value as:

[
  ...
  {
      "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"
          }
      }
  }
  ...
]

This indicates that the transaction has been successful, as we see type as TRANSACTION_SUCCESS and details.status with value AUTHORIZED.