Initialize Request Parameters

The Initialize Request parameters when integrating Apple Pay with Velocity API are listed in the tables below.

Parameters for Initializing Payments

ParameterTypeMandatoryDescription
client-idIntegerYesThe unique ID configured for a merchant on the Velocity POP.
productidIntegerNoThe product of a merchant. For example, ticket and insurance.
Currency-idIntegerNoThe currency configured for a country. It depends on the configuration available with Velocity.
accountIntegerNoThe unique ID associated with a payment transaction. It is optional. If you omit this parameter, the payment transaction is associated with the default sub-account.
order-noStringYesThe order ID that a merchant generates. It is an alphanumeric string.

Note: Some Payment Providers have strict guidelines for the order-no. The recommended pattern is “[a-zA-Z0-9._-]”.
accept-urlStringNoThe URL where Velocity directs a customer after successfully completing a payment transaction.

Note: If you do not provide this parameter, Velocity uses the default URL. The URL is used for redirecting back to the HPP or the merchant’s page after a payment completion.
cancel-urlStringNoThe absolute URL where Velocity directs customers if they cancel a payment transaction midway.

Note: If you do not provide this parameter, Velocity uses the default URL. The URL is used for redirecting back to the HPP or the merchant’s page after a payment cancellation.
decline-urlStringNoThe absolute URL where Velocity directs customers if the payment transaction fails. The URL is used for redirecting back to the HPP or the merchant’s page after a payment failure.
auth-urlStringNoThe URL which is used for single sign-on (SSO) authentication if provided by an external system.
session-idIntegerNoThe ID of a session used for multiple payment transactions during one payment flow. For example, a split payment or a retry of a failed payment transaction.
product-typeStringNoThe product type used to select the payment methods to be displayed or acquirer to be selected. The typical values include TICKET and INSURANCE.
type-idIntegerYesThe type of a transaction. For example, 40 indicates a mobile application purchase and 30 indicates a web purchase.
amountIntegerYesThe 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 a penny. If the transaction amount is $120.30, then the amount field contains the value 12030.
country-idIntegerYesThe CELLPOINT DIGITAL-specific country code, which is available on request only.
callback-urlStringNoThe absolute URL to the back office of a merchant where Velocity POP sends the payment status.Velocity uses the default URL if merchants do not provide this parameter.
auth-tokenStringNoA unique token sent to the specified auth-url to authenticate customer when they pay with a stored card and use single sign-on.
HMACStringNoThe Message Authentication Code. It is calculated by creating a sha-512 hash comprising the input fields in the order listed in the Message Authentication Code table below.

Note: CELLPOINT DIGITAL provides the salt value to merchants.

Conditional Parameters are mandatory if parameters are provided in the request.

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.
ordersObjectNoThe order details which contain event, location, date or time, ticket type, cost, booking fee, quantity, and total price data.

Note: This parameter is used for airline data only.

Message Authentication Code

The Message Authentication Code in HMAC is calculated by creating a sha-512 hash comprising the following input fields in the listed order:

ParameterRequired
clientidYes
orderidYes
amountYes
countryYes
mobileConditional
mobile-countryConditional
emailConditional
deviceidConditional
saltYes

Merchant Information Parameters

ParameterTypeMandatoryDescription
platformStringYesThe platform from which the request is sent. For example, web, iOS, Android, B2B, and B2C.
sdk-versionIntegerYesThe software development kit (SDK) version used.
versionStringYesThe version of the application programming interface (API) or application that sends the request.
languageStringYesThe 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.
mobileIntegerYesThe MSISDN of a customer without International Dialling Code.

Note: Mobile number can be mandatory or optional, based on the requirement of a merchant or a PSP.
country-idIntegerNoThe CellPoint Digital-specific country code, which is provided on request.
operator-idIntegerNoThe ID of a customer’s mobile network operator. CellPoint Digital recommends including this parameter in a request to ensure that Velocity interacts with the operator accurately.
emailStringNoThe email address of a customer. If your customer provides this parameter, the Email input field on the Send Email Receipt page is automatically populated with this value.

Note: Email can be mandatory or optional, based on the requirement of a merchant or a PSP.
customer-refStringNoThe unique reference ID given by a merchant for a customer. Velocity uses this token to identify a user. The customer reference is included in the request to a specified auth-url to identify customers when they:

• Pay with a stored card.
• Use single sign-on.

Note: Customer-ref can be mandatory or optional, based on the requirement of a merchant or a PSP.

Initialize Response Parameters

The Initialize Response parameters for integrating Apple Pay with Velocity API are listed in the tables below.

ParameterTypeMandatoryDescription
versionIntegerYesThe version of the API or application that sends the request.

Client-config Parameters

ParameterTypeMandatoryDescription
accountIntegerNoThe number for the 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 you do not provide this parameter. CellPoint Digital recommends you provide this parameter.
auto-captureBooleanYesShows if you have enabled auto-capture.
modeIntegerNoA parameter used in the SDK to switch between production and staging environment.
store-cardIntegerYesIt defines the type of configuration merchants have done to store cards. See the store-card table below.
nameStringNoThe name a merchant gives to a card as configured in Velocity.
callback-urlStringYesThe absolute URL to a merchant’s back office where Velocity sends the payment status.

Note: If you do not provide this parameter, Velocity uses the default URL. This parameter is not applicable for most of the API-based integrations.
accept-urlStringYesThe absolute URL where Velocity directs a customer after successfully completing a payment transaction.

Note: If you do not provide this parameter, Velocity uses the default URL. This parameter is not applicable for most of the API-based integrations.

store-card

The store-card values below define the type of configuration merchants have done to store cards.

IntegerMeaning
0Cards are not stored.
1INVALID!
2Stored cards are available for specific accounts only.
3Use stored cards only and make them available for specific accounts only. The e-money based prepaid account is unavailable.
4Stored cards are available for all accounts.

Note: Velocity must be hosted by a Master Merchant.

Transaction Parameters

ParameterTypeMandatoryDescription
auto-captureBooleanYesShows if you have enabled auto-capture.
eua-idIntegerNoA parameter which identifies if the API to be called is for saving account or saving card.
idIntegerYesThe unique ID of a merchant for Velocity platform.
languageStringYesThe 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.
modeIntegerNoA parameter used in SDK to switch between production and staging environment.
order-noStringYesThe order ID that a merchant generates for a customer. It is an alphanumeric string.

Note: Some payment providers have strict guidelines for the order-no. The recommended pattern is “[a-zA-Z0-9._-]”.
type-idIntegerYesThe type of application used for a transaction. For example, 40 indicates a mobile app purchase and 30 indicates a web purchase.
country-idIntegerYesThe CellPoint Digital-specific country code, provided to merchants on request.
currencyStringYesThe format of currency used for a transaction.
formatStringYesThe format in which price is presented.
mobile country-idIntegerYesThe CellPoint Digital-specific country code, which is made available to merchants on request.
operator-idIntegerYesThe ID of a customer’s mobile network operator. CellPoint Digital recommends including this parameter in the request to ensure Velocity correctly interacts with the operator.

Session Parameters

ParameterTypeMandatoryDescription
idIntegerYesThe unique ID of a merchant for Velocity platform.
total-amountIntegerYesThe total amount that a customer pays for a transaction.
alpha2codeStringYesThe three-letter alphabetic code for a currency.
alpha3codeIntegerYesThe two-letter numeric code for a country.
codeIntegerYesThe CellPoint Digital currency code for a country.
country-idIntegerYesThe CellPoint Digital-specific country code, provided to merchants on request.
currencyStringYesThe format of currency used for a transaction.
currency-idIntegerYesThe currency code of a currency.
formatStringYesThe format in which price is presented.
symbolYesA symbol used to indicate the currency of a country.

Card Parameters

ParameterTypeMandatoryDescription
cvc-lengthIntegerYesThe length of the card verification code (CVC) number on a card.
cvcmandatoryBooleanYesIndicates if the CVC is mandatory for a transaction. The value can be true or false. It is used for a wallet transaction.
dccBooleanYesIndicates if currency conversion is available. The value can be true or false.
enabledBooleanYesShows if the card was enabled.
installmentStringNoThis is no longer used in a transaction.
min-lengthIntegerYesThe minimum length of a card number.
max-lengthIntegerYesThe maximum length of a card number.
payment-typeStringYesThe type of payment. For example, card, wallet, or APM.
preferredBooleanYesShows if a customer has set a card as a preferred one.
processor-typeStringYesThe type of processor used to process payment.
psp-idIntegerYesThe ID of a PSP used for a card.
state-idIntegerYesThe state of a card. For example, enabled or disabled by PSP.
type-idIntegerYesThe type of application used for a transaction. For example, 40 indicates a mobile app purchase and 30 indicates a web purchase.
nameStringYesThe name of a card type. For example, wallet or PSP.


Pay Request Parameters

The Pay Request parameters when integrating Apple Pay with Velocity API are listed in the tables below.

Parameters

ParameterTypeMandatoryDescription
accountIntegerNoThe 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-idIntegerYesThe unique ID of a merchant.

Transaction Parameters

ParameterTypeMandatoryDescription
idIntegerYesThe ID of the transaction.
type-idIntegerYesA unique transaction identification number.
card networkEnumNoA 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

Card Parameters

ParameterTypeMandatoryDescription
currency-idIntegerYesThe country currency code of a currency.
country-idIntegerYesThe CellPoint Digital-specific country code, which is made available to merchants on request.
tokenStringNoThe base64 encoded cryptogram or session URL received from a third-party wallet such as Apple Pay.
hmacStringNoThe 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 below.

Note: CELLPOINT DIGITAL provides the salt value to merchants.

Conditional Parameters are mandatory if parameters are provided in the request.

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.

Message Authentication Code

The Message Authentication Code (MAC) found in hmac is calculated by creating a sha-512 hash comprising the following input fields in the listed order:

ParameterRequired
clientidYes
orderidYes
amountYes
countryYes
mobileConditional
mobile-countryConditional
emailConditional
deviceidConditional
saltYes

Address Parameters

ParameterTypeMandatoryDescription
country-idIntegerYesThe CellPoint Digital-specific country code, which is made available to merchants on request.
full-nameStringYesThe full name of a customer.
streetStringYesThe full address of a customer with street name and street number.
postal-codeStringYesThe postal code of a customer.
cityStringYesThe city in which a customer resides.
stateStringNoThe state in which a customer resides. Customers enter this parameter only if their country of residence is divided into states.
country-idIntegerYesThe CellPoint Digital-specific country code, which is made available to merchants on request.

Client Information Parameters

ParameterTypeMandatoryDescription
languageStringYesThe language that Velocity uses as default when translating the payment pages.

Note: Velocity language codes are based upon the ISO- 639-1 standard.

Refer to https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for details.
versionStringYesThe version of an API or application that sends the request.
platformStringYesThe platform from which the request is sent. Examples: web, iOS, Android, B2B, and B2C.
mobile operator-idIntegerYesThe ID of a customer’s mobile network operator. CellPoint Digital recommends including this parameter in the request to ensure Velocity correctly interacts with the operator.
emailStringNoThe 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.

Pay Response Parameters

The Pay Response parameters for integrating Apple Pay with Velocity API are listed in the table below.

ParameterTypeMandatoryDescription
idIntegerYesDescribes the wallet ID information.
merchant-accountStringYesGives the merchant ID configured/used for this transaction which we need to pass/configure for Apple Pay.
typeIntegerYesGives the information for the Apple Pay (mostly required for the backend use).
headStringNoThe script is received in this node and which we need to load on the HTML DOM.
urlStringNoThe URL of the provider which can be used for redirection or the overlay.
methodStringNoTells us that this URL is an overlay or the redirection to specified URL.
session-dataStringConditionalThis data is mandatory for the web-based Apple Pay transaction and we need to pass the data as is to Apple Pay. On verification of the data, Apple Pay provides access to the wallet.
Card-brandsStringNoThis is the list of cards which we need to use/send to the Apple Pay wallet. Only this card will be visible or available to select. For example, 'MASTERCARD', 'VISA', 'DISCOVER', or 'AMEX'.
nameStringNoIt is optional and shares the cardholder’s name.
Auth-tokenStringNoThis is an auth token and is used in the security verification.
codeIntegerYesShares the status code for the Pay API call.
messageStringYesThe message tells us if the Pay API is successful or not.

Authorize Request Parameters

The Authorize Request parameters when integrating Apple Pay with Velocity API are listed in the tables below.

Authorize-payment Parameters

ParameterTypeMandatoryDescription
accountIntegerNoThe 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-idIntegerYesThe unique ID of a merchant.

Transaction Parameters

ParameterTypeMandatoryDescription
idIntegerYesThe ID of the transaction.
type-idIntegerYesA unique transaction identification number.
card networkEnumNoA 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

Card Parameters

ParameterTypeMandatoryDescription
currency-idIntegerYesThe country currency code of a currency.
country-idIntegerYesThe CellPoint Digital-specific country code, which is made available to merchants on request.
tokenStringNoThe base64 encoded cryptogram for a third-party wallet such as Apple Pay.
hmacStringNoThe 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 below.

Note: CELLPOINT DIGITAL provides the salt value to merchants.

Conditional Parameters are mandatory if parameters are provided in the request.

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.

Message Authentication Code

The Message Authentication Code (MAC) in hmac is calculated by creating a sha-512 hash comprising the following input fields in the listed order:

ParameterRequired
clientidYes
orderidYes
amountYes
countryYes
mobileConditional
mobile-countryConditional
emailConditional
deviceidConditional
saltYes

Address Parameters

ParameterTypeMandatoryDescription
country-idIntegerYesThe CellPoint Digital-specific country code, which is made available to merchants on request.
full-nameStringYesThe full name of a customer.
streetStringYesThe full address of a customer with street name and street number.
postal-codeStringYesThe postal code of a customer.
cityStringYesThe city in which a customer resides.
stateStringNoThe state in which a customer resides. Customers enter this parameter only if their country of residence is divided onto states.
country-idIntegerYesThe CellPoint Digital-specific country code, which is made available to merchants on request.

Client Information Parameters

ParameterTypeMandatoryDescription
languageStringYesThe language that Velocity uses as default when translating the payment pages.

Note: Velocity language codes are based upon the ISO- 639-1 standard.

Refer to https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for details.
versionStringYesThe version of an API or application that sends the request.
platformStringYesThe platform from which the request is sent. For example, web, iOS, Android, B2B, and B2C.
mobile operator-idIntegerYesThe ID of a customer’s mobile network operator. CellPoint Digital recommends including this parameter in the request to ensure Velocity correctly interacts with the operator.
emailStringNoThe 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.

Authorize Response Parameters

The Authorize Response parameters when integrating Apple Pay with Velocity API are listed in the table below.

ParameterTypeMandatoryDescription
StatusStringYesDescribes the status code.
CodeIntegerYesStatus code for the authorizing processes.

Transaction Callback Request

The transaction status along with additional transaction information is posted to the callback URL configured for a merchant.

There are two callback requests posted to the URL where the status codes indicate the following:

CodeDescription
Invalid amountFor example, 0.01.
Missing mandatory request fieldFor example, element 'card': The attribute 'type-id' is required but missing.

The following parameters are sent in the callback:

FieldRequiredDescription
mpoint-idYesThis is the transaction/@id generated during initialize step.
session-idYesInternal session ID.
orderidYesThis is the transaction/@order-no in the initialize request, like PNR.
statusYesTransaction status code indicates successful or failure.
mobileYesIf present in the transaction requests, same will be returned.
amountYesTransaction amount.
FeeYesDefault is 0.
currencyYesTransaction code.
languageYesIf present in the transaction requests, same will be returned.
operatorYesIf present in the transaction requests, same will be returned.

Error Scenarios and Status Codes

The error scenarios and corresponding status codes for integrating Apple Pay with Velocity API are listed in the tables below.

Errors Scenarios

ScenarioStatus codeDescription
Invalid amount51For example, 0.01.
Missing mandatory request field400For example, element 'card': The attribute 'type-id' is required but missing.

Status Codes

CodeDescription
2000 and 2001Transaction successful.
2010Transaction failed.
4021Session failed; maximum attempts exceeded.
4030Session successfully completed.
4031Session partially completed.
4021Session failed or declined.