ApplePay Integration

CONFIGURATION 1

Merchant has an Apple ID and process Apple wallet at his end and sends the Apple data to Telr.

APPLE DEVELOPER ACCOUNT CONFIGURATION

Verify your merchant domain name, where will the merchant be using Apple Pay, in Apple developer account.
Create a Merchant ID (e.g. merchant.com.Telr.applepay) with Apple developer account.
Get Merchant (Payment processing) certificate from Apple developer account.
Get Merchant (session) certificate from Apple developer account.
Share #3 apple pay token processing certificate (file with extension .cer) and key (file with extension .p12) along with password if any, with Telr to update at Telr side.

File generation process:

If you need ApplePay as a payment option on your website or your application then, we will need your certificate and password to be uploaded on our system.

Please send us that.

There are two file required.

```
    Key (with extension as .p12)
```

    Certificate (with extension as .cer)

Apple merchant certificate creation -

Create a private key for CSR. private should be ECC (elliptic curve cryptography, so use ecparam) and of lentgh 256 character so use prime256v1)
openssl ecparam -out private.key -name prime256v1 -genkey
Create CSR (Certificate sigining request)with private key
openssl req -new -sha256 -key private.key -nodes -out request.csr
Upload this request.csr on Apple Dev portal to associate with Merchant Identifer. This will generate apple_pay.cer file from Apple portal.
Create .pem file from .cer
openssl x509 -inform DER -outform PEM -in apple_pay.cer -out temp.pem
generate .p12 key with privet key and .pem file.
openssl pkcs12 -export -out key.p12 -inkey private.key -in temp.pem
Run the following commands to convert them to .pem files:

openssl x509 -inform DER -outform PEM -in apple_pay.cer -out certPem.pem

 

openssl pkcs12 -in key.p12 -out privatePem.pem -nocerts -nodes

PROCESSING APPLE PAY IN WEB OR IN IOS APP

Create a Payment request with following parameters.

Currency code, country code, amount, supportedNetworks and merchantCapabilities

With payment request create an Apple Pay session.
Validate the merchant ID for the Apple Pay session.
Complete the payment method selection operation.
On successful “payment authorized” operation a token with payment data will be received. Sample Apple token variables are as below.
paymentData:: version:EC_v1,data:3O…w=,signature:MI…YX.header:: ephermeralPublicKey:MF…A==,
publickKeyHash:TM…8=,transactionId:c5…3f.paymentMethod:: dispalyName:Visa 0492, network:Visa, type:debit,transactionIdentifier:C5..93F.

Above variables to be POST to Telr with other data to Telr’s URL “https://secure.telr.comgateway/remote.json”. All required data to be sent to Telr URL are as follows. Set POST content type “application/x-www-form-urlencoded “ and do URL encode for Apple Pay data applepay_enc_paydata, applepay_enc_paysig and applepay_enc_pubkey

(Bold parameter should be sent same) Request Parameter

Field	Value	Description
ivp_method	applepay	Set value as 'applepay'
ivp_store	15164	Your store ID
ivp_authkey	cxkwshbs68ejbh	V2 Settings authentication Key
ivp_amount	10	Transaction amount
ivp_currency	AED	Currency the transaction is in
ivp_test	0	Test mode indicator
ivp_desc	Description	Purchase description
return_auth	return url for authorised transaction	return url transaction for authorised
return_decl	return url upon declined	return url transaction for declined
return_can	return url upon cancelled	return url transaction for cancelled
bill_fname	FirstName	"The customer’s forename plus any other middle names or initials they may have."
bill_sname	Lastname	Customer surname (also known as family name)
bill_addr1	Address	Customer address
bill_city	city	city
bill_region	Region	Region
bill_country	Country	Country
bill_zip	123456	Zip code
bill_email	[email protected]	Email address
ivp_lang	en	"Payment language Page inreface Your reference for the transaction. For example this could be a cart ID or order ID generated by your shopping system. This must be unique for each request. Maximum length is 63 characters."
ivp_cart	CartID	Maximum length is 63 characters.
ivp_trantype	Sale/Auth/Capture/Verify	"Purchase Authorize/Capture or Verify.To be set as per the terminal configuration."
ivp_tranclass	ecom	Set 'ecom'
delv_addr1	Bill address	Bill address
delv_addr2	Address 2	Address 2
delv_addr3	Address 3	Address 3
delv_city	City	City
delv_region	Region	Region
delv_country	Country	Country

applepay_enc_version	version	"From Apple pay token get ""version"""
applepay_enc_paydata	data	"From Apple pay token get ""data"""
applepay_enc_paysig	signature	"From ApplePay token get ""signature"""
applepay_enc_pubkey	ephemeralPublicKey	"From Apple Pay token get ""ephemeralPublicKey"""
applepay_enc_keyhash	publicKeyHash	"From Apple Pay token get ""publicKeyHash"""
applepay_tran_id	transactionId	"From Apple Pay token get ""transactionId"""
applepay_card_desc	type	"From ApplePay token get ""type"""
applepay_card_scheme	displayName	"From ApplePay token get ""displayName"""
applepay_card_type	network	"From Applepay token get ""network"""
applepay_tran_id2	transactionIdentifier	"From Apple Pay token get ""transactionIdentifier"""

With Above Request Telr gateway will process the transaction with Master card processor (MPGS).

Telr RESPONSE FORMAT IS AS BELOW
{"trace":"4001/5151/%ea6bba9", "transaction":{"ref":"040024871559","type":"sale","class":"ECom","status":"D"," code":"31","message":"Not authorised"}, "customer":{"email":"[email protected]","name":{"forenames":"A bcd","surname":"sff"},"address":{"line1:No address","city":"Unknown","country":"AE"}}}
“status” can be as below, which is to be used to notify on Apple Pay screen about the status.
A: Authorised D: Declined C: Cancelled

Using a Pre-decrypted Apple Pay Token

This supports merchant in making a payment using a decrypted Apple Pay network token.

Use the above request parameters by replacing the parameter starting with "applepay_" with below additional parameters.

Additional Request Parameters:

Field	Value	Description
applepay_net_scheme	Card scheme	Card Scheme
applepay_net_dpan	Card number	retrieve from Apple Pay network token's "PrimaryAccountNumber"
applepay_net_exm	Card expiry month	retrieve from Apple Pay network token's "applicationExpirationDate". If in YYMMDD format, use MM value
applepay_net_exy	Card expiry year	retrieve from Apple Pay network token's "applicationExpirationDate". If in YYMMDD format, use YYYY value, e.g., 2024
applepay_net_eci	ECI Value	retrieve from Apple Pay network token's "eciIndicator"
applepay_net_iav	Cryptogram	retrieve from Apple Pay network token's "onlinePaymentCryptogram

Sample JSON Request:

  "applepay": {
        "networkToken": {
        "card": {
            "scheme":"visa",
            "number":"4**************6",
                "expiry":{
                     " month":"02",
                    "year":"2**8"
									}
        },
        "cryptogram":"A*******************A="
        }
}

CONFIGURATION 2

Merchant does not have an Apple ID and wants to enable Apple Pay as payment option

This is required when merchant is using full page display of Telr payment page, where request contains ivp_framed=0(0 or not set)

APPLE DEVELOPER ACCOUNT CONFIGURATION

Telr will be using Telr Apple Pay ID and its respective key and certificate.

PROCESSING APPLE PAY IN WEB OR IN IOS APP

Create a Payment request and POST to following URL, this is same as current transaction processing which merchant is using.

https://secure.telr.com/gateway/order.json

Mandatory parameters to process Apple Pay are as below.

Field	Value	Description
ivp_method	create	Set value as ‘create’
ivp_store	15164	Your store ID
ivp_authkey	cxkwshbs68ejbh	V2 Settings authentication Key
ivp_amount	10	Transaction amount
ivp_currency	AED	Currency the transaction is in
ivp_test	0	Test mode indicator
ivp_desc	Description	Purchase description
return_auth	return url for authorised transaction	return url for authorised transaction
return_decl	return url upon declined	return url for declined transaction
return_can	return url upon cancelled	return url for cancelled transaction
bill_fname	FirstName	"The customer’s forename plus any other middle names or initials they may have. "
bill_sname	Lastname	Customer surname (also known as family name)
bill_addr1	Address	Customer address
bill_city	city	city
bill_region	Region	Region
bill_country	Country	Country
bill_zip	123456	Zip code
bill_email	[email protected]	Email address
ivp_lang	en	Payment Page interface language
ivp_applepay	0 or 1	To enable Applepay set value as 1 and to disable set as 0. If this parameter is not sent then ApplePay will be enabled by default.
ivp_cart	CartID	"Your reference for the transaction. For example this could be a cart ID or order ID generated by your shopping system. This must be unique for each request. Maximum length is 63 characters."

APPLE PAY IN Telr INVOICE

Merchant does not have an Apple ID and wants to enable Apple Pay as payment option in Invoice payment collection.

APPLE DEVELOPER ACCOUNT CONFIGURATION

Telr will be using Telr Apple Pay ID and its respective key and certificate.

INVOICE CREATION

While generating new invoice mandatory field to be provided at dash board is illustrated as below.

NOTES

Telr iframe payment page is the one of the methods of integration, where merchant uses their web page as parent frame and displays Telr Payment page in iframe within their page. Apple Pay on the Web does not support Telr iframe payment pages.