Serverside Scripting

When a customer initiates a checkout on your site, your server will have to handle several requests and responses with the Converge API gateway. Your serverside scripting will have to complete the following steps to create a payment session so that your customer can continue their checkout:

  1. Capture a shopper's purchase as an order object.
  2. POST that information to the Orders endpoint.
  3. Use the returned information to create a payment session.
  4. Return the payment session resource URL to the client.

After completing these steps, your client-facing code will redirect the shopper to the Hosted Payments Page. The shopper will enter their payment information and confirm the purchase.

Flowchart of the steps required to create a payment session.

Creating an Order

Every payments session using the Hosted Payments Page is built around an order. At a minimum, the order represents the amount and currency to process with a transaction, but usually includes more information about what is actually being purchased in a transaction and where the purchase should be shipped to after the transaction is complete.

The Total

The minimum requirement of every order is a total. The total contains the amount to be processed in the transaction and the currency code for the type of currency the amount is measuring.

{
  "total": {
    "amount": "3.23",
    "currencyCode": "EUR"
  }
}

While this is all it takes to create an order, you can include more information. Depending on your data capture settings, the Hosted Payments Page may prepopulate some fields with the values provided in the order. 

Items

An order can include an array of items to track line-item purchases and costs for an order. Each item needs a total.

{
  "total": {
    "amount": "3.23",
    "currencyCode": "EUR"
  },
  "description": "parts",
  "items": [
    {
      "total": {
        "amount": "1.00",
        "currencyCode": "EUR"
      },
      "description": "widget"
    },
    {
      "total": {
        "amount": "2.00",
        "currencyCode": "EUR"
      },
      "unitPrice": {
        "amount": "1.00",
        "currencyCode": "EUR"
      },
      "quantity": 2,
      "description": "cogs",
      "type": "goods"
    },
    {
      "total": {
        "amount": ".23",
        "currencyCode": "EUR"
      },
      "description": "tax",
      "type": "tax"
    }
  ]
} 

 

Order Total vs. Item Totals
The Order total is an independent entity from the item totals and can be greater than, less than, or equal to the sum of the item totals.

ShipTo

If you've collected shipping information for an order before initiating a payment session, you can include the information in the order as the shipTo property.  An example shipTo property is:

"shipTo": {
  "fullName": "Mecha Godzilla",
  "company": "Danger Inc.",
  "street1": "5555 foo bar ct.",
  "city": "London",
  "countryCode" : "DEU"
}  

You can view a full writeup of the orders and their components in the Orders resource.

Create the Order

Now that you've created the JSON object for the order on your server, you need to create the order in Converge by sending a POST request containing the object to the /orders endpoint of the Converge API.

When Converge receives the POST request, it will send a response confirming the creation of the order resource.

{
  "href": "https://api.eu.convergepay.com/orders/p7hxrvrpgfc68w6gm7q3b47y",
  "id": "p7hxrvrpgfc68w6gm7q3b47y",
  "createdAt": "2019-04-22T18:52:10.920Z",
  "modifiedAt": "2019-04-22T18:52:10.920Z",
  "merchant": "https://api.eu.convergepay.com/merchants/XrDXRBh9YHxwqQTj2Cmq7j49",
  "total": {
    "amount": "3.23",
    "currencyCode": "EUR"
  },
  "description": "parts",
  "shipTo": null,
  "shopperEmailAddress": null,
  "shopperReference": null,
  "customReference": null
}

The href property of the response contains the resource URL for the created order. This will be required to create the payment session. For more information, see the Payment Sessions resource.

Create the Payment Session

Now that you've created an order and have the id pointing to it, you can create a payment session. A payment session requires an order as a minimum to be created. This can be done by passing the value of the href property value returned from creating an order. You also need to include URLs to redirect a customer after they complete or cancel a transaction on the Hosted Payments Page. 

{  
  "order": "https://api.eu.convergepay.com/orders/p7hxrvrpgfc68w6gm7q3b47y",
  "returnUrl": "https://merchant.com/return",
  "cancelUrl": "https://merchant.com/cancel",
  "doCreateTransaction" : true
}

The response from the POST request to the payment session resource will include the URL's you will use to redirect your user to the Hosted Payments Page or to open the Lightbox modal.

Capturing Data Before or During a Payment Session

Depending on the setting you selected for your Hosted Payments Page and what information you capture prior to creating an order and payment session, your users will receive a different experience on the payment page. 

  1. Address Data Capture: Billing and/or Shipping Address data captured prior to initiating a payment session is displayed statically with an option to edit.
  2. Email Address Capture: If an email address isn’t captured before the session, an additional section is included to capture that data.
Address Data Capture

There are three configurations that can be included on the Hosted Payments Page:

  • Payment Info Only
  • Payment Info and Billing Address
  • Payment Info, Billing Address, and Shipping Address

Remember that this setting impacts whether Billing/Shipping fields are displayed on the HPP form. In either case, merchants can still capture this info as part of the transaction by capturing it prior to initiating the payment session and passing it as the shipTo property of an order or the billTo property of a payment session.

Data pass-through refers to data that is captured by the merchant and provided to the HPP session prior to initiating the session.

Address Data can be:

  • Captured and passed-through completely prior to the Hosted Payments Page session by including the shipTo property of the orders resource and the billTo property of the /payment-sessions resource.
  • Captured and passed-through partially prior to the Hosted Payments Page session by using either by including either the shipTo property of the orders resource or the billTo property of the /payment-sessions resource.
  • Not passed-through in which case it will be captured as the customer fills out the Hosted Payment Form.

Card details cannot be passed-through as this would defeat the point of using a Hosted Payments Form and would require that the server handling these pieces of data pass strict PCI regulatory compliance.

If address data is passed to the payment session, it will be captured as part of the transaction. However, It only displays on the Hosted Payments Page form (and made available for cardholder review/edit) if those fields are enabled from the Hosted Payments Settings Page in the Converge Virtual Terminal.

If you do not pass address data, it will only be captured if those fields are enabled from the Hosted Payment Settings page in the Converge Virtual Terminal. Address data will then be captured when the shopper enters their payment info into the Hosted Payment Form.

Billing Address and 3-D Secure
You can increase your chances of getting a frictionless 3-D Secure 2 experience by capturing Billing Address as part of a transaction. We highly recommend either capturing billing information prior to creating a payment session or including billing address fields in your Hosted Payments Form

 

Data Captured Prior to Session Hosted Payments Settings in the Virtual Terminal Result

None (Order/Amount only)

Payment Info Only

  • Payment fields display for capture on the Hosted Payments Form

Payment Info and Billing Address

  • Payment and billing address fields display for capture on the Hosted Payments Form

Payment Info, Billing, and Shipping Address

  • Payment and both address fields display for capture on the Hosted Payments Form

Billing Address

Payment Info Only

  • Payment fields display for capture on the Hosted Payments Form

  • Billing address is captured but not displayed on the Hosted Payments Form

Payment Info and Billing Address

  • Payment fields display for capture on the Hosted Payments Form

  • Billing address is captured and displayed on the Hosted Payments Form as editable form fields

Payment Info, Billing, and Shipping Address

  • Payment fields display for capture on the Hosted Payments Form

  • Billing address is captured and displayed on the Hosted Payments Form as editable form fields

  • Shipping address fields display for capture on the Hosted Payments Form

Billing and Shipping Address

Payment Info Only

  • Payment fields display for capture on the Hosted Payments Form

  • Billing and shipping addresses are captured but not displayed on the Hosted Payments Form

Payment Info and Billing Address

  • Payment fields display for capture on the Hosted Payments Form

  • Billing address is captured and displayed on the Hosted Payments Form as editable form fields

  • Shipping address is captured, but not displayed on the Hosted Payments Form

Payment Info, Billing, and Shipping Address

  • Payment fields display for capture on the Hosted Payments Form

  • Billing and shipping addresses are captured and displayed on the Hosted Payments Form as editable form fields
Email Address Data Capture

Merchants can choose to email sales and refund receipts using a Converge-generated receipt. This setting is controlled from the Receipt Settings page in the Converge Virtual Terminal.

If a merchant chooses to send sales and/or refund receipts through Converge but doesn't capture and pass the email address prior to initiating the payment session, then a section to capture this information is appended to the bottom of the HPP form.

The ‘Send Receipt To’ section captures the email address to send a receipt to if the payments session is not passed an address when it is created.

All versions of the HPP can have this section appended to the bottom of the form.

Results Page

Merchants can opt to use the Converge Hosted Payments Page to run the transaction from start to finish. If the merchant uses Converge to complete the payment, a Converge-generated transaction result page will appear once payment has been processed.

The transaction results page works for both Lightbox and Full Page redirect formats.

Executing the Transaction

You can control how the Hosted Payments Page executes the transaction using the doCreateTransaction property.

If doCreateTransaction is set to true, Converge will immediately use the information captured from the Hosted Payments Page to create a transaction. For simplicity, we recommend setting doCreateTransaction to true.

If doCreateTransaction is set to false (its default value), then the Hosted Payments Page will return a tokenized hosted card that they can use to initiate the transaction using the Transactions resource in the API. For more information, see Hosted Cards.

{
  "order": "https://api.eu.convergepay.com/orders/p7hxrvrpgfc68w6gm7q3b47y",
  "returnUrl": "https://merchant.com/return",
  "cancelUrl": "https://merchant.com/cancel",
  "doCreateTransaction" : true
}

Next Steps

The next steps will be slightly different depending on whether you are presenting the Hosted Payments Page using the lightbox or redirect options.

Next: Hosted Payments Lightbox

Next: Hosted Payments Redirect