You can invoke the Initialize Payment operation 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.

Resource Endpoint

Path Name	Path Details
Endpoint	`[VELOCITY URL]/mpoint/initialize-payment`
Request Method	POST
Format/Content Type	text/xml
Authentication	HTTP basic access authentication

Request

Sample 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 value is sent back in the initialize request with the full amount. A split abandoned payment happens when a customer starts a fresh transaction and leaves a current split payment.
Note: Merchants from specific domains, such as airlines or rail, may want to display booking information to customers after they make payment; for example, ticket details along with the address of a customer.

Request Parameters

Request parameters are listed and defined in the tables below.

Initializing Payments Parameters

Parameter	Type	Required	Description
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

Parameter	Type	Required	Description
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 transaction types found in the 'Transaction Types' table, below.
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	These are the additional fees if applicable for the transaction. For example, specific scenarios like administrative fee for offline payment or pay later. If the transaction amount is $120.30, then the field contains value `12030`. Note: The `fee` value 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. This is available in Reference.
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 Exchange Service ID table shows the possible values of exchange service ID.
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 input fields in the order listed in the Message Authentication Code table. 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.
orders	Object	No	Order details such as the following: 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 Airline Data Requirements.
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. Example: `<additional-data>` `<param name="merchant_payment_ref">12091201291</param>` `</additional-data>`

Transaction Types

Velocity supports the following transaction types (used in type-id):

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.

Merchant information parameters

Parameter	Type	Required	Description
client-info	Object	Yes	An object of client information, containing 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 sends 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 to http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for details.
mobile	Integer	No	The MSISDN of a customer without International Dialing 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.

Response

The Initialize Payment response from the Velocity server is described below. The response contains information about the transaction such as transaction ID and amount, along with the configured payment methods or card types. Merchants must use this operation when a customer makes a purchase.

The initialize payment response can be divided into the following parts:

Merchant configuration
Transaction information
Card information

Card Payment Response

The following is an example of the response that the Velocity server sends to a merchant’s customer for a card payment:

<?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>
		</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>

Wallet Response

The following is an example of a response for 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"/>
			<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)"/>
		</body>
	</card>
</wallets>

Apple Pay Response

The following is an example of a response for 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>

Offline Response

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

<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/>
	</card>
</offline>

Aggregator Response

The following is a sample response for a payment via an 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>
	</card>
</aggregators>

APM Response

The following is an example of a response for a payment using an 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>
	</card>
</apms>

Vouchers Response

The following is a sample response for a payment using a voucher:

<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>
	</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>
	</card>
</vouchers>

📘
Airline Itinerary Data
Note: For AID parameters description, refer to the Airline Data Requirements section and Reference.

Resource Endpoint

Request

Sample Request

🚧

Request Parameters

Initializing Payments Parameters

Transaction Parameters

Transaction Types

Merchant information parameters

Response

Card Payment Response

Wallet Response

Apple Pay Response

Offline Response

Aggregator Response

APM Response

Vouchers Response

📘Airline Itinerary Data

📘
Airline Itinerary Data