3. Detailed Integration Specification

3.1 HPP Payment Flow

The diagram provides an illustration of the HPP workflow, which includes the following:
Order Summary page > CPD payment page > Merchant Payment confirmation page

3.2 Request to Invoke HPP

To integrate HPP with your Digital Web Channel or Storefront, integrate a simple form that CPD provides. When you redirect customers to HPP as they checkout to make a payment; a payment page opens outside your shopping cart page.

To redirect your customers to Velocity HPP, send the following request syntax to invoke Velocity HPP as a request.

<!DOCTYPE HTML>
<html>
<body><form action="https://{HPP_HOST}/views/web.php" method="POST" id="order-form">
<input type="hidden" name="country" value="200">
<input type="hidden" name="clientid" value="10022">
<input type="hidden" name="account" value="100220">
<input type="hidden" name="accept-url" value="{accept-url}">
<input type="hidden" name="cancel-url" value="{cancel-url}">
<input type="hidden" name="callback-url" value="{callback-url}">
<input type="hidden" name="orderid" value="1561120588855">
<input type="hidden" name="operator" value="20000">
<input type="hidden" name="language" value="us">
<input type="hidden" name="customer-ref" value="test">
<input type="hidden" name="email" value="[email protected]">
<input type="hidden" name="mobile-country" value="200">
<input type="hidden" name="mobile" value="9898989898">
<input type="hidden" name="amount" value="1.232">
<input type="hidden" name="auth-token" value="E814B1DE-2A6A-4A09-B522-13D5CD9829D1">
<input type="hidden" name="init-token" value="f26ebd24d623f228cb8bc37f30939003ffd1c98b2d24ab8be35e9a881521fc1b4b3f82bf131471ff68a9c716c20af08141ff4a1337f0c31ee8ddc75bedb35fd8">
<input type="hidden" name="nonce" value="12345">
<input type="hidden" name="orderdata" value="{JSON order-data}">
<input type="hidden" name="gtm-data" value="{gtmData}">
<input type="hidden" name="profile-id" value="XC2G6BYDBqibRdO06G1OGZq6OBxM">
<input type="hidden" name=response-content-type" value="2">
   <input type="hidden" name="txntype" value="1|3|5">
<input type="hidden" name="
"additionaldata" value='{
  "additional_data": {
    "param": [
      {
        "name": "session_token",
        "text": "2A6A4A09B52213D5CD9829D1"
      },
      {
        "name": "hold_fee_amount",
        "text": "150"
      },
      {
        "name": "hold_fee_currency_code",
        "text": "608"
      },
      {
        "name": "hold_period",
        "text": "8"
      },
      {
        "name": "stepper",
        "text": "1"
      }   
    ]
  }
}'> 
<input type="submit" value="Pay" class="btn-link">
</form></body></html>

The following table provides a description of the parameters sent in a request:

Parameter

Type

Required

Description

Client id

Integer

Yes

A merchant’s unique ID for Velocity, which CPD creates.

Account

Integer

Yes

The ID of a sub-account with which a payment transaction is associated. The account ID is an integer greater than 100000 and account number is an integer smaller than 1000. CPD provides the account number.

Order id

String

Yes

A unique identification string; it is a passenger name record (PNR) for airlines.

Operator

Integer

The ID of a customer’s mobile network operator. CPD recommends including this parameter in the request to ensure Velocity interacts with the operator accurately.
A typical value is (’country id’ multiplied by 100)

Country

Integer

The ID of a country from which a customer creates a transaction. It is based on the International Organization for Standardization (ISO) country standard numeric code.
Note: If you do not provide country, Velocity uses default client country for the payment routing.

Currency-code

Integer

The ID of a currency using which, a customer creates a transaction. CPD provides this ID.
Note:The list of supported currency is based on the agreement between a merchant and CPD. If you do not provide any currency code, Velocity uses default client country for the payment routing.

Mobile

Integer

The MSISDN of a customer without the International Dialling Code.

String

The email address of a customer.

Customer-ref

String

A unique merchant’s reference ID for a customer. Velocity uses this token to identify a customer. Additionally, the customer reference is included in the request to the specified auth-URL to authenticate the customer when paying with a stored card through the mVault module if single sign-on is used.
Note: If neither country nor currency-code is provided, then the default client country is used for the payment routing.

Amount

Decimal

Yes

The total amount that a customer is charged for a payment transaction in a country’s currency.

Language

String

The default language that Velocity uses when translating the payment pages. Velocity language codes are based on the ISO-639-1 standard.
Refer to http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for details.

Accept-url

String

The absolute URL where Velocity directs the customer after successfully completing a payment transaction.
Note: If you do not provide this parameter, Velocity uses your default accept URL.

Cancel-url

String

The absolute URL where Velocity directs customers if they cancel a payment transaction midway.
Note: If you do not provide this parameter, Velocity uses your default cancel URL.

callback-url

String

The absolute URL of the server-to-server callback.
Note:If you do not provide this parameter, Velocity uses your default call back URL.

auth-token

String

The token sent to a specified auth-URL to authenticate a customer when paying with a stored card through the mVault module if single sign-on is used.

Hmac

String

Yes

The Message Authentication Code. It is calculated by creating a SHA512 hash comprising the following input fields in the listed order:

Parameter	Required
clientid	Yes
orderid	Yes
amount	Yes
country	Yes
mobile	No
mobile-country	No
email	No
deviceid	No
salt	Yes

Using MAC calculation secures the information sent by the merchant to Velocity. It applies the SHA-512 encryption algorithm on key parts of the information sent to protect against tampering. The ‘salt’ is a merchant's shared secret string used to ensure that the provided MAC is unique.

Gtm-data

JSON string

It is a payload for Google Analytics, the details of which are given in another document. It can be made available on request.

Response-content-type

Integer

The format in which merchant gets the redirect response:
Array content type = 1 (default value)
JSON content type = 2

Txntype

Integer

A value to indicate the purchase type such as Search and Book (S&B), Managed My Booking (MYB). The values are:

1 - S & B
3 - MYB
5 – MYB (Disable PCH)
6 - CPL Transaction.
7 - Call Centre Transaction

Additional data

JSON string

The additional data sent from a merchant.

Nonce

String

Yes

Timestamp / random string.

Init-token

String

Yes

This is a combination of SHA512 (clientid+username+password+nonce+accepturl) encryption.
Example:

clientid=10007
username = CPM
password = TEST
nonce = 123435

The above combination generates the following token:
SHA512(10007CPMTEST123435).

Profile-id

String

The profile ID of a customer which is used for fetching the customer’s profile from an external system or Velocity.
Note: This field is mandatory only if merchant wants user profile authentication.

additional data JSON

session_token

String

An authentication token for validating a user.

hold_fee_amount

Decimal

Yes

The holding fee amount that a customer is charged for an offline payment transaction in a country’s currency.

hold_fee_currency_code

Integer

The ID of a currency from which a customer creates a transaction. CPD provides this ID.
Note: The list of supported currency is based on the agreement between a merchant and CPD. This field is optional if holding fee currency is assumed as transaction currency.

hold_period

Integer

The number of hours for which the booking is reserved for offline payment transaction completion.
Note: The information is shown on HPP only.

stepper

Integer

The default value = 1 It depends on merchant specification related to breadcrumbs for HPP UI.
Note: Merchants can request for specific breadcrumbs shown to customers on the top of HPP payment page. Such as booking, add-ons, payment, and so on.

3.3 Response of HPP

HPP sends a response to merchants to accept or cancel URL. After your customers make a payment, they are redirected back to your website. They receive one of the following notifications about the payment processing:

Payment was successful
Payment was a failure
Customer cancelled the payment

After the completion of the payment, the control is passed back to the merchant URL. The customers are redirected to one of the following merchant URLs:

Merchant URL	Transaction status
Accept-URL	Payment is successful.
Cancel-URL	Payment fails or customers cancels a transaction.

Note: Velocity accepts the parameters if they are lowercase only.

When Velocity receives a payment request, it performs an extensive validation of the received data. The validation ensures that

The payment page is rendered correctly on a customer’s mobile device.
The transaction has the maximum chance of succeeding when sent to the PSP or Acquirer for clearance.

The callback request informs you about the payment status as an HTTP POST. Your technical team can customize the transaction details that you view. This is an asynchronous message in a separate HTTP transaction initiated from Velocity. The message is in addition to the original synchronous response to the payment request and the user redirect to confirmation page.

Note: Consider the following:

The callback response parameter is customizable.

Velocity sends parameters in lowercase. The request contains body with URL encoded format. Therefore, all the parameters may not be visible in the URL.

3.3.1 HPP Redirect Parameters

Following is a sample POST data to accept or cancel URL in HPP redirect callback for split payment. It is not visible in the URL.

[redirect] => {
  "order_status": {
    "code": "1/0"
  },
  "session_id": "21465",
  "session_type": "1",
  "sale_amount": {
    "value": "8716000",
    "currency_id": "170",
    "decimals": "2",
    "alpha3code": "COP"
  },
  "status": {
    "code": "4030",
    "message": "Session Complete"
  },
  "additional_data": {
    "params": [
      {
        "name": "platform",
        "text": "WEBB2C"
      },
      {
        "name": "hold_fee_currency_code",
        "text": "COP"
      }
    ]
  },
  "transactions": {
    "transaction": [
      {
        "id": "32629",
        "order_id": "3J6POZ",
        "hmac": "f7ef5a949c37068bad50e9e15d735eef827b108009825c0ee630db257ac58dacb91fe3cebdcec39d5549e0b1bcc39297f752d29a512e09815805e20219b4cfd1",
        "payment_method": "CASH",
        "payment_type": "8",
        "date_time": "2021-07-12T05:25:15+00:00",
        "issuing_bank": "Efecty",
        "installment": "2",
        "ip_address": "123.203.28.127",
        "service_type_id": "1",
        "amount": {
          "text": "8716000",
          "currency_id": "170",
          "decimals": "2",
          "alpha3code": "COP",
          "conversion_rate": "1"
        },
        "status": {
          "code": "2001",
          "message": "Payment captured by PSP"
        },
        "psp": {
          "id": "70",
          "name": "SafetyPay",
          "external_id": "469537"
        },
        "card": {
          "id": "7",
          "name": "VISA",
          "mask_card_number": "4444********1111",
          "expiry": "********"
        },
        "additional_data": {
          "params": [
            {
              "name": "platform",
              "text": "WEBB2C"
            },
            {
              "name": "_ga",
              "text": "2.164258751.1803897181.1625637105-1001259588.1622795959"
            },
            {
              "name": "office_id",
              "text": "BOGAV08AK"
            },
            {
              "name": "hold_fee_currency_code",
              "text": "COP"
            },
            {
              "name": "kpi_used",
              "text": "true"
            },
            {
              "name": "Response_Code",
              "text": "101"
            },
            {
              "name": "CUS",
              "text": "469537"
            },
            {
              "name": "NIT",
              "text": "9006166521"
            },
            {
              "name": "coupon_issue_timestamp",
              "text": "2021-07-12T05:27:14"
            },
            {
              "name": "coupon_expiry",
              "text": "2021-07-13T03:01:10"
            },
            {
              "name": "coupon_id",
              "text": "110924"
            },
            {
              "name": "receipt_filename",
              "text": "prdcpr_8f64d5c3-8575-460a-994b-52eeddd01702.pdf"
            }
          ]
        },
        "billing_address": {
          "first_name": "********",
          "last_name": "********",
          "street": "********",
          "city": "********",
          "state": "********",
          "country": "********",
          "postal_code": "********"
        },
        "fraud": {
          "status_code": "Post Auth Success",
          "status_desc": "Post Auth Success",
          "post_auth_ext_id": "6255590973676885104011",
          "post_auth_ext_status_code": "ACCEPT"
        }
      }
    ]
  }
}

The following is a description of the parameters.

Parameter

Child Parameter

Description

order_status

code

An integer code indicating the status of the transaction, where 1 = Success,  0 = Failed.

session_id

The Velocity session ID for the payment transaction.

session_type

An integer that defines payment type.

If the user has opted to pay with the split payment option, then session_type = 2 will be returned in the redirect response.
If the user has not opted to pay with the split payment option, then session_type = 1 will be returned in the redirect response.

sale_amount

text

The total amount that the customer was charged for the payment transaction in a country’s currency.

currency_id

The currency ID , which the customer was charged for the payment.

alpha3code

The three-letter country codes.

decimals

The currency precision. For example, 2 for the USD currency parameter.

status

Code

An integer code indicating the status of the session.

message

The status message of the session.

additional_data

session_token

The merchant's unique token.

hold_fee_amount

The holding fee amount.

hold_fee_currency_code

The holding fee currency.

hold_period

The hold period.

transactions

Velocity’s unique ID for the payment transaction.

order_id

The order ID the merchant provides when a transaction is initiated. In case of airlines, this will be the passenger name record (PNR).

Hmac

The Message Authentication Code. It is calculated by creating a SHA512 hash comprising the following input fields in the listed order:

Parameter	Required
clientid	Yes
orderid	Yes
amount	Yes
country	Yes
mobile	No
mobile-country	No
email	No
deviceid	No
salt	Yes

payment_method

The type of methods used for payment. The values are

Direct Debit (Online payment) - DD.
Credit/Debit Card (Card payment) - CD.
Wallet - eWallet.
Other payment methods – CASH.

payment_type

The type of payments

Card
Voucher
Wallet
APM
Card Token
Virtual
Online Banking
Offline Payment

ip_address

The IP address of the transaction initiation.

date_time

The date and time when the transaction was initiated in UTC.

installment

The payment is done through instalments.

issuing_bank

The bank name for PSE or the Onsite Center name for Onsite Payment. This parameter is sent for Safety Pay transactions only.

Note: For Card transactions, this parameter is not sent in the redirect callback.

approval_code

The issuer approval code provided by the PSP for a transaction. Available for card payments only.

fraud

status_code

The final fraud status code. For example, 3011/3111. Refer to Fraud Status Codes for the complete set of error codes.

Note: If Fraud is not enabled , then this parameter is not sent in the redirect callback.

status_desc

The final fraud status description. For example, Accepted / Review.

Note: If Fraud is not enabled , then this parameter is not sent in the redirect callback.

pre_auth_ext_status_code

The pre-auth fraud check system response code, if available.

pre_auth_ext_id

The pre-auth fraud check system transaction ID, if available.

pre_auth_ext_id

The post-auth fraud check system transaction ID, if available.

post_auth_ext_status_code

The post-auth fraud check system response code, if available.

service_type_id

The type of exchange services that can be applied to a transaction. The FX Services (DCC, MCP, and PCC) is applied in a manner whether it is opted or not.

X - Represents which exchange service is applicable for a transaction.
Y - Represents the exchange is used or not (opt or not opt).

For example, The ID will be 11 for DCC opt in and 12 for DDC Not opt.

ID (XY)	Service (X)	Opted
11	DCC	Opted
12	DCC	Not opted
21	MCP	Opted
22	MCP	Not opted
31	External MCP	Opted
32	External MCP	Not opted
41	PCC	Opted
42	PCC	Not opted

billing_address

first_name

The billing address first name, if available.

last_name

The billing address last name, if available.

street

The billing address street address, if available.

city

The billing address city name, if available.

country

The billing address country name, if available.

state

The billing address state or region value, if available.

postal_code

The billing address zip code, if available.

amount

text

The total amount that the customer was charged for the payment transaction in a country’s currency.

currency_id

The currency ID , which the customer was charged for the payment.

decimals

The currency precision. For example, 2 for USD for the currency parameter.

alpha3code

The three-letter country codes.

conversion_rate

Default value = 1.
This field contains the conversion rate given by the FX Service in decimals. If the FX Service is not used/opted, then the value of this field is 1.

status

code

The status code of the transaction. Refer to Transaction Status Codes for the complete set of status codes.
For the payment status timeout scenario, state_id = 0 is sent in the response.

message

The status message of the transaction.

psp

Velocity’s unique ID for the PSP.

name

The name of the PSP or ACQ used for completing the transaction. This is present in the callback if it is configured during onboarding.
For example, 2C2P, 2C2P-ALC, GlobalPayment, Worldpay, and ChasePayment.
The list of psp-name is provided at the time of implementation.

reference_id

The transaction ID received from the PSP or ACQ. This is present in the redirect if it is configured during onboarding.

card

The Velocity Card ID to identify the card scheme. For example, Mastercard or Visa. If the transaction is abandoned then this attribute is not present.
The list of card IDs is provided at the time of implementation.

mask_card_number

The masked card of the transaction. For example, 4444XXXXXXX1111.

Note: For APM, PSE, and Onsite transactions, this parameter is not sent in the redirect callback.

expiry

The card expiration date of the transaction For example, 01/21.

Note: For APM, PSE, and Onsite transactions, this parameter is not sent in the redirect callback.

name

The card scheme or network of the transaction. For example, Visa or Mastercard.

Note: For APM, PSE, and Onsite transactions, this parameter is not sent in the redirect callback.

additional_data

NIT

The Merchants Code at PSE. This parameter is sent for PSE transactions only.

coupon_issue_timestamp

The Date Time of coupon issue by Safety Pay. This parameter is sent for Safety Pay onsite payment transactions only.

coupon_expiry

The Date Time of coupon expiry by Safety Pay. This parameter is sent for Safety Pay onsite payment transactions only.

coupon_id

The AgreementCode by SafetyPay. This parameter is sent for Safety Pay onsite payment transactions only.

receipt_filename

The filename of the coupon generated.