Initialize Payment

Suggest Edits

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:

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

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.

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.

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

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.

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

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

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:

  1. 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)
  2. 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.
  3. 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.
  4. Add both the body and the head script received in the card element to the head of the HTML page.
  5. 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

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

Updated 12 months ago