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 operation is to:
- Retrieve information about how to proceed with the payment or PSP confirmation that 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, APM, and store card.
Note: Merchants are not required to call the Pay operation if they opt to use the store vault of Velocity and their customers make payment using the stored cards.
After using the Pay operation, merchants must invoke the Authorize operation. Refer to Authorize Payment for details.
The table below specifies the endpoint and request requirements for this operation:
Name | Details |
---|---|
Endpoint | [ VELOCITY URL]/mpoint/pay |
Request Method | POST |
Authentication | HTTP basic access authentication |
Format/Content Type | text/xml |
Pay Request
A Pay request is sent from a merchant’s server to Velocity as follows:
<?xml version="1.0" encoding="UTF-8"?>
<pay account="100691" client-id="10069">
<transaction store-card="false" id="1935288">
<card type-id="8">
<amount country-id="603" currency-id="356">85556</amount>
</card>
<hmac>70a702a84cd3fa8d5d3f4bb8e43d69b231e2bfe3</hmac>
<!—The following foreign-exchange-info node is applicable only for Fx Service -->
<foreign-exchange-info>
<id>123</id>
<conversation-rate>1.3456</conversation-rate>
<service-type-id>11</service-type-id>
<sale-currencyid>840</sale-currencyid>
<sale-amount>42778</sale-amount>
</foreign-exchange-info>
<!-- PCC request node will be without conversation-rate
<foreign-exchange-info>
<id>{{cfxid}}</id>
</foreign-exchange-info>
-->
</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>
</pay>
Pay Response
The Pay response includes all the required parameters that Velocity sends to a merchant’s portal to authorize payments.
Card Payment
The code below is an example of a Pay 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>
APM
The code below is an example of a Pay response for a payment using an 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">[post URL]</url>
<hidden-fields>
<merchant>AFcWxV21C7fd0v3bYYYRCpSSRl31ADxVAF5rd9Z-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>
Wallet
The code below is an example of a Pay response for a wallet payment:
<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="15">
<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.applepay'; var displayName ="UATP"; var totalAmount = "1"; var supportedNetword = ['AMEX','MASTERCARD','VISA']; </script> <script type="text/javascript" src="https://s3.ap-southeast-1.amazonaws.com/cpmassets/psp/applepay.js"></script> <style> #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} </style></head>
<body><button type="button" id="applePay"></button></body>
</card>
</wallets>
Online Banking
The code below is an example of a Pay 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>aHR0cHM6Ly9yZWdpc3Ryby5kZXNhcnJvbGxvLnBzZS5jb20uY28vUFNFVXNlclJlZ2lzdGVyL1N0YXJ0VHJhbnNhY3Rpb24uYXNweD9lbmM9dG5QY0pITUtsU25tUnBITThmQWJ1JTJmZUU5dUxxYW4lMmI0elBDcU94S3I1b09ySXZTSmYwRElPcno0RjV3S0pQdU0jIyMjQVYgM0JWOVBMIyMxMjM0NTY3OA==</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 description of the parameters is as follows:
psp-info
Client information parameters
Parameter | Type | Required | Description |
---|---|---|---|
account | Integer | No | The number for a sub-account with which the payment transaction is associated. The account ID is an integer greater than 100000 and account number is an integer smaller than 1000. The payment transaction is associated with the default sub-account if merchants do not provide this parameter. |
auto-capture | Boolean | No | Shows if you have enabled auto-capture |
enable-cvv | Boolean | No | Shows if you have enabled CVV. |
mode | Integer | No | A parameter used in SDK to switch between production and staging environment. |
store-card | Boolean | No | Shows if a card is stored during a transaction. |
name | String | No | The name of a customer. |
callback-url | String | No | The absolute URL to a merchant’s back office where Velocity sends the payment status. Velocity uses the default URL if you do not provide this parameter for the callback URL. |
accept-url | String | No | The absolute URL where Velocity directs a customer after successfully completing a payment transaction. |
cancel -url | String | No | The absolute URL where Velocity directs customers if they cancel a payment transaction midway. |
Account parameters
Parameter | Type | Required | Description |
---|---|---|---|
id | String | No | The identification number of a merchant account. |
markup | String | Yes | The type of store front. |
Transaction parameters
Parameter | Type | Required | Description |
---|---|---|---|
auto-capture | Boolean | Yes | Shows if you have enabled auto-capture. |
eua-id | Integer | No | A parameter which identifies if the API to be called is for saving account or saving card. |
id | Integer | Yes | The identification number of 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 to http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for details. |
mode | Integer | No | A parameter used in SDK to switch between production and staging environment. |
order-no | Integer | No | A unique order number of a transaction. |
amount | Integer | Yes | The amount which a customer pays. |
country-id | Integer | Yes | The CPD-specific country code, which is made available to merchants on request. |
currency | String | Yes | The currency used for a transaction. |
currency-id | Integer | Yes | The identification number of a currency. |
decimals | Integer | Yes | The number of decimals up to which a currency is shown. |
symbol | String | No | The symbol of the selected currency. |
callback-url | String | No | The absolute URL to a merchant’s back office where Velocity sends the payment status. Velocity uses the default URL if you do not provide this parameter for the callback URL. |
accept-url | String | No | The absolute URL where Velocity directs a customer after successfully completing a payment transaction. |
Card parameters
Parameter | Type | Required | Description |
---|---|---|---|
cvc-length | Integer | Yes | The length of CVC number on a card. |
enabled | Boolean | Shows if the card was enabled. | |
max-length | Integer | Yes | The maximum length of a card number. |
min-length | Integer | Yes | The minimum length of a card number. |
payment-type | String | Yes | The type of payment – card, wallet, or APM. |
preferred | Boolean | Yes | Shows if a customer has set a card as a preferred one. |
processor-type | String | Yes | The type of processor used to process payment. |
psp-id | Integer | Yes | The ID of a PSP used for a card. |
state-id | Integer | Yes | The state of a card. For example, enabled or disabled by the PSP. |
type-id | Integer | Yes | The type of a card scheme. For example, Mastercard or Visa. |
dcc | Boolean | No | Indicates if a currency conversion is available. The value can be true or false. |
name | String | Yes | Name of a card type or wallet. For example, Visa or Mastercard. |
psp-info parameters
Parameter | Type | Required | Description |
---|---|---|---|
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. See Method table below. |
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 to http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for details. |
Method
The table below shows possible values for the method of submitting the authorization request (used in method
):
Method | Description |
---|---|
App | Used for payment with the third-party wallet on the device. |
GET | Using HTTP GET. |
POST | Using HTTP POST. |
status parameter
Parameter | Type | Required | Description |
---|---|---|---|
code | Integer | Yes | Codes to show status of a transaction such as 1009, 1041. |
Foreign exchange parameters
Parameter | Type | Required | Description |
---|---|---|---|
id | Integer | Yes | The identification number for a transaction. |
conversation-rate | Float | Yes | The rate at which a currency is converted. |
service-type-id | Integer | No | The ID to indicate the type of exchange services used for a transaction. The ID indicates if the FX services such as DCC, 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 service-type-id table below shows the possible values of exchange service ID. |
service-type-id
The following table shows the possible values of exchange service ID (used in service-type-id
):
ID (XY) | Service (X) | Opted |
---|---|---|
11 | DCC | Opted |
12 | DCC | Not opted |
41 | PCC | Opted |
42 | PCC | Not opted |
Updated 5 months ago