Initialize Request Parameters

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

Parameters for Initializing Payments

Parameter	Type	Mandatory	Description
client-id	Integer	Yes	The unique ID configured for a merchant on the Velocity POP.
productid	Integer	No	The product of a merchant. For example, ticket and insurance.
Currency-id	Integer	No	The currency configured for a country. It depends on the configuration available with Velocity.
account	Integer	No	The 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-no	String	Yes	The 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-url	String	No	The 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-url	String	No	The 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-url	String	No	The 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-url	String	No	The URL which is used for single sign-on (SSO) authentication if provided by an external system.
session-id	Integer	No	The 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-type	String	No	The product type used to select the payment methods to be displayed or acquirer to be selected. The typical values include TICKET and INSURANCE.
type-id	Integer	Yes	The type of a transaction. For example, 40 indicates a mobile application purchase and 30 indicates a web purchase.
amount	Integer	Yes	The 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-id	Integer	Yes	The CELLPOINT DIGITAL-specific country code, which is available on request only.
callback-url	String	No	The 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-token	String	No	A unique token sent to the specified auth-url to authenticate customer when they pay with a stored card and use single sign-on.
HMAC	String	No	The 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.
orders	Object	No	The 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:

Parameter	Required
clientid	Yes
orderid	Yes
amount	Yes
country	Yes
mobile	Conditional
mobile-country	Conditional
email	Conditional
deviceid	Conditional
salt	Yes

Merchant Information Parameters

Parameter	Type	Mandatory	Description
platform	String	Yes	The platform from which the request is sent. For example, web, iOS, Android, B2B, and B2C.
sdk-version	Integer	Yes	The software development kit (SDK) version used.
version	String	Yes	The version of the application programming interface (API) or application that sends the request.
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.
mobile	Integer	Yes	The 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-id	Integer	No	The CellPoint Digital-specific country code, which is provided on request.
operator-id	Integer	No	The 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.
email	String	No	The 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-ref	String	No	The 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.

Parameter	Type	Mandatory	Description
version	Integer	Yes	The version of the API or application that sends the request.

Client-config Parameters

Parameter	Type	Mandatory	Description
account	Integer	No	The 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-capture	Boolean	Yes	Shows if you have enabled auto-capture.
mode	Integer	No	A parameter used in the SDK to switch between production and staging environment.
store-card	Integer	Yes	It defines the type of configuration merchants have done to store cards. See the store-card table below.
name	String	No	The name a merchant gives to a card as configured in Velocity.
callback-url	String	Yes	The 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-url	String	Yes	The 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.

Integer	Meaning
0	Cards are not stored.
1	INVALID!
2	Stored cards are available for specific accounts only.
3	Use stored cards only and make them available for specific accounts only. The e-money based prepaid account is unavailable.
4	Stored cards are available for all accounts. Note: Velocity must be hosted by a Master Merchant.

Transaction Parameters

Parameter	Type	Mandatory	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 unique ID of a merchant for Velocity platform.
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	String	Yes	The 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-id	Integer	Yes	The type of application used for a transaction. For example, 40 indicates a mobile app purchase and 30 indicates a web purchase.
country-id	Integer	Yes	The CellPoint Digital-specific country code, provided to merchants on request.
currency	String	Yes	The format of currency used for a transaction.
format	String	Yes	The format in which price is presented.
mobile country-id	Integer	Yes	The CellPoint Digital-specific country code, which is made available to merchants on request.
operator-id	Integer	Yes	The 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

Parameter	Type	Mandatory	Description
id	Integer	Yes	The unique ID of a merchant for Velocity platform.
total-amount	Integer	Yes	The total amount that a customer pays for a transaction.
alpha2code	String	Yes	The three-letter alphabetic code for a currency.
alpha3code	Integer	Yes	The two-letter numeric code for a country.
code	Integer	Yes	The CellPoint Digital currency code for a country.
country-id	Integer	Yes	The CellPoint Digital-specific country code, provided to merchants on request.
currency	String	Yes	The format of currency used for a transaction.
currency-id	Integer	Yes	The currency code of a currency.
format	String	Yes	The format in which price is presented.
symbol		Yes	A symbol used to indicate the currency of a country.

Card Parameters

Parameter	Type	Mandatory	Description
cvc-length	Integer	Yes	The length of the card verification code (CVC) number on a card.
cvcmandatory	Boolean	Yes	Indicates if the CVC is mandatory for a transaction. The value can be true or false. It is used for a wallet transaction.
dcc	Boolean	Yes	Indicates if currency conversion is available. The value can be true or false.
enabled	Boolean	Yes	Shows if the card was enabled.
installment	String	No	This is no longer used in a transaction.
min-length	Integer	Yes	The minimum length of a card number.
max-length	Integer	Yes	The maximum length of a card number.
payment-type	String	Yes	The type of payment. For example, 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 PSP.
type-id	Integer	Yes	The type of application used for a transaction. For example, 40 indicates a mobile app purchase and 30 indicates a web purchase.
name	String	Yes	The 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

Parameter	Type	Mandatory	Description
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

Parameter	Type	Mandatory	Description
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: • amex • dankort • dinersclub • jcb • maestro • mastercard • visa • visaelectron • discover

Card Parameters

Parameter	Type	Mandatory	Description
currency-id	Integer	Yes	The country currency code of a currency.
country-id	Integer	Yes	The CellPoint Digital-specific country code, which is made available to merchants on request.
token	String	No	The base64 encoded cryptogram or session URL received from a third-party wallet such as Apple Pay.
hmac	String	No	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 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:

Parameter	Required
clientid	Yes
orderid	Yes
amount	Yes
country	Yes
mobile	Conditional
mobile-country	Conditional
email	Conditional
deviceid	Conditional
salt	Yes

Address Parameters

Parameter	Type	Mandatory	Description
country-id	Integer	Yes	The CellPoint Digital-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 into states.
country-id	Integer	Yes	The CellPoint Digital-specific country code, which is made available to merchants on request.

Client Information Parameters

Parameter	Type	Mandatory	Description
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 to 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. Examples: web, iOS, Android, B2B, and B2C.
mobile operator-id	Integer	Yes	The 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.
email	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.

Pay Response Parameters

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

Parameter	Type	Mandatory	Description
id	Integer	Yes	Describes the wallet ID information.
merchant-account	String	Yes	Gives the merchant ID configured/used for this transaction which we need to pass/configure for Apple Pay.
type	Integer	Yes	Gives the information for the Apple Pay (mostly required for the backend use).
head	String	No	The script is received in this node and which we need to load on the HTML DOM.
url	String	No	The URL of the provider which can be used for redirection or the overlay.
method	String	No	Tells us that this URL is an overlay or the redirection to specified URL.
session-data	String	Conditional	This 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-brands	String	No	This 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'.
name	String	No	It is optional and shares the cardholder’s name.
Auth-token	String	No	This is an auth token and is used in the security verification.
code	Integer	Yes	Shares the status code for the Pay API call.
message	String	Yes	The 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

Parameter	Type	Mandatory	Description
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

Parameter	Type	Mandatory	Description
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: • amex • dankort • dinersclub • jcb • maestro • mastercard • visa • visaelectron • discover

Card Parameters

Parameter	Type	Mandatory	Description
currency-id	Integer	Yes	The country currency code of a currency.
country-id	Integer	Yes	The CellPoint Digital-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 Apple Pay.
hmac	String	No	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 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:

Parameter	Required
clientid	Yes
orderid	Yes
amount	Yes
country	Yes
mobile	Conditional
mobile-country	Conditional
email	Conditional
deviceid	Conditional
salt	Yes

Address Parameters

Parameter	Type	Mandatory	Description
country-id	Integer	Yes	The CellPoint Digital-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 CellPoint Digital-specific country code, which is made available to merchants on request.

Client Information Parameters

Parameter	Type	Mandatory	Description
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 to 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. CellPoint Digital recommends including this parameter in the request to ensure Velocity correctly interacts with the operator.
email	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.

Authorize Response Parameters

The Authorize Response parameters when integrating Apple Pay with Velocity API 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.

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:

Code	Description
Invalid amount	For example, 0.01.
Missing mandatory request field	For example, element 'card': The attribute 'type-id' is required but missing.

The following parameters are sent in the callback:

Field	Required	Description
mpoint-id	Yes	This is the transaction/@id generated during initialize step.
session-id	Yes	Internal session ID.
orderid	Yes	This is the transaction/@order-no in the initialize request, like PNR.
status	Yes	Transaction status code indicates successful or failure.
mobile	Yes	If present in the transaction requests, same will be returned.
amount	Yes	Transaction amount.
Fee	Yes	Default is 0.
currency	Yes	Transaction code.
language	Yes	If present in the transaction requests, same will be returned.
operator	Yes	If 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

Scenario	Status code	Description
Invalid amount	51	For example, 0.01.
Missing mandatory request field	400	For example, element 'card': The attribute 'type-id' is required but missing.

Status Codes

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