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.