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 Name	Path Details
End Point	[Velocity URL]/mpoint/pay
Format/Content Type	text/xml
Authentication	HTTP 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.

Parameter	Type	Required	Description
account	String	Yes	The identification number of a merchant account
client-id	Integer	Yes	The unique ID of a merchant.
id	String	Yes	CPD Transaction ID for which status is requested.
card type-id	Integer	Yes	The type of card used for a transaction.
amount country-id	Integer	Yes	The CPD-specific country code for the currency, which is made available to merchants on request.
currency-id	Integer	No	The currency of the transaction amount. This should be the ISO 4217 numeric code.
token	String	No	This is a card token.
hmac	String	Yes	Hash-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 id	String	Yes	The billing address country ID of the customer.
full-name	String	Yes	The full name of the customer.
street	String	Yes	The street name of the customer.
city	String	Yes	The city name of the customer.
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.
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 country-id	Integer	Yes	The CPD-specific country code for country of mobile, which is made available to merchants on request.
email	String	Yes	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 prepopulated with this value.
customer-ref	Integer	Yes	A unique reference number used for customer identification.

HMAC

Parameter	Required
clientid	Yes
orderid	Yes
amount	Yes
country	Yes
mobile	Conditional
mobile-country	Conditional
email	Conditional
deviceid	Conditional
salt	Yes

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

The device ID of a customer’s device.
Note: Device ID is optional for a web channel.

fees/fee

Integer

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

String

The identification number of a merchant account.

markup

String

Yes

The type of store front.

Transaction Parameters

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

This is a card token.

token

String

This is a card token.

psp-info Parameters

integer

yes

Internal ID of the PSP in Velocity

merchant-account

integer

Used for merchant-account for third-party wallet on device.

content-type

String

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

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

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.