Request Parameters

API Reference: Authorize

See the following reference information for Authorize API request parameters:

Find Authorize API sample code in Authorize.

`authorize-payment`

Parent: root

The authorize-payment element is required, and it has the following attributes:

Parameter	Format	Requirement	Description
`account`	Integer	Optional	The unique ID associated with a payment transaction. If you omit this parameter, the payment transaction is associated with the default sub-account. When using Apple Pay: 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	Required	The unique ID configured for a merchant on the Velocity POP.

`transaction`

Parents: root: authorize-payment

The transaction element is required, and it has the following attributes:

Parameter	Format	Requirement	Description
`id`	Integer	Required	The ID of the transaction. For FX transactions, use the `transaction: id` value in the FX OfferCriteria request.
`store-card`	Boolean	Optional	When set to `true`, Velocity API will store this transaction's payment method information.
`type-id`	Integer	Required	A unique transaction identification number.

`card`

Parents: root: authorize-payment: transaction

The card element is required, and it has the following attribute:

Parameter	Format	Requirement	Description
`type-id`	Integer	Optional	The type of transaction used for making payment. Velocity supports the transaction types found in the `type-id` Transaction Types table below.
`network`	Enum	Optional	A list to identify the card network from which the token was obtained. It takes one of the following values: • `amex` • `dankort` • `dinersclub` • `jcb` • `maestro` • `mastercard` • `visa` • `visaelectron` • `discover` Applicable to third-party wallet authorizations.

`type-id` Transaction Types

Velocity supports the following transaction types (used to define type-id):

Value	Transaction types	Examples
`1`	Online shopping	S&B Purchase
`2`	Offline shopping	S&B Purchase
`3`	Self Service Online	MYB Ancillary Purchase, MYB Change Itinerary Payment, OLCI Ancillary Purchase
`4`	Self Service Offline	MYB Pay Later
`5`	Self Service Online	MYB/Self Service Online with additional rules on FOP-- Managed Booking txn where additional rules on FOP can be configured
`6`	Self Service Online	CPL - Payment Link Transaction. Transaction originated from payment link.

`amount`

Parents: root: authorize-payment: transaction: card

The amount element is required, and it has the following attributes:

Parameter	Format	Requirement	Description
`country-id`	Integer	Required	The CellPoint Digital-specific country code. This is available in Reference. For an FX transaction in an opt-in scenario, this is the country code for the new currency, after conversion. For an FX transaction in an opt-out scenario, this is the country code of the original currency.
`currency-id`	Integer	Optional	The currency code configured for a country. This depends on the configuration available through Velocity. For an FX transaction in an opt-in scenario, this is the currency code for the new currency, after conversion. For an FX transaction in an opt-out scenario, this is the currency code of the original currency.

The amount element has the following text content:

Parameter	Format	Requirement	Description
amount	Integer	Required	The total amount a customer is charged for a payment transaction in the specified country’s smallest currency. For example, the smallest currency of USD is the penny. If the transaction amount is $120.30, then the text content of `amount` is `12030`. For an FX transaction in an opt-in scenario, this is the total amount in the new currency, after conversion. For an FX transaction in an opt-out scenario, this is the total amount in the original currency.

`card-holder-name`

Parents: root: authorize-payment: transaction: card

The card-holder-name element is required for a new card transaction, and it has the following text content:

Parameter	Format	Requirement	Description
cardholder name	String	Conditional Requirement: Required for a new card transaction.	The name on the payment card being used in this transaction.

`card-number`

Parents: root: authorize-payment: transaction: card

The card-number element is required for a new card transaction, and it has the following text content:

Parameter	Format	Requirement	Description
card number	Integer	Conditional Requirement: Required for a new card transaction.	The number on the payment card.

`expiry`

Parents: root: authorize-payment: transaction: card

The expiry element is required for a new card transaction, and it has the following text content:

Parameter	Format	Requirement	Description
expiration date	String, in MM/YY format	Conditional Requirement: Required for a new card transaction.	The payment card's expiration date.

`cvc`

Parents: root: authorize-payment: transaction: card

The cvc element is required for a new card transaction, and it has the following text content:

Parameter	Format	Requirement	Description
CVC	Integer	Conditional Requirement: Required for a new card transaction.	The CVC number on the payment card.

`token`

Parents: root: authorize-payment: transaction: card

The token element is required for a third-party wallet transaction, and it has the following text content:

Parameter	Format	Requirement	Description
token	String	Conditional Requirement: Required for a third-party wallet transaction	The base64 encoded cryptogram for a third-party wallet such as Apple Pay. Applicable to third-party wallet transactions.

`address`

Parents: root: authorize-payment: transaction: card

The address element is required for transactions using a third-party wallet, FX, or Installments. It has the following attribute:

Parameter	Format	Requirement	Description
`country-id`	Integer	Required	The CellPoint Digital-specific country code. This is available in Reference. Applicable to third-party wallet and FX transactions.

The address element has the following children:

Element	Requirement	Format of text content	Description of text content
`full-name`	Conditional Requirement: Required for third-party wallet transactions.	String	The customer's full name. Applicable to third-party wallet transactions.
`first-name`	Conditional Requirement: Required for Installment transactions.	String	The first name in the billing address. Applicable to 3DS, FX, and Installment transactions.
`last-name`	Conditional Requirement: Required for Installment transactions.	String	The last name (surname) in the billing address. Applicable to 3DS, FX, and Installment transactions.
`street`	Required	String	The customer's full street address, including street name and street number. Applicable to third-party wallet, 3DS, FX, and Installment transactions.
`postal-code`	Required	String	The postal code in the customer's mailing address. Applicable to third-party wallet, 3DS, FX, and Installment transactions.
`city`	Required	String	The city in the customer's mailing address. Applicable to third-party wallet, 3DS, FX, and Installment transactions.
`state`	Conditional Requirement: Required if country of residence is divided into states.	String	The state in the customer's mailing address. Customers enter this parameter only if their country of residence is divided into states. Applicable to third-party wallet, 3DS, FX, and Installment transactions.
`country-id`	Optional	Integer	The CellPoint Digital-specific country code. This is available in Reference. Applicable to third-party wallet transactions.

`contact-details`

Parents: root: authorize-payment: transaction: card: address

Please note:

The contact-details element is required for FX and Installment transactions.
The contact-details element has two children: mobile and email.
The mobile child element can be mandatory or optional, based on the requirement of a merchant or a PSP.

The mobile element has the following attributes:

Parameter	Format	Requirement	Description
`country-id`	Integer	Conditional Requirement: Required if mobile number is present.	The CellPoint Digital-specific country code. This is available in Reference. Applicable to 3DS, FX, and Installment transactions.
`operator-id`	Integer	Optional	The ID of a customer’s mobile network operator. CellPoint Digital recommends including this parameter in a request to ensure that Velocity correctly interacts with the operator. Applicable to 3DS, FX, and Installment transactions.

The mobile element has the following text content:

Parameter	Format	Requirement	Description
mobile number	Integer	Conditional Requirement: A mobile number can be mandatory or optional, based on the requirement of a merchant or a PSP.	The MSISDN of a customer without International Dialing Code. Applicable to 3DS, FX, and Installment transactions.

The email element is optional, and it has the following text content:

Parameter	Format	Requirement	Description
email address	String	Optional	The customer's email address. Applicable to 3DS, FX, and Installment transactions.

`device_data_info`

Parents: root: authorize-payment: transaction

Please note:

The device_data_info element is required in the second Authorize request during 3-D Secure 2.0 (3DS) authentication, after DDC. For more information on the workflow, see the 3DS integration guide.
The device_data_info element can have the following children: id, collection_time, expired, and additional_info; see their descriptions below.

The id child element is optional, and it has the following text content:

Parameter	Format	Requirement	Description
DDC ID	String	Optional	ID returned by the provider after Device Data Collection (DDC). Applicable to the second Authorize request during 3DS authentication.

The collection_time child element is required in a second Authorize request, after DDC, and it has the following text content:

Parameter	Format	Requirement	Description
collection time	Integer	Conditional Requirement: Required after DDC in a 3DS flow.	The time required for DDC, in milliseconds. Applicable to the second Authorize request during 3DS authentication.

The expired child element is required in a second Authorize request, after DDC, and it has the following text content:

Parameter	Format	Requirement	Description
expiration Boolean	Boolean	Conditional Requirement: Required after DDC in a 3DS flow.	If `true`, the DDC process has expired. (Validation took longer than the time defined in `collection_time`.) Applicable to the second Authorize request during 3DS authentication.

`additional_info`

Parents: root: authorize-payment: transaction: device_data_info

The additional_info element is applicable to the second Authorize request during 3DS authentication. It is required if the DDC provider returns any additional information. It may have multiple info children.

Each info child element has the following children:

Element	Requirement	Format of text content	Description of text content
`key`	Conditional Requirement: At least one `key` parameter is required if the DDC provider returns any additional information.	String	The type of additional information. Applicable to the second Authorize request during 3DS authentication.
`value`	Conditional Requirement: At least one `value` parameter is required if the DDC provider returns any additional information.	String	The value of the additional information defined by `key`. Applicable to the second Authorize request during 3DS authentication.

`foreign-exchange-info`

Parents: root: authorize-payment: transaction

The foreign-exchange-info element is required for transactions using CellPoint Digital's Foreign Exchange (FX) service. It has the following children:

Element	Requirement	Format of text content	Description of text content
`id`	Conditional Requirement: Required for payments using FX.	Integer	The identification number for a transaction. Only applicable for payments using FX.
`service-type-id`	Optional	Integer	The Exchange Service ID, 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: X - Represents the type of FX used in a transaction. Y - Represents the service used-- it can be: Opt-in, which has value as `1` Opt-out, which has value as `2` The Exchange Service ID table shows the possible values of exchange service ID. Only applicable for payments using FX.
`conversion-rate`	Conditional Requirement: Required for payments using FX in an opt-in scenario.	Float	The rate at which the currency is converted. Use the `offered-exchange-rate` value in the FX OfferCriteria response for the currency that the customer selected. Only applicable for payments using FX in an opt-in scenario.
`sale-currencyid`	Optional	Integer	The currency code for the original currency. Only applicable for payments using FX in an opt-in scenario.
`sale-amount`	Optional	Integer	The total sale amount in the original currency. Only applicable for payments using FX in an opt-in scenario.

`voucher`

Parents: root: authorize-payment: transaction

The voucher element is required for a transaction that uses a voucher. It has one child: amount.

The voucher element has the following attributes:

Parameter	Format	Requirement	Description
`id`	String	Required	The voucher ID.
`order-no`	String	Required	The order number associated with the voucher.

The amount child element here has the same structure as the amount element in the card object. See card:amount for a description of parameters.

`hmac`

Parents: root: authorize-payment: transaction

The hmac element is optional, and it contains the following text content:

Parameter	Format	Requirement	Description
HMAC	AN String	Optional	The Message Authentication Code (MAC). It is calculated by creating a SHA-512 hash comprising the input fields in the order listed in the Message Authentication Code table in Reference. 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. Note: CellPoint Digital provides the salt value to merchants. Conditional Parameters are optional in `hmac` if they are not provided in the request; if those parameters are present in the request, they are mandatory in `hmac`.

`additional-data`

Parents: root: authorize-payment: transaction

Note the following:

The additional-data element is optional, and it can have multiple param children.
Each param child element has:
- one name attribute, and
- text content defined by the value of that name attribute.

The table below describes the possible attribute values and their associated text content.

Attribute	Attribute Value	Requirement	Text Content Format	Text Content Value
`name`	`BrowserScreenHeight`	Optional	Integer	The height (in pixels) of the browser screen used for this transaction.
`name`	`BrowserScreenWidth`	Optional	Integer	The width (in pixels) of the browser screen used for this transaction.
`name`	`BrowserLanguage`	Optional	String	The language of the browser used for this transaction; for example, `en-US`.
`name`	`BrowserJavaEnabled`	Optional	Boolean	When `true`, Java is enabled for the browser used for this transaction.
`name`	`httpAcceptContent`	Optional	String	The type of content accepted by the browser.
`name`	`BrowserJavascriptEnabled`	Optional	Boolean	When `true`, JavaScript is enabled for the browser used for this transaction.
`name`	`BrowserColorDepth`	Optional	Integer	The color depth of the browser screen used for this transaction.
`name`	`BrowserTimeDifference`	Optional	Integer	The time zone offset for the location of the browser used for this transaction.
`name`	`UserAgent`	Optional	String	Details about the user agent for this transaction.

`ip`

Parents: root: authorize-payment

The ip element is optional, and it has the following text content:

Parameter	Format	Requirement	Description
IP	String	Optional	The IP used in the transaction.

`client-info`

Parents: root: authorize-payment

The client-info element is required, and it has the following attributes:

Parameter	Format	Requirement	Description
`language`	String	Required	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.
`platform`	String	Required	The type of platform from which the request is sent. For example, web, iOS, Android, B2B, and B2C.
`version`	String	Required	The version of the API or application sending the request.

`mobile`

Parents: root: authorize-payment: client-info

The mobile element can be mandatory or optional, based on the requirement of a merchant or a PSP. It has the following attribute:

Parameter	Format	Requirement	Description
`country-id`	Integer	Conditional Requirement: Required if mobile number is present.	The CellPoint Digital-specific country code. This is available in Reference.
`operator-id`	Integer	Optional	The ID of a customer’s mobile network operator. CellPoint Digital recommends including this parameter in a request to ensure that Velocity correctly interacts with the operator.

The mobile element has the following text content:

Parameter	Format	Requirement	Description
mobile number	Integer	Conditional Requirement: A mobile number can be mandatory or optional, based on the requirement of a merchant or a PSP.	The MSISDN of a customer without International Dialing Code.

`email`

Parents: root: authorize-payment: client-info

The email element can be mandatory or optional, based on the requirement of a merchant or a PSP. It has the following text content:

Parameter	Format	Requirement	Description
email address	String	Conditional Requirement: Email can be mandatory or optional, based on the requirement of a merchant or a PSP.	The customer's email address. If a customer provides this parameter, the 'Email' input field on the 'Send E-Mail Receipt' page is automatically populated with this value.

`device-id`

Parents: root: authorize-payment: client-info

The device-id element is optional for a web channel, and it has the following text content:

Parameter	Format	Requirement	Description
device ID	String	Conditional Requirement: Device ID is optional for a web channel.	The device ID of the customer’s device.

Updated 12 days ago