Apple Pay API Integration Guide
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 |
|
Merchant / Apple |
Production validation
|
|
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 |
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 following input
fields in the listed order:
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 |
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. |
||||||||||||||||||||
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 |
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. |
||||||||||||||||||||
|
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:
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><script type='text/javascript'> 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']; </script> <script type="text/javascript" src="https://myurl/js/applepay.js"></script> <style> #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} </style></head>
<body><button type="button" id="applePay"></button></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 |
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.
|
||||||||||||
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. |
||||||||||||
Transaction Parameters |
|||||||||||||||
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
|
||||||||||||
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 |
|||||||||||||||
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 |
|||||||||||||||
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. |
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 |
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
|
||||||||||||||||||||
client-id |
Integer |
Yes |
The unique ID of a merchant. |
||||||||||||||||||||
Transaction Parameters |
|||||||||||||||||||||||
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:
|
||||||||||||||||||||
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 |
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 following
input fields in the listed order:
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. |
||||||||||||||||||||
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 |
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 |
|||||||||||||||||||||||
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 |
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. |
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:
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 |
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 |
|||||||||||||||||||||||
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:
|
||||||||||||||||||||
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 |
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 following
input fields in the listed order:
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. |
||||||||||||||||||||
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 |
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 |
|||||||||||||||||||||||
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 |
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. |
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:
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)
- For clients who want the billing information, we need to the enable below method:
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.
Updated 30 days ago