Integrating with Apple Pay (Opayo managed certificate)

On this page:

Prepare domain for verification
Prepare your Opayo account
Display an Apple Pay button
Get an Apple Pay session
Perform the transaction
Return the to result to the device
Live URLs

 

Important: This functionality is currently in beta. If you want to enable this for your account, please contact support@opayo.io.
Important: Apple Pay functionality is currently only available to Elavon acquired merchants.     

Preparing Merchant Domains for Verification

Before making a Register Merchant request, you must prepare each domain included in the request for verification. You can download the domain verification file from here. Unzip, and use this verification files for your registrations.

 

Important: Host your domain-verification file at the following path for each domain you're registering: https://[DOMAIN_NAME]/.well-known/apple-developer-merchantid-domain-association

 

The domain verification file must be in place before add the domain to your vendor account in MySagePay. Apple Pay servers don't require domain verification in the sandbox environment. 

 

Domains cannot be behind a proxy or redirect, and must be accessible to the Apple servers listed in Allow Apple IP Addresses for Domain Verification. The domain should also not be cached or behind a proxy.

 

Preparing your Opayo account

To prepare your vendor account to accept Apple Pay, you'll need to do the following:

  • Ensure that you have carried out the steps above.
  • Log into MySagePay as an administrative user
  • Navigate to the 'Settings' tab and select 'Pay Methods'
  • Click 'Add Apple Pay'

  • Click to Accept Apple's terms and conditions

  • You should now see the Apple Pay logo in the 'Other' section.
  • Now click 'Configure Apple Pay'
  • On the next screen enter your domain and click 'Add'. You can repeat this process for other domains that you use.

Display Apple Pay button

The first step of the process is to display an Apple Pay button. This should only be displayed on compatible devices.

You can refer to the instructions at: Displaying an Apple Pay button

 

Get an Apple Pay Session

Before you can display the payment sheet, you will need to start an Apple Pay session. Begin by defining what will be displayed on the Apple Pay payment sheet:

const payreq = {

countryCode: 'GB',
currencyCode: 'GBP',
shippingMethods: [
 {
label: 'Standard Shipping',
amount: '5.00',
identifier:
'free',
detail: 'Delivery',
},
],
 
lineItems:
[
{
label: 'Stuff I buy',
amount: '3.00',
}
],
 
total: {
label: 'total cost',
amount: '10.00',
},
 
 
supportedNetworks:[ 'amex', 'masterCard', 'visa'],

merchantCapabilities: [ 'supports3DS'],
 
 }; 

 Details can be found here

 

var session = new ApplePaySession(6, payreq)
 
 session.onvalidatemerchant = async event => {
 // Call your own server to request a new merchant session.
const merchantSession = await getApplePaySession ();
session.completeMerchantValidation(merchantSession);
 
 };

 

getApplePaySession is the call that you will make to your server in order to obtain the merchant session. We've provided a simple XMLHttpRequest example, but you can use your preferred method.

 

function getApplePaySession() {
return new Promise(function (resolve, reject) {
var xhr = new XMLHttpRequest();
xhr.open('POST', '<your-server>');
xhr.onload = function () {
if (this.status >= 200 && this.status < 300) {
resolve(JSON.parse(xhr.response));
} else {
reject({
status: this.status,
statusText:
xhr.statusText
});
}
}; 
 
xhr.onerror = function
() {
reject({
status: this.status,
statusText:
xhr.statusText
});
};
 

xhr.setRequestHeader("Content-Type", "application/json");
xhr.send();
});
}
 

You'll then need to acquire an Apple Pay session from Opayo by making the post from your server to Opayo:

 

VPSProtocol=4.00
Vendor=testvendor
TxType=SESSION
DomainName=merchant.domain.com
DisplayName=Merchant

 

Name

Description

Mandatory

Valid Characters

Max Length

Allowed Values

VPSProtocol

The version of the protocol you are integrating with. The Default value is 4.00, used when an invalid value is given.

Yes

Digits and periods
 

4.00

TxType

Transaction Type. Will always be SESSION in this case

Yes

Uppercase letters

15 

  • SESSION

Vendor

Used to authenticate your site. This must contain the Opayo Vendor Name given to you on account creation.

Yes

Letters and digits
 

15 

 

DomainName

The domain that the payment request is originating from.

Yes

RFC1738

100

 

DisplayName

Merchant Display Name

Yes

Letters and digits
 

50

 

 

The response from Opayo will resemble:

 

VPSProtocol=4.00
Status=OK
StatusDetail=1001 : Session created successfully
EpochTimestamp=1627032661673
ExpiresAt=1627036261673
MerchantSessionIdentifier=SSHA1B3167F40034E698B7C88910A3A8A37_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24
Nonce=a4268986
MerchantIdentifier=389EFFD590B342FACDA038589D2CCA6419AC49FBD758DDB10A38AF9A28917434
DomainName=ec-applepay-test-merchant.s3.amazonaws.com
DisplayName=Opayo Test
SessionValidationToken=DFGEQBTYJN...
Signature=308006092

 

Name

Description

Mandatory

Valid Characters

Max Length

Allowed Values

VPSProtocol

The version of the protocol you are integrating with. The Default value is 4.00, used when an invalid value is given.

Yes

Digits and periods
 

4.00

Status

An indication of the status of the request.

Yes

Uppercase letters

9

OK= The process executed without an error.
MALFORMED = Input message was missing fields or badly formatted – normally will only occur during development.
INVALID = Transaction was not registered because although the POST format was valid, some information supplied was invalid. e.g. incorrect vendor name or currency.
ERROR = A problem occurred at Opayo which prevented transaction registration.

StatusDetail

This text adds detail to the Status value. Always check StatusDetail when the Status is not OK.

Yes

Letters, digits, commas, periods, colons, spaces, and parentheses
      

255

 

EpochTimestamp

The date and time of the signature's creation in milliseconds, formatted in Unix epoch time.

Yes

20

 

ExpiresAt

The date and time of the signature's creation in milliseconds, formatted in Unix epoch time.

Yes

20

 

MerchantSessionIdentifier

The value of the merchant session to be passed back to the browser session.

Yes

 

Letters, digits, underscore
  

 

255

 

Nonce

A one-time nonce value generated by Apple's servers.

Yes

Letters, digits
  

255

 

MerchantIdentifier

Your merchant identifier

Yes

Letters, digits
  

255

 

DomainName

The domain that is registered with Apple Pay

Yes

Letters, digits, periods
  

100

 

DisplayName

The display name associated with your vendor account.

Yes

Letters, digits, commas, periods, colons, spaces, and parentheses
      

50

 

SessionValidationToken

A token used to validate the session when Opayo process your transaction

Yes

Base 64

255

 

Signature

A hash of the public key used to sign the interactions.

Yes

Letters, digits
  

255

 

 

You'll then need to convert the response to a JSON object pass the it back to the browser session (omitting the VPSProtocol, Status, StatusDetail and SessionValidationToken fields):

 

 {

"epochTimestamp": "1627032661673",
"expiresAt":"1627036261673",
"merchantSessionIdentifier":"SSHA1B3167F40034E698B7C88910A3A8A37_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24",
"nonce": "a4268986",
"merchantIdentifier":"389EFFD590B342FACDA038589D2CCA6419AC49FBD758DDB10A38AF9A28917434",
"domainName": "ec-applepay-test-merchant.s3.amazonaws.com",
"displayName": "Opayo Test",
"signature": "308006092"
 }
Note: The case of the field names must match the sameple above.

 

You can now call various other event handlers if you need to: onpaymentmethodselected, onshippingmethodselected, onshippingcontactselected (see here for details).

 

Perform transaction

You will then need to perform the transaction, passing the payload back to your server for onward transmission to Opayo (represented by the performTransaction call in the example below).

 

session.onpaymentauthorized = function (event) { 
 
performTransaction(event.payment, function (result) {
if
(result.approved) {

appleSession.completePayment(ApplePaySession.STATUS_SUCCESS)
 } else {
appleSession.completePayment(ApplePaySession.STATUS_FAILURE)

}
}) 
}

 

The payload that you will recieve from Apple will resemble:

 

 {
 "transactionIdentifier": "xPRJU9Fiybv1LFV",

"PaymentMethod": {
"displayName": "Visa 0006",
"network":
"Visa",
"type": "debit"
 },
 
"PaymentData": {

"PaymentHeader": {
"ephemeralPublicKey": "1dqaqTEOsWjJoE0==",

"publicKeyHash": "joNiPumFmvGtXoB==",
"transactionId": "xPRJU9Fiybv1LFV",
"applicationData": "null"
 
 },
 

"data": "GVzXH4GT3TSwzjj...",
"signature":"QZUPCA1PzrEaGcI...",
"version": "EC_v1"
 
 } 
}

Your server will need to Base64 encode this response and send it to Opayo in the Payload field.

You will also need to extract the network and type fields from the PaymentMethod object, and use these to determine the CardType to submit in the request to Opayo.

If the network is Visa and type is Debit, use DELTA. If the network is Mastercard and type is Credit, use MC.  If the network is Mastercard and type is Debit, use MCDEBIT.  If the network is Diner's / Discover use DC.For a full breakdown of the CardTypes, see here.
VPSProtocol=4.0
Vendor=testvendor
Wallet=APPLE
TxType=PAYMENT
VendorTXCode=test-660999
Amount=1.01
Currency=GBP
Description=Direct-Payment-AP
CardType=Visa
BillingSurname=Me
BillingFirstnames=Jake
BillingAddress1=150 My Road
BillingCity=London
BillingPostcode=N6 4LU
BillingCountry=GB
DeliverySurname=Me
DeliveryFirstnames=Jake
DeliveryAddress1=150 My Road
DeliveryCity=London
DeliveryPostcode=N6 4LU
DeliveryCountry=GB
DeliveryPhone=0788888888
ClientIPAddress=127.0.0.1
ApplyAVSCV2=1
Apply3DSecure=2
SessionValidationToken=DGTVETVRTCSCF...
Payload=eyJwYXltZW50TWV0a...

 

See here for the full list of Direct fields.

 

Additionally, you will need to send:

 

Name

Description

Mandatory

Valid Characters

Max Length

Allowed Values

Wallet

The wallet integration being used. In this case, the value will always be APPLE

Yes

Uppercase letters

5

  • APPLE

SessionValidationToken

The SessionTokenValidation value from the Apple Pay session response

Yes

Base 64

255

This value must match the Token returned from the session response exactly.

Payload

The encrypted payment token provided by Apple

Yes

 

Letters, digits
  

 

255

 

 

Important: You can omit the Cardholder, Cardnumber, Expiry, CV2 and all 3D Secure related fields from the standard Direct transaction registration request.

 

VPSProtocol=4.00
Status=OK
StatusDetail=0000 : The Authorisation was Successful.
VPSTxId={E0980B68-9D33-FD5D-0C38-681F8485A457}
SecurityKey=VLG07RYKLD
TxAuthNo=8955544
AVSCV2=SECURITY CODE MATCH ONLY
AddressResult=NOTMATCHED
PostCodeResult=NOTMATCHED
CV2Result=NOTCHECKED
3DSecureStatus=NOTCHECKED
DeclineCode=00
ExpiryDate=1223
BankAuthCode=999777

 

See here for a full list of the fields which may be returned.

Response

If your transaction is authorised succesfully, you'll need to pass a response back to the Apple Pay payment sheet:

 

On success:

{
"approved":true
}

On failure:

{
"approved":false
}

Live URLs

Live URLs by operation

Operation URL

SESSION

https://live.sagepay.com/gateway/service/direct-applepay-session.vsp

WALLET TRANSACTION

https://live.sagepay.com/gateway/service/wallet-payment.vsp