Hosted Payment Page Integration Guide

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.

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.

<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">

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

Client idIntegerYesA merchant’s unique ID for Velocity, which CPD creates.
AccountIntegerYesThe 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 idStringYesA unique identification string; it is a passenger name record (PNR) for airlines.
OperatorIntegerNoThe 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)
CountryIntegerNoThe 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-codeIntegerNoThe 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.
MobileIntegerNoThe MSISDN of a customer without the International Dialling Code.
EmailStringNoThe email address of a customer.
Customer-refStringNoA 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.
AmountDecimalYesThe total amount that a customer is charged for a payment transaction in a country’s currency.
LanguageStringNoThe default language that Velocity uses when translating the payment pages. Velocity language codes are based on the ISO-639-1 standard.
Refer to for details.
Accept-urlStringNoThe 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-urlStringNoThe 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 NoThe 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 NoThe 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.
HmacStringYesThe Message Authentication Code. It is calculated by creating a SHA512 hash comprising the following input fields in the listed order:


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-dataJSON stringNoIt is a payload for Google Analytics, the details of which are given in another document. It can be made available on request.
Response-content-typeIntegerNoThe format in which merchant gets the redirect response:
Array content type = 1 (default value)
JSON content type = 2
TxntypeIntegerNoA 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 dataJSON stringNoThe additional data sent from a merchant.
NonceStringYesTimestamp / random string.
Init-tokenStringYesThis is a combination of SHA512 (clientid+username+password+nonce+accepturl) encryption.
  • clientid=10007
  • username = CPM
  • password = TEST
  • nonce = 123435
The above combination generates the following token:
Profile-idStringNoThe 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_tokenStringNoAn authentication token for validating a user.
hold_fee_amountDecimalYesThe holding fee amount that a customer is charged for an offline payment transaction in a country’s currency.
hold_fee_currency_codeIntegerNoThe 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_periodIntegerNoThe number of hours for which the booking is reserved for offline payment transaction completion.
Note: The information is shown on HPP only.
stepperIntegerNoThe 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 URLTransaction status
Accept-URLPayment is successful.
Cancel-URLPayment 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": "",
        "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.

3010Pre-Fraud Check InitiatedPre-Fraud Check Initiated.
3011Pre-screening result
- Accepted
The pre-auth fraud check was “accepted” and no further fraud screening will be done.
3012Pre-screening fraud service unavailableSystem error from fraud check service.
3013Pre-screening result
- Unknown
An unknown error.
3014Pre-Screening fraud Result
- Review
The fraud check was REVIEW.
3015Pre-screening result
- Rejected
The pre-auth fraud check service was in REJECTED and no further payment processing will be done.
3016Pre-screening Connection Failed - RejectedPre-screening connection failed – rejected.
3100Post Fraud Check requiredPost fraud check required.
3111Post-screening Result

- Accepted
The post-auth fraud check was ACCEPTED.
3112Post-Screening Result

- Unknown
System error from fraud check service and therefore, manual review will be required.
The payment will not be refunded or cancelled.
3113Post-screening Fraud Result - ReviewThis state indicates an unknown error.
3114Post-screening Result

- Rejected
The fraud check was REVIEW and hence manual Review will be required.
The payment will not be refunded or cancelled.
3115Post-screening Result

- Rejected
The fraud check was REJECTED. The payment will be refunded or cancelled.
3116Post-screening Connection FailedVelocity 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.

1041Payment PendingWhen 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.
2000AuthorizedThe payment has been successfully authorized by the PSP.
2001CapturedThe payment has been successfully captured by the PSP.
The payment was rejected by the PSP or Acquirer.
2011DeclinedThe payment was declined by PSP / Acquirer while performing capture.
2000CancelThe payment was cancelled.
5000ValidationThe validation failed.
20163D verification failed3D verification with MPI failed.
2017Authorization not attempted due to rule matchedAuthorization 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.

409SESSION_TIMEOUTHPP session timeout
410CANCELUser cancels without attempting a payment. Cancellation by customer is implemented via (via Button ‘Back' or 'Cancel’) and confirmation popup.
411PAYMENT_INCOMPLETE_CANCELUser 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