Guides

Authorize

API Reference

Suggest Edits

This page and its subpages provide API reference for Velocity API's Authorize (authorize-payment) operation. See Authorize sample code below, and find Authorize parameters descriptions in the Request Parameters and Response Parameters subpages. For information on how to integrate this operation, see API.

Request

Endpoint: /mpoint/authorize-payment
Method: POST

There are different formats for the Authorize request depending on the payment method a customer selects when making a payment. See sample requests below, and find parameters descriptions in the following sections in the Request Parameters subpage:

Credit or Debit Card Request

The following is a sample Authorize request for a payment using a credit or debit card:

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<authorize-payment account="100101" client-id="10002">
		<transaction id="1832214" store-card="false" type-id="30">
			<card type-id="7">
				<amount country-id="200" currency-id="840">100</amount>
				<card-holder-name>First Last</card-holder-name>
				<card-number>4999777777777777</card-number>
				<expiry>01/29</expiry>
				<cvc>009</cvc>
			</card>
			<hmac>989898989880f2dd4e485d105a3e565519fb198dee93e4477dc888852ee45e3d3e3d89999c6dd68559fe2249f0326dc543b0f02db917587cc67aca5555555555</hmac>
			<additional-data>
				<param name="BrowserScreenHeight">1066</param>
				<param name="BrowserScreenWidth">2144</param>
				<param name="BrowserLanguage">en-US</param>
				<param name="BrowserJavaEnabled">false</param>
				<param name="httpAcceptContent">payment.test.ink</param>
				<param name="BrowserJavascriptEnabled">true</param>
				<param name="BrowserColorDepth">24</param>
				<param name="BrowserTimeDifference">300</param>
				<param name="UserAgent">Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:125.0) Gecko/20100101 Firefox/125.0</param>
				<param name="httpAcceptBrowserValue">*/*</param>
			</additional-data>
		</transaction>
		<ip/>
		<client-info language="en" platform="iOS/9.0" version="1.28">
			<mobile country-id="[integer]" operator-id="10000">[phone number]</mobile>
			<email>[email protected]</email>
			<device-id>3432444444444444444FFFFFf03</device-id>
		</client-info>
	</authorize-payment>
</root>

Third-party Wallet Request

The following is a sample Authorize request for a payment using a third-party wallet:

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<authorize-payment account="[integer]" client-id="[integer]">
		<transaction type-id="[integer]" id="[integer]">
			<card network="mastercard" type-id="[integer]">
				<address country-id="[integer]">
					<full-name>First Last</full-name>
					<street>123 Test St.</street>
					<postal-code>77666</postal-code>
					<city>Test City</city>
					<state>CA</state>
				</address>
				<amount country-id="[integer]">10025</amount>
				<token>dasdlkjasl31232123231dkdlsakldfmggmmggm........</token>
			</card>
		</transaction>
		<client-info language="en" version="1.20" platform="iOS/8.1.3">
			<mobile operator-id="[integer]" country-id="[integer]">[phone number]</mobile>
			<device-id>32E232E232E2915D14777777</device-id>
		</client-info>
	</authorize-payment>
</root>

Voucher Request

The following is a sample Authorize request for a payment using a voucher:

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<authorize-payment account="100101" client-id="10002">
		<transaction id="1832214" store-card="false" type-id="30">
			<voucher id="[string]" order-no="[string]">
				<amount country-id="200" currency-id="840">100</amount>
			</voucher>
		</transaction>
		<client-info language="en" platform="iOS/9.0" version="1.28">
			<mobile country-id="[integer]" operator-id="10000">[phone number]</mobile>
			<email>[email protected]</email>
			<device-id>3432444444444444444FFFFFf03</device-id>
		</client-info>
	</authorize-payment>
</root>

3DS2 Authenticated Card Request

The following is an example of a second Authorize request after verification during a 3-D Secure 2.0 (3DS2) authentication workflow:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <authorize-payment account="117000" client-id="11700">
        <transaction id="9563765" store-card="false" type-id="10091">
            <card type-id="7">
                <amount country-id="403" currency-id="986">40000</amount>
                <card-number>4999777777777777</card-number>
                <expiry>01/29</expiry>
                <cvc>123</cvc>
                <card-holder-name>First Last</card-holder-name>
                <address country-id="405">
                    <first-name>First</first-name>
                    <last-name>Last</last-name>
                    <street>123 Test St.</street>
                    <postal-code>77666</postal-code>
                    <city>Test City</city>
                    <state>Alaska</state>
                    <contact-details>
                        <mobile country-id="428" operator-id="10000">7676565654</mobile>
                        <email>[email protected]</email>
                    </contact-details>
                </address>
            </card>
            <device_data_info>
                <id>3432a22-29d3-4e2d-bc78-4444FFFFFf03</id>
                <collection_time>7000</collection_time>
                <expired>false</expired>
                <additional_info>
                    <info>
                        <key>status</key>
                        <value>true</value>
                    </info>
                    <info>
                        <key>message</key>
                        <value>profile.completed</value>
                    </info>
                </additional_info>
            </device_data_info>
            <hmac>989898989880f2dd4e485d105a3e565519fb198dee93e4477dc888852ee45e3d3e3d89999c6dd68559fe2249f0326dc543b0f02db917587cc67aca5555555555</hmac>
        </transaction>
        <client-info language="en" platform="HTML5" version="2.0.0">
            <mobile country-id="403" operator-id="10000">[phone number]</mobile>
            <email>[email protected]</email>
            <ip>22.222.444.101</ip>
        </client-info>
    </authorize-payment>
</root>

Installments Request

Below is an example Authorize request for installments:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <authorize-payment account="101012" client-id="10101">
        <transaction type-id="10091" id="5297672" store-card="false">
            <card type-id="7">
                <amount country-id="405" currency-id="170">201000000</amount>
                <cvc>123</cvc>
                <card-holder-name>First Last</card-holder-name>
                <card-number>4999777777777777</card-number>
                <expiry>10/29</expiry>
                <address country-id="405">
                    <first-name>First</first-name>
                    <last-name>Last</last-name>
                    <street>123 Test St.</street>
                    <postal-code>711111</postal-code>
                    <city>Test City</city>
                    <state>CA</state>
                    <contact-details>
                        <mobile operator-id="64000" country-id="640">9881112222</mobile>
                        <email>[email protected]</email>
                    </contact-details>
                </address>
            </card>
            <installment>
                <value>5</value>
            </installment>
            <hmac>989898989880f2dd4e485d105a3e565519fb198dee93e4477dc888852ee45e3d3e3d89999c6dd68559fe2249f0326dc543b0f02db917587cc67aca5555555555</hmac>
        </transaction>
        <client-info language="en" sdk-version="2.0.0" version="2.0.0" platform="HTML5" profileid="">
            <mobile operator-id="40500" country-id="405">9881112222</mobile>
            <email>[email protected]</email>
            <customer-ref>[email protected]</customer-ref>
            <device-id>3432444444444444444FFFFFf03</device-id>
        </client-info>
    </authorize-payment>
</root>

Foreign Exchange (FX) Request: Opt-In Scenario

Below is an example Authorize request using CellPoint Digital's Foreign Exchange (FX) service where the user has opted for payment with currency conversion (opt-in scenario):

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<authorize-payment account="100101" client-id="10002">
		<transaction id="1832214" store-card="false" type-id="10091">
			<card type-id="8">
				<amount country-id="403" currency-id="840">222541</amount>
				<cvc>123</cvc>
				<card-holder-name>CellPointMobile</card-holder-name>
				<card-number>4999777777777777</card-number>
				<expiry>10/26</expiry>
				<address country-id="403">
					<first-name>First</first-name>
					<last-name>Last</last-name>
					<street>123 Test St.</street>
					<postal-code>123456</postal-code>
					<city>Test City</city>
					<state>Alaska[AK]</state>
					<contact-details>
						<mobile country-id="403" operator-id="40300">9881112222</mobile>
						<email>[email protected]</email>
					</contact-details>
				</address>
			</card>
			<hmac>989898989880f2dd4e485d105a3e565519fb198dee93e4477dc888852ee45e3d3e3d89999c6dd68559fe2249f0326dc543b0f02db917587cc67aca5555555555</hmac>
			<foreign-exchange-info>
				<id>279937</id>
				<service-type-id>11</service-type-id>
				<conversion-rate>0.1854509</conversion-rate>
				<sale-currencyid>986</sale-currencyid>
				<sale-amount>1200000</sale-amount>
			</foreign-exchange-info>
			<additional-data>
				<param name="document_type">Passport</param>
				<param name="document_id">RDDD1000</param>
				<param name="BrowserScreenHeight">527</param>
				<param name="BrowserScreenWidth">1920</param>
				<param name="BrowserLanguage">en-US</param>
				<param name="BrowserJavaEnabled">false</param>
				<param name="BrowserJavascriptEnabled">true</param>
				<param name="BrowserColorDepth">24</param>
				<param name="BrowserTimeZoneOffset">-330</param>
				<param name="UserAgent">Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:125.0) Gecko/20100101 Firefox/125.0</param>
				<param name="BrowserScreenType">desktop</param>
				<param name="BrowserOrientation">landscape</param>
			</additional-data>
		</transaction>
		<client-info language="en" platform="HTML5" profileid="" sdk-version="2.0.0" version="2.0.0">
			<mobile country-id="403" operator-id="40300">9881112222</mobile>
			<email>[email protected]</email>
			<customer-reference>123</customer-reference>
			<device-id>2E8888F78B88877BBFF6176313BD88D333333333</device-id>
			<ip>50f1:055b:f555:b5ad:5e5f:cf5d:5b55:515c</ip>
		</client-info>
	</authorize-payment>
</root>

Foreign Exchange (FX) Request: Opt-Out Scenario

Below is an example Authorize request using CellPoint Digital's Foreign Exchange (FX) service where the user has not opted for payment with currency conversion (opt-out scenario):

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<authorize-payment account="111111" client-id="22222">
		<transaction id="3333333" type-id="10091">
			<card type-id="8">
				<amount country-id="986">1200000</amount>
				<card-holder-name>CellPointMobile</card-holder-name>
				<card-number>4999777777777777</card-number>
				<expiry>10/26</expiry>
			</card>
			<foreign-exchange-info>
				<id>279937</id>
				<service-type-id>12</service-type-id>
			</foreign-exchange-info>
		</transaction>
		<client-info language="en" platform="HTML5" profileid="" sdk-version="2.0.0" version="2.0.0">
			<mobile country-id="403" operator-id="40300">9881112222</mobile>
			<email>[email protected]</email>
			<device-id>3432444444444444444FFFFFf03</device-id>
			<customer-reference>123</customer-reference>
			<ip>50f1:055b:f555:b5ad:5e5f:cf5d:5b55:515c</ip>
		</client-info>
	</authorize-payment>
</root>

Response

See Authorize API response sample code below. Find parameter descriptions in the Response Parameters subpage.

Success

Below is an example of an Authorize response returned if the authorization was successful:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <status code="2000" sub-code="2000101">Payment authorized</status>
</root>

Failed

Below is an example of an Authorize response returned if the authorization failed:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <status code="2010" sub-code="2010205"> Unable to authorize</status>
</root>

3DS: DDC Verification Required

The following is a sample Authorize response received during a 3-D Secure 2.0 (3DS) flow when Device Data Collection (DDC) is required for authorization:

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<status code="200501">DDC verification required for Authorization</status>
	<web-method>&lt;html&gt; &lt;head/&gt; &lt;body&gt; &lt;iframe id=&quot;cardinal_collection_iframe&quot; name=&quot;collectionIframe&quot; height=&quot;10&quot; width=&quot;10&quot; style=&quot;display: none;&quot;&gt; &lt;input name=&quot;iframeplaceholder&quot; type=&quot;hidden&quot; disabled=&quot;disabled&quot;/&gt; &lt;/iframe&gt; &lt;form id=&quot;cardinal_collection_form&quot; method=&quot;POST&quot; target=&quot;collectionIframe&quot; action=&quot;https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect&quot;&gt; &lt;input id=&quot;cardinal_collection_form_input&quot; type=&quot;hidden&quot; name=&quot;JWT&quot; value=&quot;eyJhbGci9iJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGki9iI3NDRkMjRkYy1iYmMyLTQ9NjktODIyMC0yNDMwYTQzMjY2YWIiLCJpYXQiOjE9NDU1MDkzNzgsImlzcyI9IjVkZDgzYmYwMGU0MjNkMTQ9OGRjYmFjYSIsImV4cCI9MTc0NTUxMjk7OCwiT3JnVW5pdElkIjoiNjQzZmIyMzYyYTQwMmE2MWY3NzUyMMMkIiwiUmVmZXJlbmNlSWQiOiIzYzJjNmZiMi1lZjMwLTQ4NmMtYjkzMC1hMzQ0ODVkOWFlMjcifQ.LuNnNTqBPMZ-ZMk0VVVRXwfYeX3KxF1FCHgBo40Nfak&quot;/&gt; &lt;/form&gt; &lt;script type=&quot;text/javascript&quot;&gt; window.addEventListener(&quot;message&quot;, function(event) { let deviceDataInfoObject = { &quot;device_data_info&quot;: { &quot;collection_time&quot;: null, &quot;expired&quot;: false } }; if (event.origin === &quot;https://centinelapistag.cardinalcommerce.com&quot;) { let ddcEventData = JSON.parse(event.data); let ddcEventDataAdditionalInfo = { &quot;info&quot;: [ { &quot;key&quot;: &quot;status&quot;, &quot;value&quot;: ddcEventData.Status }, { &quot;key&quot;: &quot;message&quot;, &quot;value&quot;: ddcEventData.MessageType } ] }; deviceDataInfoObject[&quot;device_data_info&quot;][&quot;id&quot;] = ddcEventData.SessionId; deviceDataInfoObject[&quot;device_data_info&quot;][&quot;additional_info&quot;] = ddcEventDataAdditionalInfo; } let onDDCCompleteEvent = new CustomEvent(&quot;onDDCComplete&quot;, { 'detail': deviceDataInfoObject }); window.dispatchEvent(onDDCCompleteEvent); }, false); &lt;/script&gt; &lt;script type=&quot;text/javascript&quot;&gt; var cardinalCollectionForm = document.querySelector('#cardinal_collection_form'); if(cardinalCollectionForm) cardinalCollectionForm.submit(); &lt;/script&gt; &lt;/body&gt; &lt;/html&gt;</web-method>
	<ddc-expiry>8000</ddc-expiry>
	<return-url>https://returnurl.com/threed-redirect</return-url>
	<card-mask>522000******1005</card-mask>
	<expiry>01/29</expiry>
	<token>4eeb155fc20fa07a7c01d82aa68f9d22cab6257c57b6694d722cfdc8b95dce4d2f8f44e0a5c9aab14065e1f2016fc95eb0185cb62689b78e8e06346429c1aedc</token>
</root>

3DS: Challenge Flow

Below is sample of a second Authorize response for a challenge flow, when DDC succeeded but 3DS verification requires additional data:

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<status code="2005">3D verification required for Authorization</status>
	<parsed-challenge>
		<action type-id="11">
			<url content-type="application/x-www-form-urlencoded" method="post">https://url.com/challenge</url>
			<hidden-fields>
				<JWT>eyJhbGciOiJIUzI1NiIs</JWT>
			</hidden-fields>
			<configuration-fields>
				<iframe>true</iframe>
				<height>400</height>
				<width>400</width>
			</configuration-fields>
		</action>
	</parsed-challenge>
	<device_collection_status>
		<status>
			<code>200601</code>
			<description>DDC Successful</description>
		</status>
	</device_collection_status>
	<return-url>https://returnurl.com/threed-redirect</return-url>
	<card-mask>522000******1005</card-mask>
	<expiry>01/29</expiry>
	<token>4eeb155fc20fa07a7c01d82aa68f9d22cab6257c57b6694d722cfdc8b95dce4d2f8f44e0a5c9aab14065e1f2016fc95eb0185cb62689b78e8e06346429c1aedc</token>
</root>

3DS: Alternate Challenge Flow

Below is a sample Authorize response for a possible 3DS challenge flow that does not require DDC:

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<status code="2005" sub-code="2005002">3D Secure Verification Required</status>
	<web-method>{web-method}</web-method>
	<return-url>https://returnurl.com/threed-redirect</return-url>
	<card-mask>522000******1005</card-mask>
	<expiry>01/29</expiry>
	<token>4eeb155fc20fa07a7c01d82aa68f9d22cab6257c57b6694d722cfdc8b95dce4d2f8f44e0a5c9aab14065e1f2016fc95eb0185cb62689b78e8e06346429c1aedc</token>
</root>

Updated 12 days ago