Velocity - API Integration Guide V3.14

Suggest Edits

1. Document Details

1.1 Scope of the Document

This document aims to help you integrate the Velocity Payment Orchestration Platform (POP) with your application using application programming interfaces (APIs).

Note: Sample codes are provided to facilitate the integration process. However, the live request and response values may vary depending on the configuration.

1.2 Version History

Document Version Additional Features
2.01
  • Introduced:
    • Split payment method
    • PayPal workflow
  • Updated:
    • AID data fields
    • Granular error codes
2.02
  • Introduced exchange services to identify the type of foreign exchange service used for a transaction.

  • Updated split payment method
2.03
  • Ticket level API changes

  • Added instalments
3.00Updated the document template.
3.01Updated Section 7.2 parameters; editing and formatting.
3.02Added Appendix with tables.
3.03Added and updated Initialize, Authorize, Capture, and Refund Status Codes in Section 18.
3.04Added table for update-order-data field description.
3.05Added section 9.1.5 for 3D secure authenticated card with field descriptions.
3.06Added 3DS example and field description for Authorize-payment (Section 9).
3.07Updated document template.
3.08Updated HMAC parameter description in sections 7.2 and 15.
3.09Updated sections 7.1, 7.2, and 14.1.
3.10Updated section 18 for the missing status codes.
3.11Updated Section 8.1.1 Pay Request for Payu and Safetypay. Added a table to Section 8.1. Added tables to Section 19 for tax_id_type.
3.12Replaced generic card numbers with “card_number” in XML files.
3.13Updated the sample code in section 13.2.1 Card Payment Transaction Status.
3.14Updated Section 5 Velocity POP Payment Workflow.
3.15Amended tables in Section 19 for tax_id_type.

2. Introduction

A single integration with the Velocity POP API provides a variety of payment options for merchant websites and mobile applications. The API integration is an easy process and the CPD team provides support for the integration process. API integration is suitable for mobile applications or websites that have Payment Card Industry Data Security Standard (PCI DSS) requirements.

3. Glossary of Terms

The terms used in this document are listed and defined in the table below.

TermsDescription
MerchantAny business who sells goods or services and accepts payments from customers.
CustomersThose who want to buy goods and services from merchants
HPPHosted Payment Pages
PSPPayment Service Provider
ACQAcquirer
APMAlternate Payment Method
CPDCellPoint Digital
FXForeign Exchange Service
MSISDNMobile Station International Subscriber Directory Number
MACMessage Authentication Code
POPPayment Orchestration Platform
CRMClient Relationship Management
MinMinimum
MaxMaximum
DCCDynamic Currency Conversion
MCPMultiple Currency Conversion
PCCPresentment Currency Conversion
txnTransaction
CRMCustomer Relationship Management

4. Integration Requirements for Merchants

To integrate the Velocity API, you require the following:

  • A PCI DSS certified website or platform
  • Velocity URL
  • Client ID
  • Merchant account ID
  • Velocity username and password
  • Country and currency
  • Country codes and operator ID
  • Salt string

5. Velocity POP Payment Workflow

The following sequence diagram provides the POP payment options, which includes the following:

  • The Common Payment Initiation Flow
  • The Fetch Exchange Rates Flow for New Cards
  • The New Card Authorization Flow
  • The New Card Authorization Flow with Agreement to Store Card
  • The Fetch Exchange Rates Flow for Stored Card
  • The Authorization Flow for Using Stored Card
  • The Authorization Flow for Card Stored in Third-party Wallet
  • The Settlement with Acquirer Flow
  • The 3DS Authorization Flow
  • The Payment Flow with APM

The payment processing workflow of the Velocity POP is as follows:

  1. The merchant application authorizes a payment using the APIs.
  2. The backend of the Velocity POP completes the payment authorization and returns the status.
  3. The APIs provide the status to the frontend of the merchant application, which processes the payment through PSS, based on the payment status.

6. API Specifications: Payments Payments Authentication and Security Management

Authentication and Security Management

All API requests must be made through HTTPS. The Velocity API header value format is as follows:

  • Use HTTP basic authentication to authenticate the request. See Basic Authentication Method for details.
  • Specify the auth-parameter, where the overall parameter value is provided in the form is x-cpm-sec-token.
  • x-cpm-sec-token is a unique value that you generate for a unique request. Velocity uses this value to verify if a request is submitted multiple times.

To generate the x-cpm-sec-token, complete the following steps:

  1. Extract the request/response body string.
  2. Remove all space characters from the string including space, tabs, newline, and carriage return.
  3. Append the salt to the body string.
    To append the salt, complete the following steps, as applicable to the authentication type:
    a. For basic authentication, make the salt as base64 (API username + API password).
    b. For bearer authentication, CPD provides the bearer token to be used as salt.
  4. Calculate sha-256 (body + salt) of the string.
  5. Set this hash string as the x-cpm-sec-token header in the request/response.

Note: Consider the following items:

  • To generate the hash string, you can follow the same process at the receiver end.
  • To validate the salt, compare the hash string with the x-cpm-sec-token from the header.

The following is an example of the parameters in the header section.

AuthenticationBasic
x-cpm-sec-token6lutO0jd0h1YjlHqjAn6cjKYF5n2ZJjp%2fDNk08IGKS0%3d

7. Initialize Payment

You can invoke the initialize-payment API to initiate a new payment transaction using the Velocity POP. The API returns the required transaction information and merchant configuration for the payment to be successfully processed.

You can access the API from the path listed in the table below.

Path NamePath Details
End Point[VELOCITY URL]/mpoint/initialize-payment
Format/Content Typetext/xml
AuthenticationHTTP basic access authentication

7.1 Request

The following is an example of an initialize payment request.

<root>
    <initialize-payment account="[integer]" client-id="[integer]">
        <transaction order-no="testOrderId1" type-id="[integer]" session-id="[integer]" product-type="[integer]" booking-ref="[PNR]">
            <amount country-id="[integer]" currency-id="[integer]">100</amount>
            <callback-url> [merchant callback url] </callback-url>
            <accept-url>[merchant accept url</accept-url>
            <hmac>76f8682b42d0de9ad6948d1a8aef1744b939cd0570cd2c9749173b</hmac>
            <additional-data>
                <param name="merchant_payment_ref">12091201291</param>
            </additional-data>
        </transaction>
        <auth-token>profilesuccessvalidation</auth-token>
        <client-info language="en" sdk-version="2.1.0" version="2.1.0" platform="[platform type]" profileid="[integer]">
            <mobile operator-id="[integer]" country-id="[integer]"> [mobile number] </mobile>
            <email> [email id] </email>
            <device-id>ABCdefr6732</device-id>
        </client-info>
    </initialize-payment>
</root>

Note: For split abandoned payments, the session-id is sent back in the initialize request with the full amount. A split abandoned happens when a customer starts a fresh transaction and leaves a current split payment.

Note: Merchants from specific domains, such as airlines or rail, want to display booking information to customers after they make payment. For example, ticket details along with the address of a customer.

7.2 Request with AID Data

The following is an example of airline data.

<?xml version="[integer]" encoding="UTF-8"?>
<root>
    <initialize-payment account="[integer]" client-id="[integer]">
        <transaction order-no="[string]" type-id="[integer]">
            <amount currency-id="[integer]" country-id="[integer]">40180</amount>
            <orders>
                <shipping-address>
                    <name>name</name>
                    <street>street</street>
                    <street2>another street</street2>
                    <city>city</city>
                    <state>NY</state>
                    <zip>411028</zip>
                    <country>India</country>
                </shipping-address>
                <line-item>
                    <product sku="PR-SAEF-11">
                        <name>single journey</name>
                        <description>single journey</description><image-url>[image URL]>
                        <airline-data order-type="TICKET" order-no="[string]">
                            <amount decimals="[integer]" currency-id="[integer]" currency="PHP" symbol="" format="" country-id="640">638500</amount>
                            <fees>
                                <fee format="" symbol="" currency="PHP" country-id="640" type-id="2">112300</fee>
                            </fees>
                            <trips>
                                <trip seq="1" tag="1">
                                    <service-level>Economy</service-level>
                                    <origin time-zone="+08:00" country-id="640" external-id="MNL" type-id="8">Manila</origin>
                                    <destination time-zone="+08:00" country-id="640" external-id="BCD" type-id="8">Bacolod</destination>
                                    <departure-time>2020-02-21 08:15:00</departure-time>
                                    <arrival-time>2020-02-21 09:35:00</arrival-time>
                                    <booking-class>H</booking-class>
                                    <transportation code="">
                                        <vehicle type="[integer]" id="[integer]">321</vehicle>
                                        <carriers>
                                            <carrier type-id="1" code="PR">
                                                <number>2131</number>
                                            </carrier>
                                            <carrier type-id="[integer]" code="PR">
                                                <number>2131</number>
                                            </carrier>
                                        </carriers>
                                    </transportation>
                                </trip>
                            </trips>
                            <profiles>
                                <profile id="[integer]">
                                    <title>MR</title>
                                    <first-name>test</first-name>
                                    <last-name>one</last-name>
                                    <type>ADULT</type>
                                    <amount decimals="2" currency-id="608" currency="[string]" symbol="" format="" country-id="640">638500</amount>
                                    <contact-info>
                                        <email>[email id]</email>
                                        <mobile country-id="[integer]">[phone number]</mobile>
                                    </contact-info>
                                </profile>
                            </profiles>
                            <billing-summary>
                                <fare-detail>
                                    <fare>
                                        <profile-seq>1</profile-seq>
                                        <description>adult</description>
                                        <currency>PHP</currency>
                                        <amount>60</amount>
                                        <product-code>ABF</product-code>
                                        <product-category>FARE</product-category>
                                        <product-item>Base fare for adult</product-item>
                                    </fare>
                                </fare-detail>
                                <add-ons>
                                    <add-on>
                                        <profile-seq>1</profile-seq>
                                        <trip-tag>2</trip-tag>
                                        <trip-seq>2</trip-seq>
                                        <description>adult</description>
                                        <currency>PHP</currency>
                                        <amount>60</amount>
                                        <product-code>ABF</product-code>
                                        <product-category>FARE</product-category>
                                        <product-item>Base fare for adult</product-item>
                                    </add-on>
                                </add-ons>
                            </billing-summary>
                        </airline-data>
                    </product>
                    <amount>638500</amount>
                    <points>200</points>
                    <reward>1</reward>
                    <quantity>1</quantity>
                    <additional-data>
                        <param name="deviceFingerPrint">12091201291</param>
                    </additional-data>
                </line-item>
            </orders>
            <hmac>76f8682b42d0de9ad6948d1a8aef1744b939cd0570cd2c9749173b</hmac>
            <additional-data>
                <param name="merchant_payment_ref">12091201291</param>
            </additional-data>
        </transaction>
        <client-info language="en" platform="Android/9(28)" version="2.00" app-id="2">
            <mobile country-id="[integer]">99065528</mobile>
            <email>[email id]</email>
            <device-id>c2f-60-45e-8f7-83a4</device-id>
        </client-info>
    </initialize-payment>

The parameters are listed and defined in the table below.

Parameter Type Required Description
Initializing Payments Parameters
account Integer No The unique ID associated with a payment transaction. It is optional. If you omit this parameter, the payment transaction is associated with the default sub-account.
client-id Integer Yes The unique ID configured for a merchant on the Velocity POP.
Transaction Parameters
order-no String Yes The order ID that a merchant generates. It is an alphanumeric string.
Note: Some Payment Providers have strict guidelines for the order-no. The recommended pattern is "[a-zA-Z0-9._-].
currency-id Integer No The currency of the transaction amount. This should be the ISO 4217 numeric code.
type-id Integer No The type of transaction used for making payment. Velocity supports the following transaction types:
Value Transaction types Examples
1 Online shopping S&B Purchase
2 Offline shopping S&B Purchase
3 Self Service Online MYB Ancillary Purchase, MYB Change Itinerary Payment, OLCI Ancillary Purchase
4 Self Service Offline MYB Pay Later
5 Self Service Online MYB/Self Service Online with additional rules on FOP-- Managed Booking txn where additional rules on FOP can be configured
6 Self Service Online CPL - Payment Link Transaction. Transaction originated from payment link
session-id Integer No The ID of a session used for multiple payment transactions during one payment flow. For example, split payment or retry of a failed payment transaction.
amount Integer Yes The total amount that a customer is charged for a payment transaction in a country’s smallest currency. For example, the smallest currency of USD is penny. If the transaction amount is $120.30, then the amount field contains value 12030.
Note: The amount is always a non-decimal value in the request. The object amount contains the country-id and currency-id parameters.
fees/fee Integer No This the addition fees if applicable for the transaction like for specific scenarios like administrative fee for offline payment or pay later. For example, the smallest currency of USD is penny. If the transaction amount is $120.30, then the amount field contains value 12030.
Note: The fee is always a non-decimal value in the request. The object amount contains the country-id and currency-id parameters.
country-id Integer Yes The CPD-specific country code, which is available in appendix.
callback-url String No The absolute URL to the back office of a merchant where Velocity POP sends the payment status.
Note: If you do not provide this parameter, Velocity uses the default URL.
accept-url String No The URL where Velocity directs a customer after successfully completing a payment transaction.
Note: If you do not provide this parameter, Velocity uses the default URL. The URL is used for redirecting to either the HPP or merchant’s page after a payment completion.
cancel-url String No The absolute URL where Velocity directs customers if they cancel a payment transaction midway.
Note: If you do not provide this parameter, Velocity uses the default URL. The URL is used for redirecting to either the HPP or merchant’s page after a payment cancellation.
decline-url String No The absolute URL where Velocity directs customers if the payment transaction fails. The URL is used for redirecting to either the HPP or merchant’s page after a payment failure.
auth-url String No The URL which used for single sign-on authentication if provided by an external system.
service-type-id Integer No A value to indicate the type of exchange services used for a transaction. The ID indicates if the FX services such as DCC, MCP, and PCC are opted. The ID is a two-digit number XY in which:
  • X - Represents the type of FX used in a transaction.
  • Y - Represents the service usedꟷ it can be:
  • Opt-in, which has value as “1”
  • Opt-out, which has value as “2”
The following table shows the possible values of exchange service ID:
ID (XY) Service (X) Opted (Y)
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
auth-token String No A unique token sent to the specified auth-url to authenticate customers when they pay with a stored card and use single sign-on.
hmac String Yes The Message Authentication Code. It is calculated by creating a sha-512 hash comprising the following input fields in the listed order:

ParameterRequired
clientidYes
orderidYes
amountYes
countryYes
mobileConditional
mobile-countryConditional
emailConditional
deviceidConditional
saltYes

Note: CPD provides the salt value to merchants.
MAC calculation secures the information sent by the merchant to Velocity by applying the SHA-512 encryption algorithm on key parts of the information sent to protect against tampering. The “salt” is the merchant's shared secret string used to ensure that MAC is unique.
orders Object No The order details with following details: event, location, date or time, ticket type, cost, booking fee, quantity, and total price.

Note: This parameter is used for airline data only, defined in separate guide for Airline Data.
additional-data Node No An optional node that contains additional information about the transaction. It includes a list of parameters with values. Recommended length for parameter value is 20 characters.
additional-data (merchant payment reference) Node No An optional node to pass the merchant's payment reference, the merchant needs to pass this value as additional data in the alphanumeric format maximum 20 characters.

Merchant information parameters
client-info Object Yes An object of client-info, which contains the following merchant details: language, version, platform, and profile ID.
platform String yes The platform from which the request is sent. For example, web, iOS, Android, B2B, and B2C.
sdk-version Integer yes The version of SDK used to send the request.
Note: Use 2.1.0 SDK version in the request.
version String yes The version of the API or application that send the request.
language String yes The language that Velocity uses as default when translating the payment pages. Velocity uses a default language set by a merchant if this parameter is omitted.
Note: Velocity language codes are based upon the ISO- 639-1 standard.
Refer http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for details.
mobile Integer No The MSISDN of a customer without International Dialling Code.
Note: A mobile number can be mandatory or optional, based on the requirement of a merchant or a PSP.
country-id Integer No The CPD-specific country code, which is provided on request.
Note: Mandatory only if mobile number is provided.
email String No The email address of a customer. If your customer provides this parameter, the Email input field on the Send E-Mail Receipt page is automatically populated with this value.
Note: Email can be mandatory or optional, based on the requirement of a merchant or a PSP.
device-id String No The device ID of a customer’s device.
Note: device ID is optional for a web channel.

Note: For AID parameters description, refer to the CPD Velocity AID Data Integration for HPP V1.02 guide.

7.3 Response

The response from the Velocity server has information about the transaction such as transaction ID and amount, along with the configured payment methods or card types. The merchants must call this API when a customer makes a purchase.

The initialize payment response can be divided into the following parts

  • Merchant configuration
  • Transaction information
  • Card information

7.3.1 Card Payment

The following is an example of the response that the Velocity server sends to a merchant’s customer.

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <client-config account="[integer]" auto-capture="false" id="[integer]" mode="[integer]" store-card="[integer]">
    <name>Test</name>
    <callback-url>[callback url]</callback-url>
    <accept-url />
  </client-config>
  <transaction auto-capture="true" eua-id="[integer]" id="[integer]" language="en" mode="1" order-no="" type-id="[integer]">
    <amount country-id="[integer]" currency="DKK" format="{PRICE} {CURRENCY}" symbol="">10025</amount>
    <mobile country-id="[integer]" operator-id="[integer]">30206172</mobile>
    <callback-url>[CALLBACK URL]</callback-url>
    <accept-url />
  </transaction>
  <cards>
  .....
    <card cvc-length=“3” cvcmandatory=“false” dcc=“false” enabled=“true” id=“8” instalment=“0" max-length=“19” min-length=“13" payment-type=“1” preferred=“false” processor-type=“1” psp-id=“21" state-id=“1” type-id=“8">
    <name>Visa</name>
    <prefixes>
                <prefix>
                    <min>4000</min>
                    <max>4999</max>
                </prefix>
                <prefix>
                    <min>413222</min>
                    <max>413222</max>
                </prefix>
    </prefixes>Visa
    </card> 
  </cards>
  <stored-cards>
    <card id="[integer]" preferred="true" psp-id="2" type-id="2" dcc="true”>
      <name>myVisa</name>
      <card-number-mask>4711 10** **** 0000</card-number-mask>
      <expiry>06/24</expiry>
    </card>
  </stored-cards>
</root>

7.3.2 Wallet

The following is an example of the response to a payment using a wallet.

<wallets>
        <card cvc-length="-1" enabled="true" id="15" max-length="-1" min-length="-1" payment-type="3" preferred="false" processor-type="3" psp-id="18" state-id="1" type-id="[integer]">
            <name>[wallet name]</name>
            <prefixes>
                <prefix>
                    <min>0</min>
                    <max>0</max>
                </prefix>
            </prefixes>
            <url method="overlay" />
            <head><script type='text/javascript'> var debug = false; var countryCode = "US"; var currencyCode = "USD"; var merchantIdentifier = 'merchant.com.cellpointmobile.(wallet name)'; var displayName ="UATP"; var totalAmount = "1"; var supportedNetword = ['AMEX','MASTERCARD','VISA']; </script> <script type="text/javascript" src="https://s3.ap-qwert-1.amazonaws.com/cpmassets/psp/(wallet name).js"></script> <style> #(wallet name){width:150px;height:50px;display:none;border-radius:5px;background-image:-webkit-named-image(apple-pay-logo-white);background-position:50% 50%;background-color:#000;background-size:60%;background-repeat:no-repeat} </style></head>
            <body><button type="button" id="(wallet name)"></button></body>
        </card>
</wallets>

The following is an example of the response to a payment using Apple Pay.

?xml version="1.0" encoding="UTF-8"?>
<root>
    <url method="overlay" />
    <head>&lt;script type='text/javascript'&gt; var debug = false; var countryCode = "US"; var currencyCode = "USD"; var merchantIdentifier = 'merchant.com.CPD.iphone.qa'; var displayName ="UATP"; var totalAmount = "1"; var supportedNetword = ['AMEX','MASTERCARD','VISA']; &lt;/script&gt; &lt;script type="text/javascript" src="https://s3.ap-qwert-1.amazonaws.com/cpmassets/psp/(wallet name).js"&gt;&lt;/script&gt; &lt;style&gt; #(wallet name){width:150px;height:50px;display:none;border-radius:5px;background-image:-webkit-named-image(apple-pay-logo-white);background-position:50% 50%;background-color:#000;background-size:60%;background-repeat:no-repeat} &lt;/style&gt;</head>
    <body>&lt;button type="button" id="(wallet name)"&gt;&lt;/button&gt;</body>
</root>

7.3.3 Offline

<offline>
        <card cvc-length="0" cvcmandatory="false" dcc="false" enabled="true" id="96" installment="0" max-length="0" min-length="0" payment-type="8" preferred="false" presentment-currency="false" processor-type="8" psp-id="-1" state-id="1" type-id="96">
         <name>Payment Center Offline</name>
         <prefixes />Payment Center Offline
        </card>
</offline>

7.3.4 Aggregator

<aggregators>
        <card cvc-length="0" cvcmandatory="false" dcc="false" enabled="true" id="97" installment="0" max-length="0" min-length="0" payment-type="7" preferred="false" presentment-currency="false" processor-type="7" psp-id="-1" state-id="1" type-id="97">
            <name>PSE</name>
            <prefixes />
            <active-payment-menthods>
                <payment-method>
                    <logoName>8f56c0c2-c2ac-4b25-9d64-849101aa512b</logoName>
                    <logoURL>0</logoURL>
                    <displayName>A continuación seleccione su banco</displayName>
                    <issuingBank>0</issuingBank>
                    <displayOrder>1</displayOrder>
                </payment-method>
                <payment-method>
                    <logoName>2c9c848b-a02b-4aa5-bc49-6695e28f7517</logoName>
                    <logoURL>1552</logoURL>
                    <displayName>BAN.CO</displayName>
                    <issuingBank>1552</issuingBank>
                    <displayOrder>2</displayOrder>
                </payment-method>
            </active-payment-menthods>PSE
        </card>
</aggregators>

7.3.5 APM

<apms>
        <card id="95" type-id="95" psp-id="-1" min-length="-1" max-length="-1" cvc-length="-1" state-id="1" payment-type="4" preferred="false" enabled="true" processor-type="4" installment="0" cvcmandatory="false" dcc="false" presentment-currency="false">
            <name>PayMaya</name>
            <prefixes>
                <prefix id="271">
                    <min>-1</min>
                    <max>-1</max>
                </prefix>
            </prefixes>PayMaya
        </card>
    </apms>

7.3.6 Vouchers

<vouchers>
        <card id="26" type-id="26" psp-id="-1" min-length="-1" max-length="-1" cvc-length="-1" state-id="1" payment-type="2" preferred="false" enabled="true" processor-type="2" installment="0" cvcmandatory="false" dcc="false" presentment-currency="false">
            <name>TravelFund</name>
            <prefixes>
                <prefix id="273">
                    <min>-1</min>
                    <max>-1</max>
                </prefix>
            </prefixes>TravelFund
        </card>
        <card id="24" type-id="24" psp-id="-1" min-length="-1" max-length="-1" cvc-length="-1" state-id="1" payment-type="2" preferred="false" enabled="true" processor-type="2" installment="0" cvcmandatory="false" dcc="false" presentment-currency="false">
            <name>Invoice</name>
            <prefixes>
                <prefix id="178">
                    <min>-1</min>
                    <max>-1</max>
                </prefix>
                <prefix id="180">
                    <min>-1</min>
                    <max>-1</max>
                </prefix>
            </prefixes>Invoice
        </card>
    </vouchers>

8. Pay

The Pay request is an internal request from a merchant’s portal to Velocity when a customer initializes the payment. The purpose of this request is to do the following:

  • Retrieve information about how to proceed with the payment or PSP confirmation which gives an idea about the parameters required to authorize a transaction.
  • Ensure that a complete audit trail is maintained for each payment transaction.
  • This request can return different responses depending on the type of payment such as 3ds, non-3ds, wallet, alternative payment method (APM), or store card.

Note: Merchants do not require to call the Pay API if the following applies:

  • They opt to use the store vault of Velocity and their customers make payment using the stored cards.
  • Customers make payment using cards.

After consuming the Pay API, merchants must invoke the authorize API. Refer to Authorize Payment for details.

The API is available at the following path:

Path NamePath Details
End Point[Velocity URL]/mpoint/pay
Format/Content Typetext/xml
AuthenticationHTTP basic access authentication

8.1 Request

The following request is sent for a pay request:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<root>
<pay account="101011" client-id="10101">
<transaction id="5057200" store-card="false">
<card type-id="97">
<amount country-id="405" currency-id="170">25526000</amount>
<token>1022</token>
</card>
<hmac>f5ef1cfd960922babd492f06d6bf439a61de05cd395fc55225d5c1fb91801010a4dd6fa56872b6a8fa53cced7594582adb1d938f93f1859a1e794a85045f28a4</hmac>
<billing-address country-id="640">
<full-name>Test Automation</full-name>
<street>MyStreet</street>
<city>Pune</city>
</billing-address>
</transaction>
<auth-token>success</auth-token>
<client-info language="en" platform="HTML5" sdk-version="2.0.0" version="2.0.0">
<mobile country-id="640" operator-id="64000">9898989898</mobile>
<email>[email protected]</email>
<customer-ref>[email protected]</customer-ref>
<ip>223.235.105.4</ip>
</client-info>
</pay>
</root>

Note: The token information depends on the type of transaction.

ParameterTypeRequiredDescription
accountStringYesThe identification number of a merchant account
client-idIntegerYesThe unique ID of a merchant.
idStringYesCPD Transaction ID for which status is requested.
card type-idIntegerYesThe type of card used for a transaction.
amount country-idIntegerYesThe CPD-specific country code for the currency, which is made available to merchants on request.
currency-idIntegerNoThe currency of the transaction amount. This should be the ISO 4217 numeric code.
tokenStringNoThis is a card token.
hmacStringYesHash-based Message Authentication Code. It is calculated by creating a sha-512 hash comprising the following input fields in the listed order. *See table below.
Note: CPD provides the salt value to merchants. Conditional Parameters are optional if not provided in request, if conditional params are present in request those are mandatory MAC calculation secures the information sent by the merchant to Velocity by applying the SHA-512 encryption algorithm on key parts of the information sent to protect against tampering. The “salt” is the merchant's shared secret string used to ensure that MAC is unique.
billing-address country idStringYesThe billing address country ID of the customer.
full-nameStringYesThe full name of the customer.
streetStringYesThe street name of the customer.
cityStringYesThe city name of the customer.
auth-tokenStringNoA unique token sent to the specified auth-url to authenticate customers when they pay with a stored card and use single sign-on.
languageStringYesThe language that Velocity uses as default when translating the payment pages. Velocity uses a default language set by a merchant if this parameter is omitted.
Note: Velocity language codes are based upon the ISO- 639-1 standard. Refer to http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for details.
mobile country-idIntegerYesThe CPD-specific country code for country of mobile, which is made available to merchants on request.
emailStringYesThe email address of a customer. If your customer provides this parameter, the Email input field on the Send E-Mail Receipt page is automatically prepopulated with this value.
customer-refIntegerYesA unique reference number used for customer identification.

8.1.1 Request for Payu and SafetyPay

The following request is sent for a pay request for Payu and SafetyPay only:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<root>
<pay account="101011" client-id="10101">
<transaction id="5057200" store-card="false">
<card type-id="97">
<amount country-id="405" currency-id="170">25526000</amount>
<token>1022</token>
</card>
<hmac>f5ef1cfd960922babd492f06d6bf439a61de05cd395fc55225d5c1fb91801010a4dd6fa56872b6a8fa53cced7594582adb1d938f93f1859a1e794a85045f28a4</hmac>
<billing-address country-id="640">
<full-name>Test Automation</full-name>
<street>MyStreet</street>
<city>Pune</city>
<contact-details>
<mobile operator-id="40500" country-id="405">9898989898</mobile>
<email>[email protected]</email>
</contact-details>
</billing-address>
<additional-data>
                <param name="tax_id_type">COL_NIT</param>
                <param name="tax_id">123456</param>
</additional-data>
</transaction>
<auth-token>success</auth-token>
<client-info language="en" platform="HTML5" sdk-version="2.0.0" version="2.0.0">
<mobile country-id="640" operator-id="64000">9898989898</mobile>
<email>[email protected]</email>
<customer-ref>[email protected]</customer-ref>
<ip>223.235.105.4</ip>
</client-info>
</pay>
</root>

8.2.2 APM

8.2 Response

The pay response includes all the required parameters that Velocity sends to a merchant’s portal to authorize a payment.

8.2.1 Card Payment

The following is an example of a payment response for a card payment:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <psp-info id="[integer]" merchant-account="[integer]" type="1">
        <url content-type="application/x-www-form-urlencoded" method="post">[post URL]</url>
        <card-number>card_number</card-number>
        <expiry-month>expiration_month</expiry-month>
        <expiry-year>expiration_year</expiry-year>
        <cvc>securitycode</cvc>
        <name>card_holderName</name>
        <clientinfo>client_info</clientinfo>
        <accept-url>[ url]</accept-url>
        <return-url>return url</return-url>
        <hidden-fields>
            <merchant_account_id>9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant_account_id>
            <request_id>1838633_15172966764151</request_id>
            <transaction_type>10091</transaction_type>
            <requested_amount>100</requested_amount>
            <requested_amount_currency>USD</requested_amount_currency>
            <client-id>[integer]</client-id>
            <account-id>[integer]</account-id>
            <requested_amount_country>200</requested_amount_country>
            <store-card>false</store-card>
            <requested_currency_id>840</requested_currency_id>
            <transactionId>1838633</transactionId>
            <payment_ip_address>139.162.215.209</payment_ip_address>
            <email>email id</email>
            <phone>integer</phone>
            <card-type-id>7</card-type-id>
            <field_name_1>exp_month</field_name_1>
            <field_name_2>exp_year</field_name_2>
            <field_name_3>card_type_id</field_name_3>
            <field_value_3>7</field_value_3>
            <field_name_4>stored_card</field_name_4>
            <field_value_4>false</field_value_4>
            <card_type>mastercard</card_type>
            <notification_url_1>url</notification_url_1>
        </hidden-fields>
        <message language="en" />
    </psp-info>
    <status code="1009">Payment Initialize with PSP</status>
</root>

8.2.2 APM

The following is an example of payment response for APM:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <psp-info id="24" merchant-account="[integer]" type="4">
        <url content-type="application/x-www-form-urlencoded" method="post">https://www.sandbox.com/cgi-bin/webscr?cmd=_express-checkout&amp;token=EC-9NU6Xasdjl2B&amp;useraction=commit</url>
        <hidden-fields>
            <merchant>ababababaYYRCpSSRl31ADxVAF5rd9Z-52J.7gdxYOzAv3RD</merchant>
            <order.id>CPD1516873044132</order.id>
            <order.amount>100</order.amount>
            <order.currency>GBP</order.currency>
            <session.id>EC-9NU66762XE901272B</session.id>
            <transaction.id>1838548</transaction.id>
            <sourceOfFunds.type>CARD</sourceOfFunds.type>
            <mpoint-id>1838548</mpoint-id>
            <store-card>false</store-card>
            <requested_currency_id>826</requested_currency_id>
        </hidden-fields>
        <name>card_holderName</name>
        <message language="en"/>
    </psp-info>
    <status code="1009">Payment Initialize with PSP</status>
</root>

8.2.3 Wallet

The following is an example of a payment response for a wallet:

<?xml version="1.0" encoding="UTF-8"?>
<root>
<psp-info id="14" merchant-account="merchant.com.cellpointdigital.applepay"  type="3">
<url method="overlay"/>
<head>&lt;script type='text/javascript'&gt; var debug = false; var countryCode = "US"; var currencyCode = "USD"; var merchantIdentifier = 'merchant.com.cellpointdigital.applepay'; var displayName ="Ethiopian Airlines"; var totalAmount = "578.34"; var supportedNetword = ['VISA','MASTERCARD','AMEX']; &lt;/script&gt; &lt;script type="text/javascript" src="https://cpmassets.s3-ap-southeast-1.amazonaws.com/et/1.3.1/applepay.js"&gt;&lt;/script&gt; &lt;style&gt; #applePay{width:150px;height:50px;display:none;border-radius:5px;background-image:-webkit-named-image(apple-pay-logo-white);background-position:50% 50%;background-color:#000;background-size:60%;background-repeat:no-repeat} &lt;/style&gt;</head>
<body>&lt;button type="button" id="applePay"&gt;&lt;/button&gt;</body>
<name>card_holderName</name>
<auth-token>Auth-Token</auth-token>
<message language="en"></message>
</psp-info>
<status code="1009">Payment Initialize with PSP</status>
</root>

8.2.4 Online Banking

The following is an example of a payment response for online banking:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<root>
<psp-info id="53" merchant-account="" type="4">
<url content-type="application/x-www-form-urlencoded" method="GET" type-id="11">https://sandbox.api/payments-api/pse-caller</url>
<hidden-fields>
<enc>adpc3Ryby5kZXNhcnJvbGxvLnBzZS5jb20uY28vUFNFVXNlclJlZ2lzdGVyL1N0YXJ0VHJhbnNhY3Rpb24uYXNweZUU5dUxxYW4lMmI0elBDcU94S3I1b09ySXZTSmYwRElPcno0RjV3S0pQdU0jIyMjQVYgM0JWOVBMIyMxMjM0NTY3OA==</enc>
</hidden-fields>
<accept-url>https://sit.cpm.dev/mpoint/aggregator/(PSP name)/redirect</accept-url>
<name>card_holderName</name>
<auth-token>Auth-Token</auth-token>
<message language="en"/>
</psp-info>
<status code="1041">Payment Pending</status>
</root>

The parameters are listed and defined in the table below.

Parameter Type Required Description
Client Information Parameters
language String Yes The language that Velocity uses as default when translating the payment pages.
Note: Velocity language codes are based upon the ISO- 639-1 standard.
Refer https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for details.
version String Yes The version of an API or application that sends the request.
platform String Yes The platform from which the request is sent; for example, The platform from which the request is sent. It can be:
  • Web
  • iOS
  • Android
  • B2B
  • B2C
  • Application
  • SPA
mobile operator-id Integer Yes The ID of a customer’s mobile network operator. CPD recommends including this parameter in the request to ensure Velocity correctly interacts with the operator.
country-id Integer Yes The CPD-specific country code, which is made available to merchants on request.
client-id Integer Yes A unique ID configured for a merchant on the Velocity POP.
device-id String No The device ID of a customer’s device.
Note: Device ID is optional for a web channel.
fees/fee Integer No This the addition fees if applicable for the transaction like for specific scenarios like administrative fee for offline payment or pay later. For example, the smallest currency of USD is penny. If the transaction amount is $120.30, then the amount field contains value 12030.
Note: The fee is always a non-decimal value in the request. The object amount contains the country-id and currency-id parameters.
customer-reference Integer Yes A unique reference number used for customer identification.
Account Parameters
id String No The identification number of a merchant account.
markup String Yes The type of store front.
Transaction Parameters
id Integer Yes The identification number of a transaction.
store-card Boolean yes Shows if you have stored card.
Card Parameters
amount Integer Yes The total amount that a customer is charged for a payment transaction in a country’s smallest currency. For example, the smallest currency of USD is penny. If the transaction amount is $120.30, then the amount field contains value 12030.
Note: The amount is always a non-decimal value in the request. The object amount contains the country-id and currency-id parameters.
type-id Integer Yes The type of card scheme. For example, Mastercard or Visa.
token String No This is a card token.
token String No This is a card token.
psp-info Parameters
id integer yes Internal ID of the PSP in Velocity
merchant-account integer No Used for merchant-account for third-party wallet on device.
content-type String No The content type used for the request to the PSP.
method Integer Yes The method used for submitting the authorization request. Method Description App Used for payment with the third-party wallet on the device. GET Using HTTP GET. POST Using HTTP POST.
Method Description
App Used for payment with the third-party wallet on the device.
GET Using HTTP GET.
POST Using HTTP POST.
token String No This is a card token.
order-id Alpha numeric string Yes The order identification number of a transaction.
transaction-id Integer Yes A unique transaction identification number of a transaction.
store-card Boolean yes Shows if you have stored card.
requested_currency_id Integer No The identification number of the currency called during a transaction.
language String Yes The language that Velocity uses as default when translating the payment pages. Velocity uses a default language set by a merchant if this parameter is omitted.
Note: Velocity language codes are based upon the ISO- 639-1 standard. Refer https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for details.
Status Parameter
Code Integer yes The status code of a transaction. It depends on the payment provider. It can be 1009, 1041, or an error code.

9. Authorize Payment

The authorize payment request is used to authorize a payment. The API is available at the following path:

Path NamePath Details
End Point[Velocity URL]/mpoint/ authorize-payment
Format/Content Typetext/xml
AuthenticationHTTP basic access authentication

9.1 Request

There are alternative request formats depending on the payment methods selected during a payment.

9.1.1 New Card

The following is an example of making a payment using a new card:

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <authorize-payment account="100101" client-id="10002">
    <transaction type-id="30" id="1832214" store-card="false" >
      <card type-id="7">
        <amount country-id="200">100</amount>
        <card-holder-name>CardHolder Name</card-holder-name>
        <card-number>"card_number"</card-number>
        <expiry>01/23</expiry>
        <cvc>009</cvc>
      </card>
    </transaction>
    <client-info language="en" version="1.28" platform="iOS/9.0">
      <mobile operator-id="10000" country-id="[integer]">[phone number]</mobile>
      <email>[email id]</email>
      <device-id>3432444444444444444FFFFFf03</device-id>
    </client-info>
  </authorize-payment>
</root>

9.1.2 Credit or Debit Card

The following is an example of a payment using a credit or debit card:

<?xml version="1.0" encoding="UTF-8"?> 
  <authorize-payment account="100691" client-id="10069">
    <transaction type-id="10091" id="1935288">
      <card type-id="8">
        <amount country-id="603">85556</amount>
            <card-holder-name>CellPointMobie</card-holder-name>
            <card-number>"card_number"</card-number>
            <expiry>11/18</expiry>
      </card>
    </transaction>
    <client-info language="da" version="1.28" platform="iOS/9.0">
      <mobile operator-id="10000" country-id="200">[phone number]</mobile>
      <email>[email id]</email>
      <device-id>B4D54A3A4F5E4E1595F7A3BF16249F6D14555303</device-id>
    </client-info>
  </authorize-payment>

9.1.3 Third-party Wallet

The following is an example of a payment using a third-party wallet:

	<?xml version="1.0" encoding="UTF-8"?>
<root>
  <authorize-payment account="[integer]" client-id="[integer]">
    <transaction type-id="[integer]" id="[integer]">
      <card network="mastercard" type-id="[integer]">
        <address country-id="[integer]">
          <full-name>test name</full-name>
          <street>Gl. test street 8</street>
          <postal-code>7766</postal-code>
          <city>testCity</city>
          <state>CA</state>
        </address>
        <amount country-id="[integer]">10025</amount>
        <token>dasdlkjasl31232123231dkdlsakldfmggmmggm........</token>
      </card>
    </transaction>
    <client-info language="en" version="1.20" platform="iOS/8.1.3">
      <mobile operator-id="[integer]" country-id="[integer]">[phone number]</mobile>
      <device-id>32E2C0FAF455915D14298774</device-id>
    </client-info>
  </authorize-payment>

9.1.4 Voucher

The following is an example of making a payment using a voucher:

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <authorize-payment account="100101" client-id="10002">
    <transaction type-id="30" id="1832214" store-card="false" >      
<voucher id=”[string]” order-no=”[string]”>
        <amount currency-id=”840” country-id="200">100</amount>
      </voucher>
    </transaction>
    <client-info language="en" version="1.28" platform="iOS/9.0">
      <mobile operator-id="10000" country-id="[integer]">[phone number]</mobile>
      <email>[email id]</email>
      <device-id>3432444444444444444FFFFFf03</device-id>
    </client-info>
  </authorize-payment>
</root>

9.1.5 3D secure authenticated card

The following is an example of a payment using a credit or debit card with 3D secure information:

	<?xml version="1.0" encoding="UTF-8"?>
<authorize-payment account="100691" client-id="10069">
<transaction type-id="10091" id="1935288">
<card type-id="8">
<amount country-id="603">85556</amount>
<card-holder-name>CellPointMobie</card-holder-name>
<card-number>"card_number"</card-number>
<expiry>11/18</expiry>
<pre_authenticated>true/false</pre_authenticated>
<info-3d-secure>
<provider>{{provider_which_is_used_for_authentication}}</provider>
<version>{{3DS Version}}</version>
<cryptogram eci="{{eci}}" xid="{{xid}}" algorithm-id="{{algorithm}}"> 
            {{cryptogram}} 
            </cryptogram>
<additional-data>
<param name="status">{{status}}</param>
<param name="msg">{{msg}}</param>
<param name="veresEnrolledStatus">{{veres enrolled status}}</param>
<param name="paresTxStatus">{{paresTxStatus}}</param>
<param name="PAResVerified">{{PAResVerified}}</param>
<param name="PAResSyntaxOK">{{PAResSyntaxOK}}</param>
<param name="cardType">{{cardType}}</param>
<param name="accessControlServerTransactionId">{{accessControlServerTransactionId}}</param>
<param name="threeDSServerTransID">{{threeDSServerTransID}}</param>
<param name="directoryServerTransactionId">{{directoryServerTransactionId}}</param>
</additional-data>
</info-3d-secure>
</card>
</transaction>
<client-info language="da" version="1.28" platform="iOS/9.0">
<mobile operator-id="10000" country-id="200">[phone number]</mobile>
<email>[email id]</email>
<device-id>B4D54A3A4F5E4E1595F7A3BF16249F6D14555303</device-id>
</client-info>
</authorize-payment>
Parameter Type Required Description
card
pre_authenticated String No True: In Case of 3DS already done at the merchant end.
Info-3d-secure Parameter
version String Yes The version of 3DS used to process the transaction.
  • For 3DS1 - 1.0.2
  • For 3DS2 - 2.1.0 or 2.2.0
provider String No The provider’s name which is used for authentication.
cryptogram String Conditional Required, if eci value is 01, 02, 05 or 06. A cryptographic value that provides evidence of the outcome of a 3DS verification.
  • Visa - Cardholder Authentication Verification Value (CAVV)
  • Mastercard - Universal Cardholder Authentication Field (UCAF)
eci String Yes Electronic Commerce Indicator (ECI). It indicates the outcome of the 3DS verification.
  • 02 or 05 - Fully Authenticated Transaction
  • 01 or 06 - Attempted Authentication Transaction
  • 00 or 07 - Non 3-D Secure Transaction
  • Mastercard - 02, 01, 00
  • Visa - 05, 06, 07
  • Amex - 05, 06, 07
  • JCB - 05, 06, 07
  • Diners - 05, 06, 07
xid String Conditional This is mandatory for 3DS Version 1.
algorithm-id String No A cryptographic algorithm used for cryptograms.
additional-data Node No In the case of 3DS version 2 directoryServerTransactionId param, it is mandatory. An optional node that contains additional information about the 3DS authentication transaction provided by an external authentication service. It includes a list of parameters with values. For example:
  • accessControlServerTransactionId : ACS server transaction ID
  • directoryServerTransactionId: Directory server trasnaction id (Mandatory for 3DS version 2.0)

9.2 Response

The Velocity server sends the response confirming if the transaction authorization was a success or a failure. The following example shows that a payment request was authorized successfully:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <status code="2000">Payment authorized</status>
</root>

The following is an example of response received for a failed authorization:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <status code="2010" sub-code="2010205"> Unable to authorize</status>
</root>

The parameters are listed and defined in the table below.

ParameterTypeRequiredDescription
statusStringYesDescribes the status code.
codeIntegerYesA status code for the authorizing processes.
sub-codeIntegerYesThe granular-level status code which shows the reason for a failed authorization.

9.2.1 3DS 1.0 Authentication Required

The following is an example of response received for 3DS 1.0 authentication required:

<?xml version="1.0" encoding="UTF-8"?>
<root>
   <status code="2005">3d verification required</status>
   <parsed-challenge>
      <action type-id="11">
         <url content-type="application/x-www-form-urlencoded" method="post">https://3ds-acs.test.modirum.com/mdpayacs/creq?token=220646651.1670842886.KJTk10b79hUunC4uy7erl0gOsaZW7UHoEh56a0-9Un4</url>
         <hidden-fields>
            <creq>ewogICAiYWNzVHJhbnNJRCIgOiAiZjEyZjUxMDItOTI4ZC00N2I3LTg1YjAtZTM5NDhjYjIzZDY1IiwKICAgImNoYWxsZW5nZVdpbmRvd1NpemUiIDogIjAzIiwKICAgIm1lc3NhZ2VUeXBlIiA6ICJDUmVxIiwKICAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjIuMCIsCiAgICJ0aHJlZURTU2VydmVyVHJhbnNJRCIgOiAiMzIwYmUxM2MtYmQ4ZC01YzliLTgwMDAtMDAwMDAxMjRiYTM1Igp9</creq>
            <TermUrl>https://5j.mesb.sit.cpm.dev/mpoint/first-data/threed-redirect?referencedTransactionId=5721077</TermUrl>
         </hidden-fields>
      </action>
   </parsed-challenge>
</root>

The steps to process the authorize response for the 3DS 1.0 authentication are as follows:

  1. Extract the content of tags .
  2. Do a form post of all the fields hidden-fields to the url in the action tag using browser.
  3. Follow the instruction to complete authentication.
  4. After the authentication is complete, it is redirected to your Accept or Decline URL.
  5. The Callback notification with the authorization status is sent to your Callback URL.

9.2.2 3DS 2.0 Authentication Required

The following is an example of response received for 3DS 2.0 authentication required:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <status code="2005" sub-code="2005002">3D Secure Verification Required</status>
    <web-method>&lt;html class="no-js" lang="en" xmlns="http://www.w3.org/1999/xhtml"&gt; &lt;head&gt; &lt;META http-equiv="Content-Type" content="text/html; charset=utf-8"&gt; &lt;meta http-equiv="Content-Type" content="text/html; charset=utf-8"&gt; &lt;meta charset="utf-8"&gt; &lt;title&gt;3D Secure Processing&lt;/title&gt; &lt;link href="https://3ds-mpi-cellpointmobile.test.modirum.com/mdpaympi/static/mpi.css" rel="stylesheet" type="text/css"&gt; &lt;/head&gt; &lt;body&gt; &lt;div id="main"&gt; &lt;div id="content"&gt; &lt;div id="order"&gt; &lt;h2&gt;3D Secure Processing&lt;/h2&gt; &lt;script src="https://3ds-mpi-cellpointmobile.test.modirum.com/mdpaympi/static/red.js" defer&gt;/* needed for xsl to xhtml */&lt;/script&gt; &lt;div id="spinner"&gt; &lt;img src="https://3ds-mpi-cellpointmobile.test.modirum.com/mdpaympi/static/preloader.gif" alt="Please wait.."&gt;&lt;/div&gt; &lt;img src="https://3ds-mpi-cellpointmobile.test.modirum.com/mdpaympi/static/mc_idcheck_hrz_ltd_pos_103px.png" alt="MasterCard ID Check"&gt;&lt;iframe id="tdsMmethodTgtFrame" name="tdsMmethodTgtFrame" xmlns="http://www.w3.org/1999/xhtml"&gt;&lt;!--.--&gt; &lt;/iframe&gt;&lt;form id="tdsMmethodForm" name="tdsMmethodForm" action="https://3ds-acs.test.modirum.com/mdpayacs/3ds-method" method="post" target="tdsMmethodTgtFrame"&gt; &lt;input type="hidden" name="3DSMethodData" value="eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogImRkZjQ5MTYxLTZiYjgtNWY5YS04MDAwLTAwMmVhNzE4N2E0ZCIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIiA6ICJodHRwczovLzNkcy1tcGktY2VsbHBvaW50bW9iaWxlLnRlc3QubW9kaXJ1bS5jb20vbWRwYXltcGkvTWVyY2hhbnRTZXJ2ZXI_bW49WSZ0eGlkPTIwMDM3MTg5NDg2MSZkaWdlc3Q9UFVyQ3ZnWnZZeHp0cVU1a1N2MTdTdnhjUlVXaTAwWVByNlh5MmttWCUyQkg0JTNEIiB9"&gt;&lt;input type="hidden" name="threeDSMethodData" value="eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogImRkZjQ5MTYxLTZiYjgtNWY5YS04MDAwLTAwMmVhNzE4N2E0ZCIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIiA6ICJodHRwczovLzNkcy1tcGktY2VsbHBvaW50bW9iaWxlLnRlc3QubW9kaXJ1bS5jb20vbWRwYXltcGkvTWVyY2hhbnRTZXJ2ZXI_bW49WSZ0eGlkPTIwMDM3MTg5NDg2MSZkaWdlc3Q9UFVyQ3ZnWnZZeHp0cVU1a1N2MTdTdnhjUlVXaTAwWVByNlh5MmttWCUyQkg0JTNEIiB9"&gt; &lt;/form&gt;&lt;div id="formdiv"&gt; &lt;div&gt; &lt;form id="webform0" name="ddcoll" method="POST" action="https://3ds-mpi-cellpointmobile.test.modirum.com/mdpaympi/MerchantServer" accept_charset="UTF-8"&gt; &lt;input type="hidden" name="txid" value="200371894861"&gt;&lt;input type="hidden" name="TDS2_Navigator_language" value=""&gt;&lt;input type="hidden" name="TDS2_Navigator_javaEnabled" value=""&gt;&lt;input type="hidden" name="TDS2_Navigator_jsEnabled" value=""&gt;&lt;input type="hidden" name="TDS2_Screen_colorDepth" value=""&gt;&lt;input type="hidden" name="TDS2_Screen_height" value=""&gt;&lt;input type="hidden" name="TDS2_Screen_width" value=""&gt;&lt;input type="hidden" name="TDS2_Screen_PixelDepth" value=""&gt;&lt;input type="hidden" name="TDS2_TimezoneOffset" value=""&gt;&lt;input type="hidden" name="digest" value="5woOk3ql1bNMosc5yuyLXdk8k47KCTR+uVloWvAA/XQ=" readonly="true"&gt;&lt;input type="submit" name="submitBtn" id="submitBtn" value="Please click here to continue"&gt; &lt;/form&gt; &lt;/div&gt; &lt;/div&gt; &lt;noscript&gt; &lt;div align="center"&gt; &lt;b&gt;Javascript is turned off or not supported!&lt;/b&gt; &lt;br&gt; &lt;/div&gt; &lt;/noscript&gt; &lt;/div&gt; &lt;div id="content-footer"&gt;&lt;/div&gt; &lt;/div&gt; &lt;/div&gt; &lt;/body&gt; &lt;/html&gt;</web-method>
    <return-url>https://av.uat-01.cellpointmobile.net/mpi/modirum/threed-redirect</return-url>
    <card-mask>553571******3561</card-mask>
    <expiry>01/23</expiry>
    <token>4eeb155fc20fa07a7c01d82aa68f9d22cab6257c57b6694d722cfdc8b95dce4d2f8f44e0a5c9aab14065e1f2016fc95eb0185cb62689b78e8e06346429c1aedc</token>
</root>

The steps to process the authorize response for the 3DS 2.0 authentication are as follows:

1. Extract the content of tag <Web method>.

2. HTML decode the web-method content to get the HTML.

3. Load the HTML on the browser and follow the instruction to complete authentication.

4. After the authentication is complete, it is redirected to your Accept or Decline URL.

5. The Callback notification with authorization status is sent to your Callback URL.

10.Ticket-level Capture

This API facilitates ticket-level capture for automatic captures. After updating AID data, Velocity captures the amount internally and passes the information to PSPs for payment processing. Thereafter, it is passed to the merchant system. You do not need call the capture API. Call the update-order-data API to facilitate ticket-level auto-capture.
Use the following API to capture ticket-level information.

Path NamePath Details
End Point[Velocity URL]/mpoint/ update-order-data
Format/Content Typetext/xml
AuthenticationHTTP basic access authentication

10.1 Request

The code below is a sample request for the Order Ticket API.

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <update-order-data>
        <transaction id="12345" order-no="FIU9YA">
            <orders>
                <line-item>
                    <product order-ref="ABC1234" sku="product-ticket">
                        <type>100</type>
                        <name>ONE WAY</name>
                        <description>MNL-CEB</description>
                        <airline-data>
                            <profiles>
                                <profile>
                                    <seq>1</seq>
                                    <title>Mr</title>
                                    <first-name>dan</first-name>
                                    <last-name>dan</last-name>
                                    <type>ADT</type>
                                    <contact-info>
                                        <email>[email protected]</email>
                                        <mobile country-id="640">9187231231</mobile>
                                    </contact-info>
                                    <additional-data>
                                        <param name="loyality_id">345rtyu</param>
                                    </additional-data>
                                </profile>
                            </profiles>
                            <billing-summary>
                                <fare-detail>
                                    <fare>
                                        <profile-seq>1</profile-seq>
                                        <description>adult</description>
                                        <currency>PHP</currency>
                                        <amount>60</amount>
                                        <product-code>ABF</product-code>
                                        <product-category>FARE</product-category>
                                        <product-item>Base fare for adult</product-item>
                                    </fare>
                                </fare-detail>                               
                            </billing-summary>
                            <trips>
                                <trip tag="1" seq="1">
                                    <origin external-id="MNL" country-id="640" time-zone="+08:00" terminal="1">Ninoy Aquino International Airport</origin>
                                    <destination external-id="CEB" country-id="640" time-zone="+08:00" terminal="2">Mactan Cebu International Airport</destination>
                                    <departure-time>2021-03-07T19:35:00Z</departure-time>
                                    <arrival-time>2021-03-07T21:05:00Z</arrival-time>
                                    <booking-class>Z</booking-class>
                                    <service-level>Economy</service-level>
                                    <transportation code="5J" number="1">
                                        <carriers>
                                            <carrier code="5J" type-id="Aircraft Boeing-737-9">
                                                <number>563</number>
                                            </carrier>
                                        </carriers>
                                    </transportation>
                                    <additional-data>
                                        <param name="fare_basis">we543s3</param>
                                    </additional-data>
                                </trip>
                            </trips>
                        </airline-data>
                    </product>
                    <amount>125056</amount>
                    <quantity>1</quantity>
                    <additional-data>
                        <param name="key">value</param>
                    </additional-data>
                </line-item>
                <line-item>
                    <product order-ref="ABC1237" sku="product-ticket">
                        <type>200</type>
                        <name>ONE WAY</name>
                        <description>MNL-CEB</description>
                        <airline-data>
                            <profiles>
                                <profile>
                                    <seq>1</seq>
                                    <title>Mr</title>
                                    <first-name>dan</first-name>
                                    <last-name>dan</last-name>
                                    <type>ADT</type>
                                    <contact-info>
                                        <email>[email protected]</email>
                                        <mobile country-id="640">9187231231</mobile>
                                    </contact-info>
                                    <additional-data>
                                        <param name="loyality_id">345rtyu</param>
                                    </additional-data>
                                </profile>
                            </profiles>
                            <billing-summary>                            
                                <add-ons>
                                    <add-on>
                                        <profile-seq>1</profile-seq>
                                        <trip-tag>2</trip-tag>
                                        <trip-seq>2</trip-seq>
                                        <description>adult</description>
                                        <currency>PHP</currency>
                                        <amount>60</amount>
                                        <product-code>ABF</product-code>
                                        <product-category>FARE</product-category>
                                        <product-item>Base fare for adult</product-item>
                                    </add-on>
                                </add-ons>
                            </billing-summary>
                            <trips>
                                <trip tag="1" seq="1">
                                    <origin external-id="MNL" country-id="640" time-zone="+08:00" terminal="1">Ninoy Aquino International Airport</origin>
                                    <destination external-id="CEB" country-id="640" time-zone="+08:00" terminal="2">Mactan Cebu International Airport</destination>
                                    <departure-time>2021-03-07T19:35:00Z</departure-time>
                                    <arrival-time>2021-03-07T21:05:00Z</arrival-time>
                                    <booking-class>Z</booking-class>
                                    <service-level>Economy</service-level>
                                    <transportation code="5J" number="1">
                                        <carriers>
                                            <carrier code="5J" type-id="Aircraft Boeing-737-9">
                                                <number>563</number>
                                            </carrier>
                                        </carriers>
                                    </transportation>
                                    <additional-data>
                                        <param name="fare_basis">we543s3</param>
                                    </additional-data>
                                </trip>
                            </trips>
                        </airline-data>
                    </product>
                    <amount>125056</amount>
                    <quantity>1</quantity>
                    <additional-data>
                        <param name="key">value</param>
                    </additional-data>
                </line-item>             
            </orders>
        </transaction>
    </update-order-data>
</root>

This API must be called for each transaction associated with the order number separately. Each request contains one or more line-item that are associated with the order-ref (ticket/emd number).

Refer to the examples listed below:

Payment MethodOrder # PNRABC $1000UATP Card $100 Request 1VISA Card $900 Request 2
Transaction IDTransaction 1Transaction 2
Ticket Number
1 line-item		50500
Ticket Number
2 line-item		47525450
Ticket Number
3 line-item		47525450

Following are the description of the fields under update-order-data:

ParameterTypeRequiredDescription
transaction/ @idIntegerYesThe identification number of a transaction
Transaction/order-nostringYesOrder number associated with the transaction.
ordersnodeYesContains one or more line-item.
For details of all the fields under orders refer to the AID - Airline Itinerary Integration Guide.

10.2 Response

The response of this API can be either a successful or a failed transaction.

10.2.1 Success

You receive the following response for a successful transaction:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <status code="100">Operation Success</status>
</root>

10.2.2 Fail

You receive the following response for a failed transaction:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <status code="99">Operation Failed</status>
</root>

11. Capture

After a customer completes the checkout process, the authorized transaction is captured. You can invoke this API to capture the payment amount. Velocity exposes an API to capture an authorized transaction. The amount field can take values equal to or less than the authorized amount. You can facilitate either a complete capture or a partial capture. If the authorized amount is greater than the authorized amount and greater than one, it is a partial capture.

Note: Invoke this API only if you enable manual capture. Do not invoke if you have enabled auto-capture.

Use the following API to capture transaction-level information:

Path NamePath Details
End Point[Velocity URL]/mpoint/ capture-payment
Format/Content Typetext/xml
AuthenticationHTTP basic access authentication

11.1 Request

The following is an example of a request API used to capture an authorized transaction. It is sent from the merchant’s server to Velocity. It contains the transaction details of a customer.

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <capture client-id="[integer]" account="[integer]">
        <transaction id="[integer]" order-no="UAT-28577880">
            <amount country-id="100">10000</amount>
        </transaction>
    </capture>
</root>

11.2 Response

The following is an example of the response returned from Velocity server to a merchant. It contains the transaction ID and transaction status.

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <transactions client-id="[integer]">
        <transaction id="[integer]" order-no="28577880">
            <status code="1000" />
        </transaction>
    </transactions>
</root>

12. Get Payment Summary

Velocity exposes an API for retrieving the decrypted payment summary including the masked card number from various wallets.

Use the following API to get payment summary information:

Path NamePath Details
End Point[Velocity URL]/mpoint/ get-payment-summary
Format/Content Typetext/xml
AuthenticationHTTP basic access authentication

12.1 Request

Merchants need to consume this API for wallet integration only. For example, if you have integrated Apple Pay or Google Pay and want to show the card number to your customer in a masked manner, you can call this API.

The following is an example of a request for retrieving the payment summary:

12.2 Response

If the Get Payment Summary API request is successful, the masked card details are shown to a customer as a response.

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <card id="7" charge-type-id="2">
        <card-number-mask>540287******4924</card-number-mask>
        <expiry>10/17</expiry>
        <card-holder-name>Joe Test</card-holder-name>
        <address country-id="200">
            <first-name>Joe</first-name>
            <last-name>Test</last-name>
            <street>4000 Ponce De Leon Blvd</street>
            <postal-code>33146</postal-code>
            <city>Coral Gables</city>
            <state>FL</state>
        </address>
    </card>
</root>

The parameters are listed and defined in the table below

ParameterTypeDescription
get-payment-summaryObjectThe object which contains details of the payment summary.
client-idIntegerThe unique ID of a merchant.
transaction idIntegerA unique transaction identification number of a transaction.
card type-idIntegerThe type of card used for a transaction.
tokenStringThe encrypted alpha-numeric string to represent card information used in third-part wallet.
client-infoStringThe object which contains details of language used for a transaction, version, and platform details.
device-idStringThe unique device identification number from which a transaction is conducted.
card idIntegerThe ID which indicates the type of card used for a transaction.
charge-type-idIntegerThe ID to indicate the type of wallet used for a transaction.
maskStringThe masked value of a card number.
expiryStringThe expiration date of a card.
card-holder-nameStringThe name of a card holder.
addressObjectThe object which contains address details such as country-id, first name, last name, street name, postal code, city, and state.

13.Get Transaction Status

Velocity exposes an API for retrieving the transaction status based on the transaction ID and session status based on session ID. This API is useful to reverify a transaction status when, for example, the authorize API does not show a response because of network issues or after redirection flow.

Note: Consider the following items:

  • CPD recommends integrating the Get Status API, which is optional.
  • You can configure this API to view the transaction status on your web portal or on your server.

Refer to transaction Status Codes for details

You can use the following API to get the payment summary information:

Path NamePath Details
End Point[Velocity URL]/mpoint/get-transaction-status
Format/Content Typetext/xml
AuthenticationHTTP basic access authentication

13.1 Request

The following is an example for fetching Transaction status:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <get-transaction-status>
        <client-id>10101</client-id>
        <transactions>
            <transaction-id>5297501</transaction-id>
        </transactions>
    </get-transaction-status>
</root>

The following is an example for fetching Session status:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <get-transaction-status>
        <client-id>10101</client-id>
        <session_id>533234</session_id>
    </get-transaction-status>
</root>

The parameters are listed and defined in the table below.

ParameterTypeRequiredDescription
Client-idStringYesA unique ID for Velocity, which CPD creates for a merchant.
account-idStringYesThe ID or number for a sub-account with which a payment transaction is associated. CPD provides the account number.
transaction-idStringYesCPD Transaction ID for which status is requested.

13.2 Response

The following are examples of a response for the Get Transaction Status API:

13.2.1 Card Payment Transaction Status

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <transaction accoutid="100630" approval-code="121000" card-id="7" clientid="10063" extid="CPM5670_
8060858" id="8060858" language="en" mpoint-id="8060858" order-no="CPM5670" payment-method-id="1"
psp-id="4" session-id="178752" session-type=" walletid="4">
        <amount conversationRate="1" country-id="103" currency="826" currency-code="GBP" decimals="2"
format="{CURRENCY}{PRICE}" pending="0" symbol="£">1000</amount>
        <card-mask>554433******0003</card-mask>
        <dummy-account-number>5544330000090003</dummy-account-number>
        <card-expiry>10/23</card-expiry>
        <card-name>Master Card</card-name>
        <psp-name>WorldPay</psp-name>
        <accept-url>https://cpm-hpp2-sit2.cellpointmobile.com/views/redirect_response.php</accept-url>
        <cancel-url>https://cpm-hpp2-sit-01.cellpoint.dev/views/</cancel-url>
        <css-url>https://s3-ap-southeast-1.amazonaws.com/devcpmassets/marchant/et/style.css</css-url>
        <logo-url>https://hpp-uat-02.cellpointmobile.net/css/swag/img/cebu.png</logo-url>
        <google-analytics-id>%7B%22id%22%3A%22GTM-TJHF9HX%22%2C%22auth%22%3A%220bNRJejIX9R
vP164Mor_Tw%22%2C%22preview%22%3A%22env-61%22%2C%22env%22%3A%22sit%22%7D</google-analytics-id>
        <form-method>GET</form-method>
        <auto-redirect>true</auto-redirect>
        <createdDate>2021-03-04</createdDate>
        <createdTime>07:55:32</createdTime>
        <status>
            <status-message id="1001" position="1">Input Valid</status-message>
            <status-message id="1009" position="2">Payment Initialized with Payment Service Provider</status-message>
            <status-message id="1990" position="14">Callback Accepted</status-message>
            <status-message id="1990" position="17">Callback Accepted</status-message>
            <status-message id="1990" position="23">Callback Accepted</status-message>
            <status-message id="1990" position="25">Callback Accepted</status-message>
            <status-message id="1991" position="12">Callback Constructed</status-message>
            <status-message id="1991" position="15">Callback Constructed</status-message>
            <status-message id="1991" position="20">Callback Constructed</status-message>
            <status-message id="1991" position="22">Callback Constructed</status-message>
            <status-message id="1992" position="13">Callback Connected</status-message>
            <status-message id="1992" position="16">Callback Connected</status-message>
            <status-message id="1992" position="21">Callback Connected</status-message>
            <status-message id="1992" position="24">Callback Connected</status-message>
            <status-message id="2000" position="9">Payment authorized by PSP</status-message>
            <status-message id="2001" position="18">Payment captured by PSP</status-message>
            <status-message id="2005" position="5">3d verification required for Authorization</status-message>
            <status-message id="2006" position="7">3d verification successful</status-message>
            <status-message id="3010" position="3">Pre Auth Initiated</status-message>
            <status-message id="3014" position="4">Pre Auth Review</status-message>
            <status-message id="3117" position="10">Post Auth Screen Skip - Business Rules</status-message>
            <status-message id="4030" position="19">Session Complete</status-message>
            <status-message id="20012" position="11">Capture Initialized</status-message>
            <status-message id="2005001" position="6">Authentication Card is enrolled Attempt authentication using 3DSv1.0</status-message>
            <status-message id="2006001" position="8">Authentication Fully</status-message>
        </status>
        <sign>8aabe019e70972acaddb0bc09101e35e</sign>
        <client-info language="en" platform="app" profileid="-1">
            <mobile country-id="640" operator-id="64000">9876543210</mobile>
            <email>[email protected]</email>
            <customer-ref />
            <device-id />
        </client-info>
        <additional-data>
            <param name="pre_auth_ext_status_code">105</param>
            <param name="eci">02</param>
            <param name="xid">MDAwMDAwMDAwMDAwMDgwNjA4NTg=</param>
            <param name="merchant">CELLPOINT</param>
            <param name="issuer-approval-code">121000</param>
        </additional-data>
        <address>
            <first-name>Test</first-name>
            <last-name>Automation</last-name>
            <street>MyStreet</street>
            <street2 />
            <postal-code>8060858</postal-code>
            <city>Pune</city>
            <state>MH</state>
            <country>
                <name>Philippines</name>
                <code>608</code>
                <alpha2code>PH</alpha2code>
                <alpha3code>PHL</alpha3code>
            </country>
        </address>
    </transaction>
</root>

13.2.2 APM (PayPal) Transaction Status

13.2.3 APM (GRAB PAY) Transaction Status

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <transaction accoutid="100770" approval-code="" card-id="28" clientid="10077" extid="69U82640BX0039150"
id="8059428" language="en" mpoint-id="8059428" order-no="WAIKALZ" payment-method-id="4" psp-id="24"
session-id="177544" session-type="" walletid="0">
        <amount conversationRate="1" country-id="640" currency="608" currency-code="PHP" decimals="2" format=""
pending="0" symbol="â±">55500</amount>
        <card-name>PayPal</card-name>
        <psp-name>PayPal</psp-name>
        <accept-url>https://hpp2.sit-01.cellpoint.dev/views/redirect_response.php</accept-url>
        <cancel-url>https://hpp2.sit-01.cellpoint.dev/views/redirect_response.php</cancel-url>
        <css-url>https://cpd-hpp2-devassests.s3.eu-central-1.amazonaws.com/10077</css-url>
        <logo-url>https://cpd-hpp2-devassests.s3.eu-central-1.amazonaws.com/10077/logo.png</logo-url>
        <google-analytics-id>%7B%22id%22%3A%22GTM-TJHF9HX%22%2C%22auth%22%3A%220bNRJejIX9RvP164Mor
_Tw%22%2C%22preview%22%3A%22env-61%22%2C%22env%22%3A%22sit%22%7D</google-analytics-id>
        <form-method>GET</form-method>
        <auto-redirect>true</auto-redirect>
        <createdDate>2021-02-27</createdDate>
        <createdTime>06:34:04</createdTime>
        <status>
            <status-message id="2001" position="1">Payment captured by PSP</status-message>
        </status>
        <sign>bf2f4194205c9839e67547b860c4a05b</sign>
        <client-info language="en" platform="spa" profileid="CEBUPROFILE123">
            <mobile country-id="640" operator-id="64000">2147483647</mobile>
            <email>[email protected]</email>
            <customer-ref>[email protected]</customer-ref>
            <device-id />
        </client-info>
        <additional-data>
            <param name="invoiceid">8059428</param>
        </additional-data>
    </transaction>
</root>

13.2.4 Split Payment Session Status

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <session id="533234" total-amount="160000000" type="2">
        <amount alpha2code="CO" alpha3code="COL" code="170" country-id="405" currency="COP" currency-id="170" format="" symbol="$">0</amount>
        <status>4030</status>
    </session>
    <transaction accoutid="101011" approval-code="654321" card-id="7" clientid="10101" extid="000000033710000442590000100001" id="5297500" language="en" mpoint-id="5297500" order-no="QLG763" payment-method-id="1" psp-id="21" session-id="533234" session-type="2" txn-type-id="1" walletid="-1">
        <amount conversationRate="1" country-id="405" currency="170" currency-code="COP" decimals="2" format="" pending="0" symbol="$">80000000</amount>
        <card-mask>530371******8783</card-mask>
        <card-expiry>10/23</card-expiry>
        <card-name>Master Card</card-name>
        <psp-name>GlobalCollect</psp-name>
        <accept-url>https://hpp2.sit-01.cellpoint.dev/views/redirect_response.php</accept-url>
        <cancel-url>https://hpp2.sit-01.cellpoint.dev/views/redirect_response.php</cancel-url>
        <css-url>https://cpd-hpp2-devassests.s3.eu-central-1.amazonaws.com/10101</css-url>
        <logo-url>https://cpd-hpp2-devassests.s3.eu-central-1.amazonaws.com/10101/logo.png</logo-url>
        <google-analytics-id>GTM-WPHV68Z</google-analytics-id>
        <form-method />
        <auto-redirect>true</auto-redirect>
        <createdDate>2022-05-24</createdDate>
        <createdTime>11:27:53</createdTime>
        <status>
            <status-message id="3011" position="1">Pre Auth Success</status-message>
            <status-message id="2001" position="2">Payment captured by PSP</status-message>
        </status>
        <sign>e9e738e8e781c600de232d1b4bbcb640</sign>
        <client-info language="en" platform="spa" profileid="-1">
            <mobile country-id="405" operator-id="40500">9377178759</mobile>
            <email>[email protected]</email>
            <customer-ref>[email protected]</customer-ref>
            <device-id />
        </client-info>
        <additional-data>
            <param name="hmac">6146073de014b302c4d2f6b5a1cb81da4ace9fd166ed9bc62eb3b513b087c45a80c654952e8b2dd5ca0e141a0e4b04f0741f274a6f5ab9fde0fcf4701264979e</param>
            <param name="card-holder-name">Chris Harris</param>
            <param name="pre_auth_ext_id">6533916842106908704010</param>
            <param name="pre_auth_ext_status_code">100</param>
            <param name="Response_Code">800</param>
            <param name="hold_fee_amount">2300</param>
            <param name="hold_fee_currency_code">COP</param>
            <param name="platform">WEBB2C</param>
            <param name="_ga">2.168694248.833265534.1632121657-2073837615.1627877376</param>
            <param name="office_id">BOGAV08AK</param>
        </additional-data>
        <address>
            <first-name>Rohan</first-name>
            <last-name>Deo</last-name>
            <street>141/2 Andul test</street>
            <street2 />
            <postal-code>711103</postal-code>
            <city>Kolkata</city>
            <state>Maharastra</state>
            <country>
                <name>Colombia</name>
                <code>170</code>
                <alpha2code>CO</alpha2code>
                <alpha3code>COL</alpha3code>
            </country>
            <mobile idc="63">9898989898</mobile>
            <email>[email protected]</email>
        </address>
    </transaction>
    <transaction accoutid="101011" approval-code="654321" card-id="8" clientid="10101" extid="000000033710000442600000100001" id="5297501" language="en" mpoint-id="5297501" order-no="QLG763" payment-method-id="1" psp-id="21" session-id="533234" session-type="2" txn-type-id="1" walletid="-1">
        <amount conversationRate="1" country-id="405" currency="170" currency-code="COP" decimals="2" format="" pending="0" symbol="$">80000000</amount>
        <card-mask>451307******5348</card-mask>
        <card-expiry>10/23</card-expiry>
        <card-name>VISA</card-name>
        <psp-name>GlobalCollect</psp-name>
        <accept-url>https://hpp2.sit-01.cellpoint.dev/views/redirect_response.php</accept-url>
        <cancel-url>https://hpp2.sit-01.cellpoint.dev/views/redirect_response.php</cancel-url>
        <css-url>https://cpd-hpp2-devassests.s3.eu-central-1.amazonaws.com/10101</css-url>
mobile>
            <email>[email protected]</email>
        </address>
    </transaction>        <logo-url>https://cpd-hpp2-devassests.s3.eu-central-1.amazonaws.com/10101/logo.png</logo-url>
        <google-analytics-id>GTM-WPHV68Z</google-analytics-id>
        <form-method />
        <auto-redirect>true</auto-redirect>
        <createdDate>2022-05-24</createdDate>
        <createdTime>11:28:17</createdTime>
        <status>
            <status-message id="3011" position="1">Pre Auth Success</status-message>
            <status-message id="2001" position="2">Payment captured by PSP</status-message>
        </status>
        <sign>d3fb3b3156f825de5afd0b80047493ef</sign>
        <client-info language="en" platform="spa" profileid="-1">
            <mobile country-id="405" operator-id="40500">9377178759</mobile>
            <email>[email protected]</email>
            <customer-ref>[email protected]</customer-ref>
            <device-id />
        </client-info>
        <additional-data>
            <param name="hmac">6146073de014b302c4d2f6b5a1cb81da4ace9fd166ed9bc62eb3b513b087c45a80c654952e8b2dd5ca0e141a0e4b04f0741f274a6f5ab9fde0fcf4701264979e</param>
            <param name="card-holder-name">Chris Harris</param>
            <param name="pre_auth_ext_id">6533917086316951404009</param>
            <param name="pre_auth_ext_status_code">100</param>
            <param name="Response_Code">800</param>
            <param name="hold_fee_amount">2300</param>
            <param name="hold_fee_currency_code">COP</param>
            <param name="platform">WEBB2C</param>
            <param name="_ga">2.168694248.833265534.1632121657-2073837615.1627877376</param>
            <param name="office_id">BOGAV08AK</param>
        </additional-data>
        <address>
            <first-name>Rohan</first-name>
            <last-name>Deo</last-name>
            <street>141/2 Andul test</street>
            <street2 />
            <postal-code>711103</postal-code>
            <city>Kolkata</city>
            <state>Maharastra</state>
            <country>
                <name>Colombia</name>
                <code>170</code>
                <alpha2code>CO</alpha2code>
                <alpha3code>COL</alpha3code>
            </country>
            <mobile idc="63">9898989898</
    <transaction accoutid="101011" approval-code="" card-id="0" clientid="10101" extid="" id="5310635" language="gb" mpoint-id="5310635" order-no="" payment-method-id="1" psp-id="0" session-id="533234" session-type="2" txn-type-id="40" walletid="-1">
        <amount conversationRate="1" country-id="405" currency="170" currency-code="COP" decimals="2" format="" pending="0" symbol="$">0</amount>
        <card-name>System Record</card-name>
        <psp-name>System Record</psp-name>
        <accept-url />
        <cancel-url />
        <css-url>https://cpd-hpp2-devassests.s3.eu-central-1.amazonaws.com/10101</css-url>
        <logo-url>https://cpd-hpp2-devassests.s3.eu-central-1.amazonaws.com/10101/logo.png</logo-url>
        <google-analytics-id>GTM-WPHV68Z</google-analytics-id>
        <form-method />
        <auto-redirect>true</auto-redirect>
        <createdDate>2022-05-31</createdDate>
        <createdTime>10:26:48</createdTime>
        <status />
        <sign>d331679f5a42d4579bb375e6d5034ac7</sign>
        <client-info language="gb" platform="">
            <mobile country-id="0" operator-id="0" />
            <email />
            <customer-ref />
            <device-id />
        </client-info>
        <additional-data>
            <param name="hold_fee_amount">2300</param>
            <param name="hold_fee_currency_code">COP</param>
            <param name="platform">WEBB2C</param>
            <param name="_ga">2.168694248.833265534.1632121657-2073837615.1627877376</param>
            <param name="office_id">BOGAV08AK</param>
        </additional-data>
    </transaction>
    <transaction accoutid="101011" approval-code="" card-id="0" clientid="10101" extid="" id="5326993" language="gb" mpoint-id="5326993" order-no="" payment-method-id="1" psp-id="0" session-id="533234" session-type="2" txn-type-id="40" walletid="-1">
        <amount conversationRate="1" country-id="405" currency="170" currency-code="COP" decimals="2" format="" pending="0" symbol="$">0</amount>
        <card-name>System Record</card-name>
        <psp-name>System Record</psp-name>
        <accept-url />
        <cancel-url />
        <css-url>https://cpd-hpp2-devassests.s3.eu-central-1.amazonaws.com/10101</css-url>
        <logo-url>https://cpd-hpp2-devassests.s3.eu-central-1.amazonaws.com/10101/logo.png</logo-url>
        <google-analytics-id>GTM-WPHV68Z</google-analytics-id>
        <form-method />
        <auto-redirect>true</auto-redirect>
        <createdDate>2022-06-09</createdDate>
        <createdTime>20:17:34</createdTime>
        <status />
        <sign>0eddfdf2f525a316cc15846c42684b12</sign>
        <client-info language="gb" platform="">
            <mobile country-id="0" operator-id="0" />
            <email />
            <customer-ref />
            <device-id />
        </client-info>
        <additional-data>
            <param name="hold_fee_amount">2300</param>
            <param name="hold_fee_currency_code">COP</param>
            <param name="platform">WEBB2C</param>
            <param name="_ga">2.168694248.833265534.1632121657-2073837615.1627877376</param>
            <param name="office_id">BOGAV08AK</param>
        </additional-data>
    </transaction>
    <transaction accoutid="101011" approval-code="" card-id="0" clientid="10101" extid="" id="5388333" language="gb" mpoint-id="5388333" order-no="" payment-method-id="1" psp-id="0" session-id="533234" session-type="2" txn-type-id="40" walletid="-1">
        <amount conversationRate="1" country-id="405" currency="170" currency-code="COP" decimals="2" format="" pending="0" symbol="$">0</amount>
        <card-name>System Record</card-name>
        <psp-name>System Record</psp-name>
        <accept-url />
        <cancel-url />
        <css-url>https://cpd-hpp2-devassests.s3.eu-central-1.amazonaws.com/10101</css-url>
        <logo-url>https://cpd-hpp2-devassests.s3.eu-central-1.amazonaws.com/10101/logo.png</logo-url>
        <google-analytics-id>GTM-WPHV68Z</google-analytics-id>
        <form-method />
        <auto-redirect>true</auto-redirect>
        <createdDate>2022-07-11</createdDate>
        <createdTime>21:07:58</createdTime>
        <status />
        <sign>ef2023d31ff47087730d42c83992f3c3</sign>
        <client-info language="gb" platform="">
            <mobile country-id="0" operator-id="0" />
            <email />
            <customer-ref />
            <device-id />
        </client-info>
        <additional-data>
            <param name="hold_fee_amount">2300</param>
            <param name="hold_fee_currency_code">COP</param>
            <param name="platform">WEBB2C</param>
            <param name="_ga">2.168694248.833265534.1632121657-2073837615.1627877376</param>
            <param name="office_id">BOGAV08AK</param>
        </additional-data>
    </transaction>
</root>

14.Refund or Void Transaction

You can use the refund transaction API to refund a transaction to a customer. The refund is based on the amount you provide. You can provide a partial or complete refund.

If you do not specify an amount, a customer receives the complete refund. Velocity exposes an API to cancel an authorized transaction or refund a captured transaction based on the status of the transaction. The Amount field can take values equal to or less that the captured or authorized amount.

Path NamePath Details
End Point[Velocity URL]/mpoint/ refund
Format/Content Typetext/xml
AuthenticationHTTP basic access authentication

14.1 Request

The following is an example of a Refund Transaction request:

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <refund client-id = "[integer]">
      <transaction order-no="XCDFGG" id="1859798">
        <amount country-id="200">14000</amount>
        <external_claim_reference>ABCD1234</external_claim_reference>
      </transaction>
      <source>API</source>
  </refund>
</root>

14.2 Response

The following is an example of a Refund Transaction response:

Note: If the status code is 1000, the refund is successful. Other rest response codes indicate a failure. Refer to Refund Payment codes for details.

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <status code="1000"> [message] <status/>
</root>

OR

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <status code="9400">
	<!--For Exceptions-->
        <exception type="http">
            <code>400</code>
        </exception>
    </status>
</root>

14.Refund or Void Transaction

You can use the refund transaction API to refund a transaction to a customer. The refund is based on the amount you provide. You can provide a partial or complete refund.

If you do not specify an amount, a customer receives the complete refund. Velocity exposes an API to cancel an authorized transaction or refund a captured transaction based on the status of the transaction. The Amount field can take values equal to or less that the captured or authorized amount.

Path NamePath Details
End Point[Velocity URL]/mpoint/ refund
Format/Content Typetext/xml
AuthenticationHTTP basic access authentication

14.1 Request

The following is an example of a Refund Transaction request:

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <refund client-id = "[integer]">
      <transaction order-no="XCDFGG" id="1859798">
        <amount country-id="200">14000</amount>
      </transaction>
  </refund>
</root>

The parameters are listed and defined in the table below.

ParameterTypeDescription
external_claim_referenceStringThe External Claim Reference number for refund request. Optional. Maximum length – 20 characters.
sourceStringThe source of refund request. Optional. Maximum length – 20 characters.

14.2 Response

The following is an example of a Refund Transaction response:

Note: If the status code is 1000, the refund is successful. Other rest response codes indicate a failure. Refer to Refund Payment codes for details.

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <status code="1000"> [message] <status/>
</root>

OR

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <status code="9400">
	<!--For Exceptions-->
        <exception type="http">
            <code>400</code>
        </exception>
    </status>
</root>

15.Callback Request to Merchant Server from Velocity

After Velocity completes processing a transaction, the customers know if their payment was processed. The callback request informs you about the payment status as an HTTP POST. This is an asynchronous message in a separate HTTP transaction initiated from Velocity. It is in addition to the original synchronous response to the payment request and the user redirect to confirmation page.

The following is an example of a callback request:

mpoint-id=8068110&office-id=PHPNMA&ep-number=PM10004843&invoice-no=2CQQJKMT050320180&issuer-approval-code=007283&fraud_status_code=3014&fraud_status_desc=Pre+Auth+Review&pre_auth_ext_id=5900006009536418604009&pre_auth_ext_status_code=105&post_auth_ext_id=6163976912096333904010&post_auth_ext_status_code=ACCEPT&txn-status=A&card-holder-name=Primary Mastercard Card&orderid=NL4PJN&status=2001&desc=Payment+captured+by+PSP&exchange_rate=1&amount=358700&fee=0&currency=CNY&decimals=2&sale_amount=358700&sale_currency=CNY&sale_decimals=2&mobile=22532290&operator=13600&language=us&card-id=7&card-number=557781%2A%2A%2A%2A%2A%2A0004&pspid=1951911&device-id=12ABC&psp-name=2c2p-alc&description=Captured&hmac=bac9357b196c4cf17cede735ba68c75aee98dc17&email=email%40example.name&expiry=2023-01&session-id=106800&customer-country-id=200&approval-code=360020&payment-method=CD&payment-type=1&invoice-no=2CQQJKMT050320180&date-time=2020-04-06T08:33:28+00:00&local-date-time=2020-04-06T16:33:28+08:00&issuing-bank=sbi&billing_first_name=Abc&billing_last_name=xyz&billing_street_address=Barshinger+Avenue&billing_city=New+York&billing_country=640&billing_state=Agusan+del+Norte&billing_postal_code=212435&billing_email=data%40test.com&billing_mobile=2147483647&billing_idc=200&service_type_id=11&session-type-id=1

The following is a refund callback sample:

mpoint-id=1234556&orderid=TESTID&status=2003&desc=Payment+Refunded&exchange_rate=1&amount=12345&currency=PHP&decimals=2&sale_amount=12345&sale_currency=PHP&sale_decimals=2&fee=0&mobile=987654321&operator=64000&language=en&card-id=8&card-number=444444%2A%2A%2A%2A%2A%2A4444&pspid=4321&psp-name=FIRST+DATA&hmac=23a91b25d76903b4228631854db66af3c773413834e27943646551260acd21929&email=test%40test.com&expiry=2022-05&session-id=5432&session-type-id=1&approval-code=1234&payment-method=CD&payment-type=1&payment-provider-id=62&cfx_status_code=115&pre_auth_ext_status_code=105&merchant=6160800539&issuer-approval-code=1234&session_token=testToken&hold_fee_amount=333&hold_fee_currency_code=608&hold_period=480&fraud_status_code=3117&fraud_status_desc=Post+Auth+Screen+Skip+-+Business+Rules&date-time=2021-11-18T23:59:30+00:00&local-date-time=2021-11-19T07:59:30+08:00&billing_first_name=TEST+USER+NAME&billing_last_name=TEST&billing_street_address=TEST+ADDRESS&billing_city=TEST&billing_country=640&billing_state=Metro+Manila&billing_postal_code=1421&billing_email=TEST%40TEST.com&billing_mobile=987654321&billing_idc=63&first_departure_time=2021-11-21 22:00:00&first_departure_time_zone=+08:00&pos=640&ip_address=111.111.111.111,2021-11-19 00:03:14.567,2021-11-19 00:03:14.345

The callback response parameters are listed and defined in the table below.

ParameterTypeDescription
mpoint-idIntegerVelocity’s unique ID for the payment transaction.
payment-methodStringThe type of method used for payment. For example, card, APM, or wallet.
payment-typeStringThe type of payment. For example, card, APM, or wallet.
payment-provider-idintegerA unique identification of the payment provider.
short-codeintegerAn SMS short code if opted for SMS notification.
orderidintegerThe order ID the merchant provides when a transaction is initiated.
statusIntegerAn integer code indicating the status of the transaction; the values can be either 0 or 1. Refer to the Transaction Status Codes for details.
amountIntegerTotal amount that the customer was charged for the payment transaction in a country’s smallest currency.
Note: If you have subscribed to FX, this field contains the converted amount.
currencyStringThe currency in which the customer was charged.
Note: If you are availing FX, this field contains the converted currency.
mobileStringMSISDN of the customer without an International Dialling Code.
operatorintegerThe ID of a customer’s Mobile Network Operator.
A typical value is “country id” multiplied by 100.
descStringThe description of the transaction status and it depends on the status ID. For example, payment captured or payment rejected.
feeStringThe fee that you charge from a customer.
emailStringThe email address of a customer. If your customer provides this parameter, the Email input field on the Send E-Mail Receipt page is automatically prepopulated with this value.
card-idStringThe card ID to identify the card type. For example, Mastercard or Visa.

HMAC

String

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

ParameterRequired
clientidYes
orderidYes
amountYes
countryYes
mobileConditional
mobile-countryConditional
emailConditional
deviceidConditional
saltYes


Using the MAC calculation secures the information sent by the merchant to Velocity by applying the SHA-512 encryption algorithm on key parts of the information sent to protect against tampering. The tifica is the merchant's shared secret used to ensure that the provided MAC is unique.
date-timeStringThe date and time when the transaction takes place
local-date-timeStringThe local time and date when the transaction takes place
approval-codeStringThe unique ID that a PSP provides for a transaction.
session-idStringThe session ID that Velocity sends as a callback request.
wallet-idStringThe ID of the wallet used.
payment-typeStringThe type of payment. For example, card, wallet, or APM.
pspidStringID of the transaction at PSP or ACQ. This varies in every transaction.
psp-nameStringThe name of the PSP or ACQ used for completing the transaction. For example, 2C2P, 2C2P-ALC, GlobalPayment, Worldpay, or ChasePayment.
office-idintegerThe office ID received from approver.
ep-numberintegerThe number received from PSP.
invoice-noStringThe invoice number of a transaction.
issuer-approval-codeAlpha numeric stringThe code issued by an approver.
txn-statusIntegerThe status of a transaction.
card-holder-nameStringThe name of a card holder.
orderidIntegerThe order identification number of a transaction.
errorcodeIntegerAn integer code indicating the error status of the transaction.
customer-country-idIntegerThe country ID of a mobile.
device-idStringThe device ID of the customer.
card-numberStringThe masked card number if present for a transaction.
expiryStringThe card expiry date (YYYY-MM) if present for the transaction.
languageStringDefault language encoding set during client onboarding.
descriptionStringThe transaction description as provided during payment initiation.
issuing-bankStringThe issuing bank name for payment transactions done through online banking payment option.
decimalsIntegerThe currency precision; for example, 2 for USD for the currency parameter. If you subscribe to FX, this field contains the converted currency in decimals.
sale_currencyIntegerThis is the checkout or sale currency.
If you do not subscribe to FX, the sale currency has the same value as that of the currency parameter.
sale_amountIntegerThis is the checkout or sale amount. If you do not subscribe to FX services, the same amount will have the same value as that of the amount parameter.
exchange_rateIntegerThe conversion rate given by FX. If you do not subscribe to FX, the value of this field is 1.
fraud_status_codeIntegerThe final fraud status code. For example, 3011 or 3111.
fraud_status_descStringFinal fraud status description. For example, Accepted or Review
pre_auth_ext_status_codeIntegerThe pre-auth fraud check system response code.
pre_auth_ext_idIntegerThe pre-auth fraud check system transaction ID.
post_auth_ext_idIntegerPost-auth fraud check system transaction ID.
post_auth_ext_status_codeStringThe post-auth fraud check system response code.
billing_first_nameStringThe cardholder's billing address first name.
billing_last_nameStringThe cardholder's billing address last name.
billing_street_addressStringThe cardholder's billing address street address.
billing_cityStringThe cardholder's billing address city name.
billing_countryIntegerThe cardholder's billing address country ID.
billing_stateStringThe cardholder billing address state/region value.
billing_postal_codeintegerThe cardholder's billing address zip code.
billing_emailStringThe card holder's email address.
integerIntegerThe card holder's mobile number.
billing_idcIntegerThe card holder's mobile dialling country code.
service_type_idIntegerA value to indicate the type of exchange services used for a transaction. The ID indicates if FX such as DCC, MCP, and PCC are opted. The ID is a two-digit number XY in which:
  • X - Represents the type of exchange service used in a transaction.

  • Y - Represents the exchange usedꟷ it can be opt-in or opt-out.

The following table shows the possible values of exchange service ID:


ID (XY)Service (X)Opted
11 DCCOpted
12 DCCNot opted
21 MCPOpted
22 MCPNot opted
31 External MCPOpted
32 External MCPNot opted
41 PCCOpted
42 PCCNot opted
StringIf the PSP sends additional data related to transaction, mPoint sends it in callback. For example, ep-number and office-id are additional information sent by 2c2p-ALC.
session-type-idIntegerThe session type ID in which:
  • 1= normal payment
  • 2= split payment
posIntegerPoint of sale of transaction. For example, countryid - ISO numeric.
ip_addressStringThe IP address of the transaction initiation

16.Frequently Asked Questions

Q: How can I save the profiles of customers?

A: Use the /mpoint/save-account API to create a new customer profile during sign-up or log in. The profile can be linked to any CRM system for authentication.

Q: How can I save the credit cards of customers?

A: Use the /mpoint/save-card API to store customer card details securely.

Q: How can I get the Client ID and Account ID?

A: CPD shares the client ID and account ID after the client configuration is completed.

Q: What is the use of pay service?

A: The Pay API call is required to identify the payment methods and to capture the appropriate payment details from the user. For instance, in the case of APMs and Wallets a customer may be redirected to complete payment in-app or by opening a web view.

Q: Can I support delayed captures, that is, authorize first and capture later?

A: If the auto-capture option is set to false in the client configuration, /mPoint/capture-payment, the API call enables capturing an authorized transaction. The capture API call can be made immediately or after a delay. A merchant can choose to make the capture calls offline after a delay or in a batch mode during off-peak hours.

Q: Our flow is to ask a customer to add a card before the journey. We would therefore need a card verification service.

A: This feature is dependent on acquirer services. You can get in touch with our support team for details.

Q: What is the use of callback URL as arguments in the API, when the service is synchronous?

A: The authorization response is a synchronous service response, while callback is an asynchronously triggered B2B call. CPD recommends using the callback as a trigger for releasing the ticket. The synchronous auth response has a risk of being timed out at the merchant's end. The callback helps to process any asynchronous processing, if required. The callback can also send a few additional parameters that can be used by retail system such as masked card number or status code. The callback is received for key transaction states such as authorize, capture, refund, and cancel operations.

17.Description of Parameters

The parameters are listed and defined in the table below.

ParameterTypeDescription
accountIntegerThe unique ID associated with a payment transaction. It is optional. If you omit this parameter, the payment transaction is associated with the default sub-account.
client-idIntegerThe unique ID configured for a merchant on the Velocity POP.
auth-tokenStringA unique token sent to the specified auth-url to authenticate customers when they pay with a stored card and use single sign-on.
operator-idIntegerThe ID of a customer’s mobile network operator. CPD recommends including this parameter in a request to ensure that Velocity interacts with the operator accurately.
country-idIntegerThe CPD-specific country code, which is made available to merchants on request.
emailStringThe email address of a customer.
customer-refStringThe unique reference ID given by a merchant for a customer. Velocity uses this token to identify a user. The customer reference is included in the request to a specified auth-URL to identify customers when they:

  • Pay with a stored card through the mVault
  • Use single sign-on.


Note: Customer-ref can be mandatory or optional, based on the requirement of a merchant or a PSP.
type-idIntegerA type of card.
country-idIntegerThe CPD-specific country code, which is made available to merchants on request.
card-holder-nameStringThe name of a card holder.
card-numberStringThe card number used for transaction.
expiry-monthStringThe date on which a card expires.
expiry-yearStringThe year in which a card expires.
languageStringThe language that Velocity uses as default when translating the payment pages.
Note: Velocity language codes are based upon the ISO- 639-1 standard.
Refer to https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for details.
versionStringThe version of the API or application that send the request.
card-holder-nameStringThe name of a card holder.
card-numberStringThe card number used for transaction.
expiry-monthStringThe date on which a card expires.

18 Status Codes

18.1 General Codes

CodeCategoryTypeDescription
1001PaymentPayment Initialized with VelocityThe payment transaction is created in the Velocity database.
1009PaymentPayment Initialized with PSPThe payment processor responsible for authorizing the payment has been initialized.
1991CallbackMerchant Callback ConstructedThe callback to the merchant application sent to callback-url has been constructed.
1992CallbackCallback ConnectedThe connection with the merchant callback URL is established.
1993CallbackCallback Connection FailedThe connection with the merchant callback URL failed.
1990CallbackCallback AcceptedThe merchant system returned an HTTP 200 OK and received the callback.
1995CallbackCallback RejectedThe merchant system returned an HTTP $XX/5XX Error and rejected the callback.
2000PaymentAuthorizedThe payment has been authorized successfully by the PSP.
2002PaymentCancelledThe authorized payment has been cancelled successfully by the PSP.
2003PaymentRefundedThe captured payment refunded successfully (full / partial) by the PSP. The manual operation / delayed refund - pending states, initiated.
2008PaymentPayment via StoredInitialized payment with a stored card.
2009PaymentAuthorized and Card StoredThe payment has been authorized successfully by the PSP and the card stored on a successful authorization.
2001PaymentCapturedThe payment has been captured successfully by the PSP initiated for refund.
2010PaymentRejectedThe payment was rejected by the PSP or Acquirer need more granular states - message tbl front end can continue handling the generic state.
CodeCatagoryTypeDescription
20109PaymentRejected sub state on timeoutIssuer down time; SDK returns this to the Velocity core.
20108PaymentRejected sub state on timeoutPSP down time; SDK returns this to the Velocity core.
2011refund PaymentDeclinedThe payment was declined by the PSP / Acquirer while performing capture, refund, or cancel.
No Vision impact; however, all declines have common state 2011.
4020SessionSession FailedThe session failed or declined. One or more transactions in the session failed.
4021SessionSession FailedThe session failed (maximum attempt exceeds). One or more transaction attempts failed.
4030SessionSession CompleteThe session completed successfully. The transactions in the session are complete and successful.
4031SessionSession PartialThe session was partially completed. One or more transactions in the session were incomplete.

Additional codes.

CodeDescription
0Payment not made.
200Request validated and accepted by back end.
400Request rejected by back end because of validation error.
401Authentication required.
403Access denied.
415Message transmitted in an unknown format or by using an unsupported content type.
500Velocity server error.
502PSP returned an unknown error.
504A timeout occurred while communicating with the PSP.
1003Card expired.
1005Invalid card number.
1011Invalid card name.
1012Invalid card address.
1013Invalid card date of birth.
1014Card is inactive.
2007Payment processed.
2019Payment duplicated.
2084Card not found.
4030Payment success.
40031Partial payment success.

18.2 Initialize Payment

The following table provides information about the codes that you can receive after you initialize a payment.

CodeDescription
1Undefined client ID
1Client ID / Account does not match.
2Invalid client ID
3Unknown client ID
4Client disabled
11Undefined account
12Invalid account
13Unknown account
14Account disabled
53Amount is more than pending amount.
400Wrong operation: initialize.
401Authentication required.
401Authorization required.
401Username / Password doesn't match.
415Invalid XML Document.
CodeDescription
1002Internal database error - Unable to create a new Transaction.
Contact [email protected]
1003Internal database error - Unable to insert new message for Transaction.
Contact [email protected]
1004Internal database error - Unable to update Transaction.
Contact [email protected]
4021Payment failed: You have exceeded the maximum number of attempts.
4039Payment session is already completed.

18.3 Authorize Payment

The following table provides information about the codes that you can receive after you authorize a payment.

Code Description
1Undefined client ID
1Client ID / Account does not match.
2Invalid client ID
3Unknown client ID
4Client disabled
11Undefined account
12Invalid account
13Unknown account
14Account disabled
24The selected payment card is not available.
26Undefined password.
27 Password is too short; min length is 6 characters.
28Password is too long; max length is 50 characters.
29Password contains invalid characters or
31 Authentication failed.
32Authentication failed – Next invalid attempt will delete the account.
33Authentication failed – Account deleted.
34Authentication rejected by the single sign-on server.
35User account not found.
36A timeout occurred while communicating with the single sign-on server.
37Mobile number not verified.
38Unable to perform single sign-on due to invalid Security Token or Authentication URL.
39User account disabled.
41Undefined card ID.
42ID for the stored card is too small, min value is 1.
43Stored card not found.
43Insufficient balance on voucher.
44Stored card disabled.
45Voucher and Redeem device-ids not equal.
48Voucher payment temporarily locked.
51Insufficient balance on e-money account.
52Insufficient balance on loyalty account.
52Amount is more than pending amount.
53Authorization type not supported for the transaction.
59An unknown error occurred while retrieving payment data from 3rd party wallet. Card has been blocked.
79An unknown error occurred while retrieving payment data from third-party wallet. Card has been blocked.
90The connection timed out while authorizing the payment with the PSP.
92Authorization rejected by PSP / Acquirer.
92Payment rejected by invoice issuer
99Unknown PSP / Acquirer.
99The given request combination is not configured for the client.
99Invoice payment not configured for client.
100Payment authorized using a stored card.
100Payment authorized using Invoice
100Payment Authorized using stored card.
101Payment authorized using e-money account.
102Payment authorized using loyalty account.
103Authorization already in progress.
400Wrong operation: authorization.
401Authentication required.
401Authorization required.
401Username / Password doesn't match.
404Transaction with ID:.
415Invalid XML Document.
1002Internal database error - Unable to create a new Transaction. Contact [email protected]
1003Internal database error - Unable to insert new message for Transaction. Contact [email protected]
1004Internal database error - Unable to update Transaction.
Contact [email protected]
2000Payment authorized.
2009Payment authorized and card stored.
2010Authorization Declined or Rejected

18.4 Capture Payment

CodeDescription
1Client ID / Account does not match.
400Invalid request.
400Wrong operation: capture.
401Authorization required.
401Username / Password does not match.
415Invalid XML Document.
500Internal Error.
997Capture not supported.
998Network error.
999Declined.
1000Transaction captured successfully.
1000Success.

18.5 Refund Payment

CodeDescription
1Client ID / Account does not match.
51The amount is undefined.
52The amount is too small.
53The amount greater than the authorized amount.
177Order already refunded.
400Wrong operation: refund.
401Authorization required.
401Username / Password does not match.
415Invalid XML Document.
998Network error.
999Declined.
1000Transaction refunded successfully.
1001Transaction cancelled successfully.
1100Refund Initiated.
9400Invalid request.
9502Bad gateway.
9500Internal sever error.

19. Appendix

19.1 Processor Type

IDProcessor Type
1PSP
3Wallet
4APM
2Acquirer
5Virtual
6Merchant Plug-in
7Gateway
8Tokenize
9Fraud Gateway
10Post Auth Fraud Gateway
11Voucher and Credit

19.2 Card

IDCard
10SMS
12Switch
13Solo
14Delta
1American Express
2Dankort
3Diners Club
4EuroCard
5JCB
6Maestro
7Master Card
8VISA
9VISA Electron
18Cartebleue
19Postepay VISA
20Postepay Mastercard
22Discover
24Invoice
16VISA Checkout
17MobilePay
27Android Pay
25AMEX Express Checkout
23Master Pass
15Apple Pay
28Paypal
31SADAD
32AliPay
34POLi
35mVault
11My Account
39WeChat Pay
40AliPay Chinese
41Google Pay
70BENEFIT
69KNet
21UATP
72SADAD v2
87OMANNET
71MADA
94GrabPay
36Klarna
42PPRO
92SWISH
93GCash
95PayMaya
73FPX
26TravelFund
47Dragonpay
88DRAGONPAYOFFLINE
96Payment Center Offline
63SafetyPay
97PSE
99Efecty
100Banco de Bogata
98Via Baloto
82ELO
45Bancontact
50EPS
52giropay
53Ideal
61Przelewy24
66Sofort
86Mobile Money
67UnionPay
101UnionPay Card
102Agency Credit

19.3 Card State

IDCard State
1Enabled
2Disabled By Merchant
3Disabled By PSP
4Prerequisite not Met
5Temporarily Unavailable
6Disable Show

19.4 Country

IDCountry
103UK
338Libyan Arab Jamahiriya
410Central African Republic
502Cook Islands
100Denmark
616Japan
415Netherlands Antilles
422South Georgia and IS
423British International Ocean Territory
135Latvia
622Macao
425St. Lucia
145St. Pierre and Miquelon
401Aruba
436St. Maarten
440St. Vincent and The Grenadines
507Cocos (Keeling) Islands
647United Arab Emirates
600Abu Dhabi
602Dubai
629Kerguelen Archipelago
307Burundi
122Bulgaria
304Bolivia
650Kiribati
511Kiribati
146Palestinian Territory
516Tuvalu
409French Departments and Territories in the Indian Ocean
120Belarus
109Switzerland
404Chile
609China
315Democratic Republic of the Congo
405Colombia
309Cape Verde
406Costa Rica
208Cuba
124Cyprus
125Czech Republic
115Germany
316Djibouti
417Scott Base
317Egypt
337Eritrea
113Spain
126Estonia
319Ethiopia
104Finland
504Fiji
416Falkland Islands
108France
127Faroe Islands
128Georgia
210Guadeloupe
105Greece
130Greenland
421French Guiana
133Ireland
107Italy
136Liechtenstein
137Lithuania
138Luxembourg
141Monaco
139Malta
142Montenegro
426Martinique
339Mayotte
110Netherlands
343Reunion
151San Marino
335Tristan Da Cunha
152Slovakia
153Slovenia
156Vatican City State
430Pitcairn Island
312Comoros
322Ghana
129Gibraltar
323Guinea
321Gambia
410Guatemala
411Guyana
614Hong Kong
412Honduras
123Croatia
131Hungary
505Indonesia
603India
615Iran
628Iraq
132Iceland
106Israel
617Jordan
325Kenya
617Cambodia
604Kuwait
620Lao P.D.R.
621Lebanon
327Liberia
634Sri Lanka
326Lesotho
333Morocco
636Macau
140Moldova
328Madagascar
623Maldives
201Mexico
143Republic of Macedonia
624Mongolia
334Mozambique
331Mauritania
332Mauritius
329Malawi
638Malaysia
340Namibia
427Nicaragua
629Nepal
513New Zealand
610pakistan
606Qatar
607Russia
344Rwanda
150Republic of Serbia
216Johnston Island
217Midway Island
218United States Minor Outlying Islands
442Virgin Islands, United States
510Norfolk Island
626Diego Garcia
308Cameroon
407Ecuador
506Micronesia
211Haiti
635Marshall Islands
342Nigeria
515Niue
102Norway
605Oman
428Panama
429Peru
640Philippines
641Palau
112Poland
147Portugal
432Paraguay
149Romania
608Saudi-Arabia
346Sudan
642Singapore
348Sierra Leone
347St. Helena
408El Salvador
434Somalia
349Sao Tome and Principe
435Suriname
101Sweden
350Swaziland
345Seychelles
643Syrian Arab Republic
311Chad
644Thailand
645Turkmenistan
515Tonga
352Tunisia
154Turkey
353Tanzania
354Uganda
155Ukraine
439Uruguay
200USA
648Uzbekistan
441Venezuela
517Vanuatu
519Samoa
358Zimbabwe
144Monserrat
357Zaire
414Carriacou
424St. Christopher (St. Kitts) Nevis
303Benin
306Burkina Faso
314Côte d'Ivoire
313Congo
320Gabon
324Guinea-Bissau
318Equatorial Guinea
330Mali
509New Caledonia
341Niger
504French Polynesia
433Senegal
351Togo
518Wallis and Futuna Islands
650Yemen
355South Africa
356Zambia
161Åland Islands
445French Southern Territories
456Heard and McDonald Islands
652Tajikistan
520Timor-Leste
521Tokelau
219Saint Barthelemy
443Bonaire, Saint Eustatius and Saba
444Curacao
159Guernsey
158Svalbard and Jan Mayen Islands
160Jersey
220Saint Martin
111Belgium
114Austria
116Afghanistan
117Albania
118Andorra
119Armenia
121Bosnia and Herzegovina
300Algeria
301Angola
302Bangladesh
305Botswana
400Argentina
402Belize
403Brazil
500Australia
501Brunei Darussalam
514Solomon Islands
601Bahrain
611Azerbaijan
612Bhutan
134Isle of Man
202Canada
203Anguilla
204Antigua and Barbuda
205Barbados
206British Virgin Islands
207Cayman Islands
209Dominican Republic
212Jamaica
213American Samoa
214Bermuda
215Bahamas
336Western Sahara
413Antarctica
418Dominica
420Grenada
431Puerto Rico
437Turks and Caicos Islands
438Trinidad and Tobago
508Christmas Island
618Kazakhstan
359South Sudan
619Kyrgyzstan
627Guam
637Northern Mariana Islands
646Taiwan
651Papua New Guinea
653Myanmar
416Bouvet Island
649Vietnam
148Kosovo
633Kazakhstan
632South Korea
631North Korea
625Burma

19.5 Currency

IDCurrency
12Algerian Dinar
44Bahamian Dollar
64Ngultrum
68Boliviano
72Pula
84Belize Dollar
116Riel
124Canadian Dollar
132Cabo Verde Escudo
136Cayman Islands Dollar
144Sri Lanka Rupee
152Chilean Peso
15Yuan Renminbi
170Colombian Peso
174Comorian Franc
188Costa Rican Colon
191Kuna
192Cuban Peso
203Czech Koruna
214Dominican Peso
222El Salvador Colon
230Ethiopian Birr
232Nakfa
238Falkland Islands Pound
242Fiji Dollar
262Djibouti Franc
270Dalasi
292Gibraltar Pound
320Quetzal
324Guinean Franc
328Guyana Dollar
332Gourde
340Lempira
344Hong Kong Dollar
348Forint
352Iceland Krona
356Indian Rupee
360Rupiah
364Iranian Rial
368Iraqi Dinar
376New Israeli Sheqel
388Jamaican Dollar
398Tenge
400Jordanian Dinar
404Kenyan Shilling
408North Korean Won
414Kuwaiti Dinar
417Som
418Lao Kip
422Lebanese Pound
426Loti
430Liberian Dollar
434Libyan Dinar
454Malawi Kwacha
458Malaysian Ringgit
462Rufiyaa
478Ouguiya
480Mauritius Rupee
484Mexican Peso
496Tugrik
498Moldovan Leu
504Moroccan Dirham
512Rial Omani
516Namibia Dollar
524Nepalese Rupee
558Cordoba Oro
566Naira
578Norwegian Krone
586Pakistan Rupee
590Balboa
600Guarani
604Sol
608Philippine Peso
634Qatari Rial
643Russian Ruble
646Rwanda Franc
654Saint Helena Pound
678Dobra
682Saudi Riyal
694Leone
702Singapore Dollar
704Dong
706Somali Shilling
748Lilangeni
752Swedish Krona
756Swiss Franc
780Trinidad and Tobago Dollar
807Denar
818Egyptian Pound
901New Taiwan Dollar
933Belarusian Ruble
936Ghana Cedi
938Sudanese Pound
941Serbian Dinar
943Mozambique Metical
946Romanian Leu
8Lek
32Argentine Peso
36Australian Dollar
48Bahraini Dinar
50Taka
51Armenian Dram
52Barbados Dollar
60Bermudian Dollar
90Solomon Islands Dollar
96Brunei Dollar
104Kyat
108Burundi Franc
392Yen
446Pataca
532Netherlands Antillean Guilder
533Aruban Florin
554New Zealand Dollar
598Kina
728South Sudanese Pound
784UAE Dirham
931Peso Convertible
932Zimbabwe Dollar
944Azerbaijan Manat
950CFA Franc BEAC
960SDR (Special Drawing Right)
968Surinam Dollar
969Malagasy Ariary
971Afghani
972Somoni
973Kwanza
975Bulgarian Lev
940Uruguay Peso en Unidades Indexadas (URUIURUI)
976Congolese Franc
977Convertible Mark
981Lari
947WIR Euro
985Zloty
990Unidad de Fomento
994Sucre
997US Dollar (Next day)
965ADB Unit of Account
970Unidad de Valor Real
979Mexican Unidad de Inversion (UDI)
978Euro
208Danish Krone
984Mvdol
1No Specific Currency
826Pound Sterling
948WIR Franc
890US Dollar
410Won
548Vatu
690Seychelles Rupee
710Rand
760Syrian Pound
764Baht
776Pa’anga
788Tunisian Dinar
800Uganda Shilling
834Tanzanian Shilling
858Peso Uruguayo
860Uzbekistan Sum
882Tala
886Yemeni Rial
934Turkmenistan New Manat
937Bolívar
949Turkish Lira
951East Caribbean Dollar
952CFA Franc BCEAO
953CFP Franc
967Zambian Kwacha
980Hryvnia
986Brazilian Real

19.6 Payment Type

IDPayment Type
1Card
3Wallet
4APM
5Card Token
6Virtual
7Online Banking
8Offline Payment
2Voucher and Credit

19.7 Product Type

IDProduct Type
100Ticket
200Ancillary
210Insurance

19.8 PSP

IDPSP
1CellPoint Mobile
2DIBS - Custom Pages
3IHI
4WorldPay
5PayEx
6Authorize.Net
7WannaFind
8NetAxept
9CPG
11MobilePay
13VISA Checkout
14Apple Pay
15Master Pass
16AMEX Express Checkout
17Data Cash
18Wire Card
20Android Pay
21GlobalCollect
22Velocity
23PayFort
25CCAvenue
262C2P
27MayBank
28PublicBank
30AliPay
32POLi
36mVault
43AliPay - Chinese
49UATP
50UATP Card Account
44Google Pay
52Chase Payment
48CHUBB
45Amex
47MODIRUM MPI
54Cielo
56Global Payments
57MADA MPGS
65CEBU-RMFSS
60EZY Fraud Gateway
59VeriTrans4G
51eGHL
38Paytabs
46PPRO
62FIRST DATA
63CyberSource
41Citcon
42NETS MPI
37Klarna
66SWISH
61DragonPay
19DSB
76Agency Credit
58CELLULANT
78Reach
12Adyen
70SafetyPay
73paymaya acq
74nmi
24PayPal
402c2p-alc
67GrabPay
68PayMaya
69Payment Center
71CEBU Travel Fund
72MPGS
53PayU
10Stripe
64CyberSource Fraud Gateway
75AUB

19.9 Session Type

IDSession Type
1Full Payment Session
2Split Payment Session

19.10 TXN Type

IDTXN Type
10Call Centre Purchase
11Call Centre Subscription
20SMS Purchase
21SMS Subscription
30Web Purchase
31Web Subscription
100Top-Up Purchase
101Top-Up Subscription
1000E-Money Top-Up
1001E-Money Purchase
1002E-Money Transfer
1003E-Money Withdrawal
1009Card Purchase
40Mobile App. Purchase
41Mobile App. Subscription
102Points Top-Up Purchase
1004Points Top-Up
1005Points Purchase
1007Points Reward
10091New Card Purchase
1Shopping Online
2Shopping Offline
3Self Service Online
4Self Service Offline
5Self Service Online with additional rules on FOP
6Payment Link Transaction
7Telephone Order
8Mail Order

19.11 Supported tax_id_type

19.11.1 PSE

The following document types and corresponding tax_id_type are supported for PSE:

Document TypeSupported tax_id_type
Citizenship CardCC
Foreign Citizenship CardCE
Tax Identification NumberTI
Identity CardIDC
PassportPP
Birth CertificateRC
Foreign Identification DocumentDE

Updated 7 months ago