Authorize Payment
7. Authorize Payment
The authorize payment request is used to authorize a payment. The API is available at the following path:
| End point | [Velocity URL]/mpoint/ authorize-payment |
| Format | text/xml |
| Authentication | HTTP basic access authentication |
7.1 Authorize Request
The payment authorize request is initiated using the payment token returned by Google Pay™ after a card is selected for completing the transaction by the user. The expected format of <token> is base-64 encoded string.
Sample Token from Google Pay™ after base-64 decode: paymentMethodToken:token:
{"signature":"MEUCIQC3NcKqGIPaVXOPM/Bj+Z7n0aj+4W2tXAGFhUHyiWnAygIgA63/Tua2SoSShO44twYIgoc+iWEYGqwq3OyLW9PgEew\u003d","protocolVersion":"ECv1","signedMessage":"{\"encryptedMessage\":\"CLMBGB3LYeQn3EAVIpJviCSjS0Um82lEM8f1nHzSie2DFe4DcD1kvBtwqYbMgPO2L4g6qIokQGNL5Q6PoDhfaPIfgR4d1mnrDJ86XMN+Dz2CbiePbhHKGU3onUdJgd7aWGU9Mk9FevGJm5sYWdazyReq/PO2ajwuNraoXzNxjxLeXiYsEcl1HvmgwVv50tP9AhKCgf1UnNH1HUQXlSobFaUVayVQpqn3XOtHo/BGv5O92T34vdC7lOpAjVRrHkrHqhdoZ6M4IzZLl6TlA/9NsLvUl2TAKWUFq/1j07yVEDs4K5UwPs5LViJc4rlMPywI44B2zQnhB3h9iZW8TFTOBGU/uf+0f9t0f0D9j5e4o+46+Ki9jp8T5llaDhxpFJJzDPb5u+oAM1ZHZdP6lhVWQ77qDQ4\\u003d\",\"ephemeralPublicKey\":\"BBcuSTInFFydICDeDO6FnXfxgOpyrmRy5klmMGImkjWas1L46bFrFh6zNmZnHEAqXrQHSd/x/HDSCTCo0AFWx0Y\\u003d\",\"tag\":\"033Q7bumMQTQ5r/Ov9DMOQNhrMEpbmYjnvWZCs8C/lU\\u003d\"}"}
The following code is an example of making payment:
<?xml version="1.0" encoding="UTF-8"?>
<root>
<authorize-payment account="[account-id]" client-id="[client-id]">
<transaction type-id="1009" id="[transaction-id]">
<card network="visa" type-id="41">
<amount currency-id="[currency-id]" country-id="[country-id]">[amount-in-decimals]</amount>
<token>[token]</token>
<address country-id="[country-id]">
<full-name>Name</full-name>
<street>Street</street>
<postal-code>1111</postal-code>
<city>CityName</city>
<state>StateName</state>
</address>
</card>
<hmac>f2cd1d924416574d571c6e59d5e00d1a28a462cd9d98f718057267aec380430502ae0640a71af230125af855878fa41571d1fe1ea6fbade401f3fd974c826fd5
</hmac>
</transaction>
<client-info language="us" version="1.46"
platform="Android/10(29)">
<mobile operator-id="64300" country-id="[country-id]">[mobile-number]</mobile>
<email>[email]</email>
<ip>[ip]</ip>
<device-id>1f771072-2fc8-4e2a-9d52-7038f8b385e1</device-id>
</client-info>
</authorize-payment>
</root>
The Authorize Request parameters are listed in the table below.
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| Authorize-payment Parameters | |||
| account | Integer | No | The number for a sub-account with which a 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. |
| client-id | Integer | Yes | The unique ID of a merchant. |
| Transaction Parameters | |||
| id | Integer | Yes | The ID of the transaction. |
| type-id | Integer | Yes | A unique transaction identification number. |
| card network | Enum | No | A list to identify the card network from which the token was obtained. It takes one of the following values:
|
| Card Parameters | |||
| currency-id | Integer | Yes | The country currency code of a currency. |
| country-id | Integer | Yes | The CPD-specific country code, which is made available to merchants on request. |
| token | String | No | The base64 encoded cryptogram for a third-party wallet such as Google Pay™. |
| hmac | String | No | The Message Authentication Code (MAC). 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. |
| Address Parameters | |||
| country-id | Integer | Yes | The CPD-specific country code, which is made available to merchants on request. |
| full-name | String | Yes | The full name of a customer. |
| street | String | Yes | The full address of a customer with street name and street number. |
| postal-code | String | Yes | The postal code of a customer. |
| city | String | Yes | The city in which a customer resides. |
| state | String | No | The state in which a customer resides. Customers enter this parameter only if their country of residence is divided onto states |
| country-id | Integer | Yes | The CPD-specific country code, which is made available to merchants on request. |
| 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, web, iOS, Android, B2B, and B2C. |
| 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. |
| String | No | The email address of a customer. If a customer provides this parameter, the Email input field on the Send Email Receipt page is automatically populated with this value. | |
7.2 Authorize Response
For Google Pay™, we receive the 2 types of response as per the data we receive from the Google Pay™ Wallet.
7.2.1 Case 1
The Velocity server sends the response informing 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 Authorize Response parameters are listed in the table below.
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| Status | String | Yes | Describes the status code. |
| Code | Integer | Yes | Status code for the authorizing processes. |
7.2.2 Case 2
In some cases, we will receive the parse challenge from the provider where the user needs to complete the parsed challenge to complete the transaction.
7.2.3 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:
- Extract the content of tags <parsed-challenge>.
- Do a form post of all the fields hidden-fields to the url in the action tag using browser.
- Follow the instruction to complete authentication.
- After the authentication is complete, it is redirected to your Accept or Decline URL.
- The Callback notification with authorization status is sent to your Callback URL.
7.2.4 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><html class="no-js" lang="en" xmlns="http://www.w3.org/1999/xhtml"> <head> <META http-equiv="Content-Type" content="text/html; charset=utf-8"> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <meta charset="utf-8"> <title>3D Secure Processing</title> <link href="https://myurl/mdpaympi/static/mpi.css" rel="stylesheet" type="text/css"> </head> <body> <div id="main"> <div id="content"> <div id="order"> <h2>3D Secure Processing</h2> <script src="https://3ds-mpi-cellpointmobile.test.modirum.com/mdpaympi/static/red.js" defer>/* needed for xsl to xhtml */</script> <div id="spinner"> <img src="https://3ds-mpi-cellpointmobile.test.modirum.com/mdpaympi/static/preloader.gif" alt="Please wait.."></div> <img src="https://3ds-mpi-cellpointmobile.test.modirum.com/mdpaympi/static/mc_idcheck_hrz_ltd_pos_103px.png" alt="MasterCard ID Check"><iframe id="tdsMmethodTgtFrame" name="tdsMmethodTgtFrame" xmlns="http://www.w3.org/1999/xhtml"><!--.--> </iframe><form id="tdsMmethodForm" name="tdsMmethodForm" action="https://3ds-acs.test.modirum.com/mdpayacs/3ds-method" method="post" target="tdsMmethodTgtFrame"> <input type="hidden" name="3DSMethodData" value="eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogImRkZjQ5MTYxLTZiYjgtNWY5YS04MDAwLTAwMmVhNzE4N2E0ZCIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIiA6ICJodHRwczovLzNkcy1tcGktY2VsbHBvaW50bW9iaWxlLnRlc3QubW9kaXJ1bS5jb20vbWRwYXltcGkvTWVyY2hhbnRTZXJ2ZXI_bW49WSZ0eGlkPTIwMDM3MTg5NDg2MSZkaWdlc3Q9UFVyQ3ZnWnZZeHp0cVU1a1N2MTdTdnhjUlVXaTAwWVByNlh5MmttWCUyQkg0JTNEIiB9"><input type="hidden" name="threeDSMethodData" value="eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogImRkZjQ5MTYxLTZiYjgtNWY5YS04MDAwLTAwMmVhNzE4N2E0ZCIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIiA6ICJodHRwczovLzNkcy1tcGktY2VsbHBvaW50bW9iaWxlLnRlc3QubW9kaXJ1bS5jb20vbWRwYXltcGkvTWVyY2hhbnRTZXJ2ZXI_bW49WSZ0eGlkPTIwMDM3MTg5NDg2MSZkaWdlc3Q9UFVyQ3ZnWnZZeHp0cVU1a1N2MTdTdnhjUlVXaTAwWVByNlh5MmttWCUyQkg0JTNEIiB9"> </form><div id="formdiv"> <div> <form id="webform0" name="ddcoll" method="POST" action="https://3ds-mpi-cellpointmobile.test.modirum.com/mdpaympi/MerchantServer" accept_charset="UTF-8"> <input type="hidden" name="txid" value="200371894861"><input type="hidden" name="TDS2_Navigator_language" value=""><input type="hidden" name="TDS2_Navigator_javaEnabled" value=""><input type="hidden" name="TDS2_Navigator_jsEnabled" value=""><input type="hidden" name="TDS2_Screen_colorDepth" value=""><input type="hidden" name="TDS2_Screen_height" value=""><input type="hidden" name="TDS2_Screen_width" value=""><input type="hidden" name="TDS2_Screen_PixelDepth" value=""><input type="hidden" name="TDS2_TimezoneOffset" value=""><input type="hidden" name="digest" value="5woOk3ql1bNMosc5yuyLXdk8k47KCTR+uVloWvAA/XQ=" readonly="true"><input type="submit" name="submitBtn" id="submitBtn" value="Please click here to continue"> </form> </div> </div> <noscript> <div align="center"> <b>Javascript is turned off or not supported!</b> <br> </div> </noscript> </div> <div id="content-footer"></div> </div> </div> </body> </html></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:
- Extract the content of tags <web-method>.
- HTML decode the web-method content to get the HTML.
- Load the HTML on the browser and follow the instructions to complete the authentication.
- After the authentication is complete, it is redirected to your Accept or Decline URL.
- The Callback notification with authorization status is sent to your Callback URL.
7.2.5 Authorization Failure
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| status | String | Yes | Describes the status code. |
| code | Integer | Yes | A status code for the authorizing processes. |
| sub-code | Integer | Yes | The granular-level status code which shows the reason for a failed authorization. |
Updated about 1 year ago