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

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. 

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

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 MyOpayo as an administrative user
• Navigate to the 'Settings' tab and select 'Pay Methods'
• Click 'Add Apple Pay'

• Click the 'Configure Apple Pay' button under 'Opayo manages your certificate'.

• 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

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

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

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.

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:

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