1. Introduction

1.1 About CellPoint Digital

CellPoint Digital (CPD) is a Payment Orchestration Platform (POP) pioneer, enabling merchants to adopt multi-acquirer payment models that open up new opportunities for growth. We help merchants meet customer expectations of a flexible, frictionless checkout with the payment methods they want to use, no matter where they are in the world.

With 400+ payment methods in our ecosystem, CellPoint Digital increases digital revenue while reducing payment costs, total cost of ownership, and time to market. A fintech leader in payment innovation and expanding rapidly into multiple markets, our mission is to help unify and accelerate our customers’ digital transactions.

We are a PCI DSS certified organization.

1.2 About Velocity POP

CellPoint Digital’s Velocity POP simplifies payment processing across all digital channels while handling PCI DSS compliance through a variety of integration options. Its growing payment ecosystem accommodates several global and local acquiring banks, PSPs, card schemes, alternative payment methods, and offline payment methods.

Velocity also offers business services such as stored cards, pay-by-link, split payments, multi-currency pricing, intelligent routing, recurring, and installments payment out of the box.

2. Scope of the Document

The document helps you integrate Apple Pay with your web channel or native app. The document is a sub-set of the CellPoint Digital Velocity API Integration Guide, which can be made available on request.

3. Glossary of Terms

The terms used in the document are defined in the table below.

Terms	Description
Merchant	Any business who sells goods or services and accepts payments from customers
Customers	Those who want to buy goods and services from merchants
PSP	Payment Service Provider
CellPoint Digital	CellPoint Digital
MSISDN	Mobile Station International Subscriber Directory Number
MAC	Message Authentication Code
POP	Payment Orchestration Platform
HPP	Hosted Payment Page
B2B	Business to Business
B2C	Business to Consumer
SDK	Software Development Kit

4. Integration Prerequisites

The Apple Pay integration prerequisites are listed in the table below:

Owner	Owner Responsibilities	Details
CellPoint Digital	Client onboarding and configuration and merchant onboarding with Apple	Client setup - account and clientid API Authorization Credentials Configure redirect URLs for successful and failed transactions API version Supported Country-id list Gateway ID: cellpointmobile
Merchant / Apple	Production validation by Apple	Merchant to contact Apple for validating - web integration merchantid as provided by Apple once production review is completed for merchant app or web integration Provide Merchant and Payment certificate Request production access

5. Availability

Where your business is located dictates your ability to accept Apple Pay. Most merchants based in the following regions – contingent on their processing settings – can accept Apple Pay transactions from eligible customers with the indicated card types:

APAC - Visa, Mastercard, American Express*
Australia - Visa, Mastercard, American Express*
Canada - Visa, Mastercard, American Express*
Europe - Visa, Mastercard, American Express*
New Zealand - Visa, Mastercard, American Express*
United States - Visa, Mastercard, American Express, Discover

*To be eligible to accept Apple Pay with American Express in this region, you must be processing with your own Amex account.

Customer Availability

Device requirements

To pay with Apple Pay, customers must have devices with the following specifications

For in-app purchases:

iOS 8+
Touch ID or Face ID

For mobile web purchases:

iOS 8+
Touch ID or Face ID

For desktop web purchases:

An iPhone, iPad, Apple Watch, or Mac that can authorize the payment
macOS Sierra 10.12+
Safari

6. API Specifications – Payments

6.1 Authentication and Security Management

All API requests must be made through HTTPS. You must authenticate all requests by using the HTTP Authorization header. The POP API header value format is as follows:

Use HTTP basic authentication to authenticate the request.
Specify the auth-parameter, where the overall parameter value is provided in the form is
x-cpm-sec-token.

Note: x-cpm-sec-token is a unique value that you generate for a unique request. Velocity uses this value to verify if a request is submitted multiple times. This value must be a valid UUID (Universally Unique Identifier), with a canonical format using hexadecimal text with inserted hyphen characters. You can consult CELLPOINT DIGITAL support to check if this is enabled for your account.

The following is an example of parameters in HTTP header section:

x-cpm-sec-token- 6lutO0jd0h1YjlHqjAn6cjKYF5n2ZJjp%2fDNk08IGKS0%3d

To integrate Apple Pay with your application, complete the following steps:

Initialize payment using mpoint/initialize-payment.
Invoke Pay API call to retrieve the session for the Apple Pay Payment
Authorize payment using /mpoint/authorize-payment.

Note: You must Process Response of initialize payment to complete the integration process.

Note: This document details the API flow for the mobile side of the integration.
You may be required to refer to the CellPoint Digital Velocity - iOS SDK - Integration Guide.

6.2 Apple Pay Integration

Before you start the API integration, you must follow the Apple Web Integration checklist and branding guidelines as follows:

7. Initialize Payment

You can invoke the initialize-payment API to initiate a new payment transaction using Velocity POP. It returns the required transaction information and merchant configuration for the payment to be processed successfully. If you have already integrated with CellPoint Digital Velocity POP APIs, you do not require any additional setup to generate the request. However, you must be able to process the response received during the integration to retrieve the response’s Apple Pay configuration in addition to processing other payment methods.

Note: For details about the initialize-payment API, refer to theCellPoint Digital Velocity API Integration Guide, section Initialize payment.

You can access the API from the following path:

End point	[ VELOCITY URL]/mpoint/initialize-payment
Format/Content Type	text/xml
Authentication	HTTP basic access authentication

7.1 Initialize Request

The following is an example of the initialize payment request:

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<initialize-payment account="[integer]" client-id="[integer]">
		<transaction order-no="CPM1601976034055" type-id="[integer]" >
			<amount currency-id="[integer]" country-id="[integer]">100</amount>
		</transaction>
		<client-info language="en" app-version="1.43" sdk-version="1.43" version="1.43" platform="HTML5">
			<mobile operator-id="[integer]" country-id="200">[mobile number]</mobile>
			<email>[email]</email>
			<customer-ref>[customer-ref]</customer-ref>
		</client-info>
	</initialize-payment>
</root>

The Initialize Request parameters are listed in the table below:

Parameter

Type

Mandatory

Description

Parameters for Initializing Payments

client-id

Integer

Yes

The unique ID configured for a merchant on the Velocity POP.

productid

Integer

The product of a merchant. For example, ticket and insurance.

Currency-id

Integer

The currency configured for a country. It depends on the configuration available with Velocity.

account

Integer

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

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

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

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

The URL which is used for single sign-on (SSO) authentication if provided by an external system.

session-id

Integer

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

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

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

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

The Message Authentication Code. It 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

Note: CELLPOINT DIGITAL 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.

orders

Object

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.

Merchant Information Parameters

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

The CellPoint Digital-specific country code, which is provided on request.

operator-id

Integer

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.

String

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

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.

7.2 Initialize Response

The response from Velocity server has information about the transaction such as transaction ID and amount, along with the configured payment methods or card types. The merchants must call this API when a customer checks out.

The initialize payment response can be divided into the following chunks:
• Merchant configuration
• Transaction information
• Card information

The following fields from the initialize payment response are required to call the /mpoint/pay and /mpoint/authorize API:

Field

Type

Description

transaction/@id

xs:positiveInteger

A unique transaction ID generated for the initialize payment request. This identifies a transaction within CellPoint Digital systems.

cards/card/@type-id

xs:positiveInteger

A unique ID that identifies the payment methods configured.

type-id = 41 indicates the internal id defined for Apple Pay™ payment method.

7.2.1 Initialize response for Apple Pay Response for a Web Channel

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <client-config account="[integer]" auto-capture="false" id="[integer]" mode="[integer]" store-card="[integer]">
    <name>Test</name>
    <callback-url>[merchant URL for callback]</callback-url>
    <accept-url />
  </client-config>
  <transaction auto-capture="true" eua-id="[integer]" id="[integer]" language="en" mode="1" order-no="" type-id="[integer]">
    <amount country-id="[integer]" currency="DKK" format="{PRICE} {CURRENCY}" symbol="">10025</amount>
    <mobile country-id="[integer]" operator-id="[integer]">30206172</mobile>
    <callback-url>[CALLBACK URL]</callback-url>
    <accept-url />
  </transaction>
 
    <session id="6143" total-amount="1" type="1">
        <amount alpha2code="US" alpha3code="USA" code="840" country-id="200" currency="" currency-id="0" format="{CURRENCY}{PRICE}" symbol="$">10025</amount>
    </session>
    <wallets>
<card cvc-length="-1" cvcmandatory="false" dcc="false" enabled="true" id="15" installment="0" max-length="-1" min-length="-1" payment-type="3" preferred="false" presentment-currency="false" processor-type="3" psp-id="-1" state-id="1" type-id="15">
<name>Apple Pay</name>
<prefixes>
<prefix id="164">
<min>-1</min>
<max>-1</max>
</prefix>
</prefixes>
<url method="overlay" />
<head>&lt;script type='text/javascript'&gt; var debug = false; var countryCode = "GB"; var currencyCode = "GBP"; var merchantIdentifier = 'merchant.mytest.applepay.sandbox'; var displayName ="Holidays"; var totalAmount = "152"; var supportedNetword = ['VISA','DISCOVER','MASTERCARD','AMEX']; var supportedNetwork = ['VISA','DISCOVER','MASTERCARD','AMEX']; &lt;/script&gt; &lt;script type="text/javascript" src="https://myurl/js/applepay.js"&gt;&lt;/script&gt; &lt;style&gt; #applePay{width:150px;height:50px;display:none;border-radius:5px;background-image:-webkit-named-image(apple-pay-logo-white);background-position:50% 50%;background-color:#000;background-size:60%;background-repeat:no-repeat} &lt;/style&gt;</head>
<body>&lt;button type="button" id="applePay"&gt;&lt;/button&gt;</body>
<auth-token>Auth-Token</auth-token>Apple Pay
</card>
    </wallets>
</root>

7.2.2 Initialize response for Apple Pay Response for the Native APP Channel

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <client-config account="[integer]" auto-capture="false" id="[integer]" mode="[integer]" store-card="[integer]">
    <name>Test</name>
    <callback-url>[merchant URL for callback]</callback-url>
    <accept-url />
  </client-config>
  <transaction auto-capture="true" eua-id="[integer]" id="[integer]" language="en" mode="1" order-no="" type-id="[integer]">
    <amount country-id="[integer]" currency="DKK" format="{PRICE} {CURRENCY}" symbol="">10025</amount>
    <mobile country-id="[integer]" operator-id="[integer]">30206172</mobile>
    <callback-url>[CALLBACK URL]</callback-url>
    <accept-url />
  </transaction>
    <session id="6143" total-amount="1" type="1">
        <amount alpha2code="US" alpha3code="USA" code="840" country-id="200" currency="" currency-id="0" format="{CURRENCY}{PRICE}" symbol="$">10025</amount>
    </session>
    <wallets>
        <card id="15" type-id="15" psp-id="52" min-length="-1" max-length="-1" cvc- length="-1" state-id="1" payment-type="3" preferred="false" enabled="true" processor-type="3" installment="0" cvcmandatory="false" dcc="false" presentment-currency="false">
         <name>Apple Pay</name>
         <prefixes><prefix><min>0</min><max>0</max></prefix></prefixes>
         <url method="overlay"/>
         <hidden-fields>
         <card-brands>'MASTERCARD','VISA','DISCOVER','AMEX'</card-brands>
         </hidden-fields>
         <auth-token>Auth-Token</auth-token>Apple Pay
         </card>
    </wallets> 
</root>

The Initialize Response parameters are listed in the table below:

Parameter

Type

Mandatory

Description

version

Integer

Yes

The version of the API or application that sends the request.

Client-config Parameters

account

Integer

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

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.

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.

name

String

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.

Transaction Parameters

auto-capture

Boolean

Yes

Shows if you have enabled auto-capture.

eua-id

Integer

A parameter which identifies if the API to be called is for saving account or saving card.

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

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

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

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

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.

Note: The wallets, APM, and gateway have the same parameters as the card parameters in this table.

7.3 Process Response

To ensure seamless Apple Pay configuration with your web or mobile browser, you need to process the response that you receive from the Velocity server.

7.3.1 Process Initialize Response on the Web

To process the initialize response on the web, complete the following steps:

First check following perquisite, then only we can show the Apple Pay payment option:
a. iPhone
i. iPhone models with Face ID
ii. iPhone models with Touch ID, except iPhone 5s
b. iPad
i. iPad Pro, iPad Air, iPad, and iPad mini models with Touch ID or Face ID
c. Laptop
i. Mac models with Touch ID
ii. Mac models introduced in '12 or later with an Apple Pay-enabled iPhone/Apple Watch
iii. Mac computers with Apple silicon that are paired with a Magic Keyboard with Touch ID
d. Web only in Safari (Apple Pay web)
In initial response, we receive the head and body. In the body tag, it contains the Apple Pay button and, in the head tag, it contains the required script for Apple Pay. We need to load both data based on the UI design.
We need to implement the following methods to receive the call-back from the Apple Pay Events:
InitPay - When we receive the callback in this method, we receive the URL which we need to pass in the Pay API call. Refer to 7.1. On success of 7.1, we need to return that response (session info). This object is received in the JSON format and we need to return as it as part of the return object of this initPay method.
Add both the body and the head script received in the card element to the head of the HTML page.
After adding the script to the head of HTML page, handle a callback method after the Apple Pay™ UI interaction is complete. This callback method captures the card token generated by Apple Pay™.

Sample Checkout Page for a Web Channel

Sample Checkout Page for an Application

onWalletProcess (Payment, Network)

The onWalletProcess (payment, network) function is called every time your customer selects a card from Apple Pay wallet. Implement this function as shown in the following sample code: As per requirement different type of method need to implement

OnWalletProcess(payment,network)
or
OnWalletProcess(payment,network,billingaddress)

7.3.2 Process Response of a Customer's Apple Pay Card Selection on the SDK

After your customer selects a card from the Apple Pay wallet, they need to invoke the Pay API call (Please refer to the CellPoint Digital Velocity - iOS SDK - Integration Guide).

8. Pay

The Pay request is used to retrieving the wallet related information. The API is available at the following path:

End point	[Velocity URL]/mpoint/pay
Format	text/xml
Authentication	HTTP basic access authentication

8.1 Pay Request

The pay request will be different for both the mobile and web channel and, depending on the channel, we need to send the respective parameter.

8.1.1 Apple Pay Request for a Web Channel

When we process the Apple Pay web transaction, we need to send the session URL in the token. In this session URL and when user clicks the button, we receive this URL from the Apple Pay wallet.

<?xml version="1.0" encoding="UTF-8"?>
<root>
<pay client-id="10064" account="100640">
<transaction id="9953806" store-card="false">
<card type-id="15">
<amount country-id="200" currency-id= "840">100</amount>
<token>https://apple-pay-gateway-cert.apple.com/paymentservices/startSession</token>
</card>
</transaction>
<client-info language="us" version="1.00" platform="HTML5/1.00"/>
</pay>
</root>

In web channel request, we need to send the additional header parameter and the host URL in the header as the key name reference. Check the example below.

Refer:https://www.mywebsite.com

8.1.2 Apple Pay™ Request for a Mobile Channel

<?xml version="1.0" encoding="UTF-8"?>
<root>
<pay account="100691" client-id="10069">
<transaction store-card="false" id="10044528">
<card type-id="15">
<amount country-id="200" currency-id="840">22398</amount>
</card>
</transaction>
<client-info version="10.02" app-version="10.02" sdk-version="2.3.1" language="gb" platform="iOS/15.5">
<device-id>087E575D-92BD-483A-B1AA-C4F9CDCA5674</device-id>
</client-info>
</pay>
</root>

The Authorize Request parameters are listed in the table below.

Parameter

Type

Mandatory

Description

Authorize-payment Parameters

account

Integer

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

Integer

Yes

The ID of the transaction.

type-id

Integer

Yes

A unique transaction identification number.

card network

Enum

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

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

The base64 encoded cryptogram or session URL received from a third-party wallet such as Apple Pay™.

hmac

String

The Message Authentication Code (MAC). It 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

Note: CELLPOINT DIGITAL provides the salt value to merchants.

Address Parameters

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

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

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.

String

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.

9. 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

9.1 Authorize Request

The payment authorize request is initiated using the payment token returned by Apple 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 Apple Pay after base-64 encode: paymentMethodToken:token:

eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoiQWNRd0FFeWhSYzdHdWJleUVHOUJnWEdjNktkaTJ4RjMxazJSMTRqNGZxTUtQRHA4S1VyT0FTNVFFRTIxT1U2a0d6TFBzRVAwbUw5MGR1NExqbVNjWFRFb1ZqVk81b1dzejVaTC90ZllSOEpJTmRVTUJZM0g2UnNqeFFQZXdXLzYzUDVwdDN0eTZXUjl5dnN0RGpoMHliR01vZVVSZnZLTmtTTy9KaDBNQVpnRmcxRXozS0huZHJiRi9UeDBvZXJBZmNxYXdZVGZyMUtQN2ozR3FBRm5Tam1DNFhUTUFSVnJSNXdYUklCYzZFYXBEOE43blhiTXlDem03R2ZxNGFqWk5ocGl3djBkU1N2OE9KNkRwWG40WTQ2Y0toeUlPYXZraE5qcGdxZGV2SnI4ekZIZ0UxWENZODBVMUNoWTd4dGhqNWNqdVFYYVdkbVFDbXJKdCtkQlYxMXg1T3UyNngrNWNYSk9GL1lPV21QQkpSeWhVWUxhTXhaL05jTERXUVBEQTgvRTJzTWRjSlFaQzdtMWhZWDhvZG93dmhTOTJBWmJMUzFHRDZXd1BmZTYiLCJzaWduYXR1cmUiOiJNSUFHQ1NxR1NJYjNEUUVIQXFDQU1JQUNBUUV4RFRBTEJnbGdoa2dCWlFNRUFnRXdnQVlKS29aSWh2Y05BUWNCQUFDZ2dEQ0NBK013Z2dPSW9BTUNBUUlDQ0V3d1FVbFJuVlEyTUFvR0NDcUdTTTQ5QkFNQ01Ib3hMakFzQmdOVkJBTU1KVUZ3Y0d4bElFRndjR3hwWTJGMGFXOXVJRWx1ZEdWbmNtRjBhVzl1SUVOQklDMGdSek14SmpBa0JnTlZCQXNNSFVGd2NHeGxJRU5sY25ScFptbGpZWFJwYjI0Z1FYVjBhRzl5YVhSNU1STXdFUVlEVlFRS0RBcEJjSEJzWlNCSmJtTXVNUXN3Q1FZRFZRUUdFd0pWVXpBZUZ3MHhPVEExTVRnd01UTXlOVGRhRncweU5EQTFNVFl3TVRNeU5UZGFNRjh4SlRBakJnTlZCQU1NSEdWall5MXpiWEF0WW5KdmEyVnlMWE5wWjI1ZlZVTTBMVkJTVDBReEZEQVNCZ05WQkFzybFBVeUJUZVhOMFpXMXpNUk13RVFZRFZRUUtEQXBCY0hCc1pTQkpibU11TVFzd0NRWURWUVFHRXdKVlV6QlpNQk1HQnlxR1NNNDlBZ0VHQ0NxR1NNNDlBd0VIQTBJQUJNSVZkKzNyMXNleUlZOW8zWENRb1NHTng3QzlieXdvUFlSZ2xkbEs5S1ZCRzROQ0R0Z1I4MEIrZ3pNZkhGVEQ5K3N5SU5hNjFkVHY5SktKaVQ1OER4T2pnZ0lSTUlJQ0RUQU1CZ05WSFJNQkFmOEVBakFBTUI4R0ExVWRJd1FZTUJhQUZDUHlTY1JQaytUdkorYkU5aWhzUDZLNy9TNUxNRVVHQ0NzR0FRVUZCd0VCQkRrd056QTFCZ2dyQmdFRkJRY3dBWVlwYUhSMGNEb3ZMMjlqYzNBdVlYQndiR1V1WTI5dEwyOWpjM0F3TkMxaGNIQnNaV0ZwWTJFek1ESXdnZ0VkQmdOVkhTQUVnZ0VVTUlJQkVEQ0NBUXdHQ1NxR1NJYjNZMlFGQVRDQi9qQ0J3d1lJS3dZQkJRVUhBZ0l3Z2JZTWdiTlNaV3hwWVc1alpTQnZiaUIwYUdseklHTmxjblJwWm1sallYUmxJR0o1SUdGdWVTQndZWEowZVNCaGMzTjFiV1Z6SUdGalkyVndkR0Z1WTJVZ2IyWWdkR2hsSUhSb1pXNGdZWEJ3YkdsallXSnNaU0J6ZEdGdVpHRnlaQ0IwWlhKdGN5QmhibVFnWTI5dVpHbDBhVzl1Y3lCdlppQjFjMlVzSUdObGNuUnBabWxqWVhSbElIQnZiR2xqZVNCaGJtUWdZMlZ5ZEdsbWFXTmhkR2x2YmlCd2NtRmpkR2xqWlNCemRHRjBaVzFsYm5SekxqQTJCZ2dyQmdFRkJRY0NBUllxYUhSMGNEb3ZMM2QzZHk1aGNIQnNaUzVqYjIwdlkyVnlkR2xtYVdOaGRHVmhkWFJvYjNKcGRIa3ZNRFFHQTFVZEh3UXRNQ3N3S2FBbm9DV0dJMmgwZEhBNkx5OWpjbXd1WVhCd2JHVXVZMjl0TDJGd2NHeGxZV2xqWVRNdVkzSnNNQjBHQTFVZERnUVdCQlNVVjl0djFYU0Job21KZGk5K1Y0VUg1NXRZSkRBT0JnTlZIUThCQWY4RUJBTUNCNEF3RHdZSktvWklodmRqWkFZZEJBSUZBREFLQmdncWhrak9QWdOSkFEQkdBaUVBdmdsWEgrY2VIbk5iVmVXdnJMVEhMK3RFWHpBWVVpTEhKUkFDdGg2OWIxVUNJUURSaXpVS1hkYmRickYwWURXeEhyTE9oOCtqNXE5c3ZZT0FpUTNJTE4ycVl6Q0NBdTR3Z2dKMW9BTUNBUUlDQ0VsdEw3ODZtTnFYTUFvR0NDcUdTTTQ5QkFNQ01HY3hHekFaQmdOVkJBTU1Fa0Z3Y0d4bElGSnZiM1FnUTBFZ0xTQkhNekVtTUNRR0ExVUVDd3dkUVhCd2JHVWdRMlZ5ZEdsbWFXTmhkR2x2YmlCQmRYUm9iM0pwZEhreEV6QVJCZ05WQkFvTUNrRndjR3hsSUVsdVl5NHhDekFKQmdOVkJBWVRBbFZUTUI0WERURTBNRFV3TmpJek5EWXpNRm9YRFRJNU1EVXdOakl6TkRZek1Gb3dlakV1TUN3R0ExVUVBd3dsUVhCd2JHVWdRWEJ3YkdsallYUnBiMjRnU1c1MFpXZHlZWFJwYjI0Z1EwRWdMU0JITXpFbU1DUUdBMVVFQ3d3ZFFYQndiR1VnUTJWeWRHbG1hV05oZEdsdmJpQkJkWFJvYjNKcGRIa3hFekFSQmdOVkJBb01Da0Z3Y0d4bElFbHVZeTR4Q3pBSkJnTlZCQVlUQWxWVE1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRThCY1JoQm5YWklYVkdsNGxnUWQyNklDaTc5NTdyazNnamZ4TGsrRXpWdFZtV3pXdUl0Q1hkZzBpVG51NkNQMTJGODZJeTNhN1puQyt5T2dwaFA5VVJhT0I5ekNCOURCR0JnZ3JCZ0VGQlFjQkFRUTZNRGd3TmdZSUt3WUJCUVVITUFHR0ttaDBkSEE2THk5dlkzTndMbUZ3Y0d4bExtTnZiUzl2WTNOd01EUXRZWEJ3YkdWeWIyOTBZMkZuTXpBZEJnTlZIUTRFRmdRVUkvSkp4RStUNU84bjVzVDJLR3cvb3J2OUxrc3dEd1lEVlIwVEFRSC9CQVV3QXdFQi96QWZCZ05WSFNNRUdEQVdnQlM3c042aFdET0ltcVNLbWQ2K3ZldXYyc3NrcXpBM0JnTlZIUjhFTURBdU1DeWdLcUFvaGlab2RIUndPaTh2WTNKc0xtRndjR3hsTG1OdmJTOWhjSEJzWlhKdmIzUmpZV2N6TG1OeWJEQU9CZ05WSFE4QkFmOEVCQU1DQVFZd0VBWUtLb1pJaHZkalpBWUNEZ1FDQlFBd0NnWUlLb1pJemowRUF3SURad0F3WkFJd09zOXlnMUVXbWJHRyt6WERWc3Bpdi9RWDdka1BkVTJpanI3eG5JRmVRcmVKK0pqM20xbWZtTlZCRFkrZDZjTCtBakF5TGRWRUliQ2pCWGRzWGZNNE81Qm4vUmQ4TENGdGxrL0djbW1DRW05VStIcDlHNW5MbXdtSklXRUdtUThKa2gwQUFER0NBWWN3Z2dHREFnRUJNSUdHTUhveExqQXNCZ05WQkFNTUpVRndjR3hsSUVGd2NHeHBZMkYwYVc5dUlFbHVkR1ZuY21GMGFXOXVJRU5CSUMwZ1J6TXhKakFrQmdOVkJBc01IVUZ3Y0d4bElFTmxjblJwWm1sallYUnBiMjRnUVhWMGFHOXlhWFI1TVJNd0VRWURWUVFLREFwQmNIQnNaU0JKYm1NdU1Rc3dDUVlEVlFRR0V3SlZVd0lJVERCQlNWR2RWRFl3Q3dZSllJWklBV1VEQkFJQm9JR1RNQmdHQ1NxR1NJYjNEUUVKQXpFTEJna3Foa2lHOXcwQkJ3RXdIQVlKS29aSWh2Y05BUWtGTVE4WERUSXpNREV6TURFME16RXhORm93S0FZSktvWklodmNOQVFrME1Sc3dHVEFMQmdsZ2hrZ0JaUU1FQWdHaENnWUlLb1pJemowRUF3SXdMd1lKS29aSWh2Y05BUWtFTVNJRUlJUGpmOU9aMFRwQjlhNmtId3I4YXRtdXN6MXF4Nk5KS0RrTDhVRWp3cmJoTUFvR0NDcUdTTTQ5QkFNQ0JFWXdSQUlnZjZLZmExNytEeW8zZlY0c1Y3Z1hpRDV1S25ieWdRSVUzd0M5QWQ1azF0WUNJQThwQ3FZakxBNzhaNkhuWkhSVW9HSWJrcDBOb1IyMTlCNXRuY3FmcDlFL0FBQUFBQUFBIiwiaGVhZGVyIjp7ImVwaGVtZXJhbFB1YmxpY0tleSI6Ik1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRVVWdStobVpaT1lOUTgxbGEySm1saWhPbnFmMEU3VWZOOENmM2ZobEp6Sy9TSzJoWDlIZGVwVDZoMjZBczJGSW5pQVhMN0c4elNjQW1LQVg2Q1ZTRmRnPT0iLCJhcHBsaWNhdGlvbkRhdGEiOiJlM2IwYzQ0Mjk4ZmMxYzE0OWFmYmY0Yzg5OTZmYjkyNDI3YWU0MWU0NjQ5YjkzNGNhNDk1OTkxYjc4NTJiODU1IiwicHVibGljS2V5SGFzaCI6IiswSVBCODBLa2JwOUxnTlNTSkROemFMVkdIYXdXSEIyRG9HYjFJay8yTjg9IiwidHJhbnNhY3Rpb25JZCI6ImUxZDBiYWNmYTFkNjFkY2YyYTc1MzhkNmM1ZDFlNjE1YjdlMGU4ZTJmM2YzOWU5N2JiMzI3NGQ5MGRhMWFjYjIifX0=

The following authorize payment request is an example of making payment:

<?xml version="1.0" encoding="UTF-8"?>
<root>
<authorize-payment account="[integer]" client-id="[integer]" >
<transaction type-id="40" id="[CELLPOINT DIGITAL-TXNID]">
<card network="visa" type-id="15">
   <address country-id="200">
     <first-name>Harish</first-name>
     <last-name>Chandra</last-name>
     <street>1131 Meadow Creek Dr.</street>
     <postal-code>75086</postal-code>
     <city>Irving</city><state>KY</state>
     <contact-details>
     </contact-details>
   </address>
<amount currency-id="[integer]" country-id="[integer]">100</amount>
<token>[token]</token>
</card>
</transaction><client-info version="10.02" app-version="10.02" sdk-version="2.3.1" language="gb" platform="iOS/15.5"><device-id>087E575D-92BD-483A-B1AA-C4F9CDCA5674</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

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

Integer

Yes

The ID of the transaction.

type-id

Integer

Yes

A unique transaction identification number.

card network

Enum

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

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

The base64 encoded cryptogram for a third-party wallet such as Apple Pay™.

hmac

String

The Message Authentication Code (MAC). It 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

Note: CELLPOINT DIGITAL provides the salt value to merchants.

Address Parameters

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

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

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.

String

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.

9.2 Authorize Response

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.

10. Transaction Call Back 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	Mandatory	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.

Note: For details about transaction call back, refer to the Velocity Callback Request to the Merchant Integration Guide.

11. Error Scenarios and Status Codes

The error scenarios and corresponding status codes are listed in the tables below.

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.

Note: For details about status codes, refer to the CellPoint Digital Velocity API Integration Guide - Status Codes

12. Java Script Interfaces

We need to implement the below methods in the front end for clients who are using Apple Pay. CPD sends the callback in this method or requests data as the return parameter in this method.

We need to use the following method or attribute name for showing the applepay btn:

You can set the element name “applepay” and the CPD hides it if the device/browser does not have the capability of Apple Pay.
The payment flow related method initPay(valURL)
- You will receive the URL which you need to pass in the pay API call.
- We have two options for this flow as follows:
  - For clients who want the billing information, we need to the enable below method:
    onWalletProcess(paymentObj, paymentToken.paymentMethod.network, billingAddress)
  - For clients who do not want the billing information, we need to enable the below method:
    onWalletProcess(Jpayment, paymentToken.paymentMethod.network)

13. Frequently Asked Questions

How does Apple Pay work?
Apple Pay encrypts any credit/debit cards added to an Apple Wallet on supported Apple devices. Apple Pay assigns a device-specific tokenized credit card number called a DPAN that CellPoint Digital will use to process transactions.

Which currencies does Apple Pay support?
Any currencies that you can process on your Apple Pay-supported processor(s).

What are the fees on Apple Pay transactions?
There will be no additional standard fees beyond the standard fees described in your processing agreement with CellPoint Digital. Volume pricing is available.

Which card types are supported?
Visa, MasterCard, American Express and Discover are supported for Apple Pay. For additional information on customer availability, please click here.

Who is the merchant of record?
As the seller, you will be the merchant of record for the purchase.

How will I identify Apple Pay payments in the Control Panel?
Apple Pay cards will appear as a new payment instrument with its own associated logo.

How are disputes handled?
The payment instruments behind Apple Pay are credit or debit cards, and so chargebacks will look and behave the same as any other credit card chargeback on your account.

Is recurring billing supported?
Yes, Apple Pay cards can be used to process recurring transactions.

Is vaulting supported?
Apple Pay cards can be vaulted, but we recommend vaulting only for split shipment and recurring transactions, as Apple Pay cryptograms cannot be reused.

How does fraud checking (AVS/CVV) work with Apple Pay?
Since Apple uses a tokenization system to encrypt card information and reduce the risk of fraud, CVV and AVS are not necessary for use with Apple Pay.