1. Introduction

CellPoint Digital’s (CPD) Velocity Hosted Payment Page (HPP) provides a seamless and secure payment processing channel and offers payment processing for websites. You can easily integrate it with your website and control, optimize, and harmonize payment transactions across channels.

During the project, CPD’s Merchant Implementation Manager provides you with the Implementation Guide and the Data Collector. Both documents need be read alongside this integration guide which explains how payment control is passed between CPD’s HPP and your website.

A summary of the next chapter’s detailed specification is listed in the table below.

Page	Feature
Order summary page	Shopping cart summary. Customers can checkout using the payment button.
Hosted Payment page (HPP)	Hosted by CPD. Facilitates payment processing based on your account ID. Provides payment information about the success or failure of payment. Redirects customers back to your page.
Payment Confirmation Page	Provides information if a transaction was successful or failure. Provides confirmation about the purchase..

2. Integration Requirement

To ensure the seamless integration of your system with HPP, CPD requires the following from merchants:

Organization logo, website payment template, and website colour scheme
Accept URL: customers are redirected on this URL if their transaction is successful.
Cancel URL: customers are redirected on this URL if their transaction is cancelled.
Callback URL: a URL where CPD presents the asynchronous status of a transaction.
PSP or acquirer details.
Preferred payment methods, countries, and languages and currencies supported.
Whitelist server IPs of CPD.
Payment options that need to be mapped with specific regions or countries.

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.

4. Error Codes

4.1 Fraud Status Codes

The following table lists status codes that can be returned in the redirect from HPP against fraud_status_code.

Code	Type	Description
3010	Pre-Fraud Check Initiated	Pre-Fraud Check Initiated.
3011	Pre-screening result - Accepted	The pre-auth fraud check was “accepted” and no further fraud screening will be done.
3012	Pre-screening fraud service unavailable	System error from fraud check service.
3013	Pre-screening result - Unknown	An unknown error.
3014	Pre-Screening fraud Result - Review	The fraud check was REVIEW.
3015	Pre-screening result - Rejected	The pre-auth fraud check service was in REJECTED and no further payment processing will be done.
3016	Pre-screening Connection Failed - Rejected	Pre-screening connection failed – rejected.
3100	Post Fraud Check required	Post fraud check required.
3111	Post-screening Result - Accepted	The post-auth fraud check was ACCEPTED.
3112	Post-Screening Result - Unknown	System error from fraud check service and therefore, manual review will be required. The payment will not be refunded or cancelled.
3113	Post-screening Fraud Result - Review	This state indicates an unknown error.
3114	Post-screening Result - Rejected	The fraud check was REVIEW and hence manual Review will be required. The payment will not be refunded or cancelled.
3115	Post-screening Result - Rejected	The fraud check was REJECTED. The payment will be refunded or cancelled.
3116	Post-screening Connection Failed	Velocity could not connect to fraud check service and therefore, manual review will be required. The payment will not be refunded or cancelled.

4.2 Transaction Status Codes

The following table lists possible status codes that can be returned in the redirect from HPP against state_id.

Code	Type	Description
1041	Payment Pending	When Velocity starts a payment with a provider and waits for the confirmation about payment, mPoint logs this state. This state is useful for offline payment methods, where the payment is processed on Velocity and waiting for the offline provider.
2000	Authorized	The payment has been successfully authorized by the PSP.
2001	Captured	The payment has been successfully captured by the PSP.
2010	Captured Rejected	The payment was rejected by the PSP or Acquirer.
2011	Declined	The payment was declined by PSP / Acquirer while performing capture.
2000	Cancel	The payment was cancelled.
5000	Validation	The validation failed.
2016	3D verification failed	3D verification with MPI failed.
2017	Authorization not attempted due to rule matched	Authorization not attempted after successful 3D verification due to rule matched.

4.3 Cancellation/Timeout Status Codes

The following table lists possible status codes that can be returned in the redirect from HPP in specific cancellation/time out scenarios.

Code	Type	Description
409	SESSION_TIMEOUT	HPP session timeout
410	CANCEL	User cancels without attempting a payment. Cancellation by customer is implemented via (via Button ‘Back' or 'Cancel’) and confirmation popup.
411	PAYMENT_INCOMPLETE_CANCEL	User cancels after back-end interaction (after an error is thrown on the HPP).

5. Frequently Asked Questions

Q: Where can I view the payment transaction?

A: After you complete the onboarding, the support team provides you login credentials and a link to the Vision console. You can use one of the modules to view all of the transaction details. You can also use Vision to cancel or refund the transactions.

Q: After the completion of a transaction, does a merchant’s backend server receive information about the success or failure of transaction?

A: After customers receive a confirmation of the success or failure of transaction, an asynchronous call back request is sent to your server about the success or failure of the translation. This includes information such as TXNid, status, authcode, and amount information.

Q: The details of a transaction are not present in the API body. Where can I view them?

A: The entire data is present in the body and the URL is encoded. For example, transaction ID, transaction status, authorization code, and currency code.

Q: How do I check transaction data on front end and back end?

Front end:

When HPP sends data on accept URL, it sends following transaction details in the body of the URL on the front end (accept URL) and client server (call back URL):

Back end:

When transaction is successful, Velocity sends back end data of above transaction details on that URL for both successful or failed transaction.

Note: If the transaction fails, Velocity sends information on cancel URL