Initialize Payment
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 Name | Path Details |
|---|---|
| End Point | [VELOCITY URL]/mpoint/initialize-payment |
| Format/Content Type | text/xml |
| Authentication | HTTP 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:
|
|||||||||||||||||||||||||||
| 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:
|
|||||||||||||||||||||||||||
| 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:
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. | |||||||||||||||||||||||||||
| 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><script type='text/javascript'> 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']; </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>
</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>
Updated 12 months ago