Judopay Documentation

Apple Pay™ for Web

Note

It is assumed you already have a Judopay account. If you do not, sign up for a sandbox account here.

Prerequisites

Make sure you have implemented the following prerequisites:

Direct from Judopay:

  • Judopay APIToken

  • Judopay APISecret

  • Judopay JudoID

  • A valid apple-developer-merchantid-domain-association

    Get it here.

From the Merchant:      

  • Domain(s) being used for Apple Pay™

    These are the domain(s) where the Apple Pay™ button will be displayed, for example the checkout page.      

    Note

    These must be SSL enabled domains, Apple will not allow non-encrypted domains to be used.

  • Account(s) being used for Apple Pay™

Web SDK Version:

  • Web SDK Version 0.0.18 (or higher).

Domain Registration

  1. Create the following folder on your web server's root domain directory:

    ./well-known

  2. In the folder, create a web server identity file: 

    apple-developer-merchantid-domain-association

  3. Add the following contents to the web server identity file:

    Caution

    Take care when copying and pasting the contents.

    7B227073704964223A2246464441433543444430383931464146354232334143353735363243323638434132323337363438304230344433323935433433374635423133433830393835222C2276657273696F6E223A312C22637265617465644F6E223A313538323234343132383531332C227369676E6174757265223A223330383030363039326138363438383666373064303130373032613038303330383030323031303133313066333030643036303936303836343830313635303330343032303130353030333038303036303932613836343838366637306430313037303130303030613038303330383230336533333038323033383861303033303230313032303230383463333034313439353139643534333633303061303630383261383634386365336430343033303233303761333132653330326330363033353530343033306332353431373037303663363532303431373037303663363936333631373436393666366532303439366537343635363737323631373436393666366532303433343132303264323034373333333132363330323430363033353530343062306331643431373037303663363532303433363537323734363936363639363336313734363936663665323034313735373436383666373236393734373933313133333031313036303335353034306130633061343137303730366336353230343936653633326533313062333030393036303335353034303631333032353535333330316531373064333133393330333533313338333033313333333233353337356131373064333233343330333533313336333033313333333233353337356133303566333132353330323330363033353530343033306331633635363336333264373336643730326436323732366636623635373232643733363936373665356635353433333432643530353234663434333131343330313230363033353530343062306330623639346635333230353337393733373436353664373333313133333031313036303335353034306130633061343137303730366336353230343936653633326533313062333030393036303335353034303631333032353535333330353933303133303630373261383634386365336430323031303630383261383634386365336430333031303730333432303030346332313537376564656264366337623232313866363864643730393061313231386463376230626436663263323833643834363039356439346166346135343131623833343230656438313166333430376538333333316631633534633366376562333232306436626164356434656666343932383938393365376330663133613338323032313133303832303230643330306330363033353531643133303130316666303430323330303033303166303630333535316432333034313833303136383031343233663234396334346639336534656632376536633466363238366333666132626266643265346233303435303630383262303630313035303530373031303130343339333033373330333530363038326230363031303530353037333030313836323936383734373437303361326632663666363337333730326536313730373036633635326536333666366432663666363337333730333033343264363137303730366336353631363936333631333333303332333038323031316430363033353531643230303438323031313433303832303131303330383230313063303630393261383634383836663736333634303530313330383166653330383163333036303832623036303130353035303730323032333038316236306338316233353236353663363936313665363336353230366636653230373436383639373332303633363537323734363936363639363336313734363532303632373932303631366537393230373036313732373437393230363137333733373536643635373332303631363336333635373037343631366536333635323036663636323037343638363532303734363836353665323036313730373036633639363336313632366336353230373337343631366536343631373236343230373436353732366437333230363136653634323036333666366536343639373436393666366537333230366636363230373537333635326332303633363537323734363936363639363336313734363532303730366636633639363337393230363136653634323036333635373237343639363636393633363137343639366636653230373037323631363337343639363336353230373337343631373436353664363536653734373332653330333630363038326230363031303530353037303230313136326136383734373437303361326632663737373737373265363137303730366336353265363336663664326636333635373237343639363636393633363137343635363137353734363836663732363937343739326633303334303630333535316431663034326433303262333032396130323761303235383632333638373437343730336132663266363337323663326536313730373036633635326536333666366432663631373037303663363536313639363336313333326536333732366333303164303630333535316430653034313630343134393435376462366664353734383138363839383937363266376535373835303765373962353832343330306530363033353531643066303130316666303430343033303230373830333030663036303932613836343838366637363336343036316430343032303530303330306130363038326138363438636533643034303330323033343930303330343630323231303062653039353731666537316531653733356235356535616661636234633732666562343435663330313835323232633732353130303262363165626436663535303232313030643138623335306135646436646436656231373436303335623131656232636538376366613365366166366362643833383038393064633832636464616136333330383230326565333038323032373561303033303230313032303230383439366432666266336139386461393733303061303630383261383634386365336430343033303233303637333131623330313930363033353530343033306331323431373037303663363532303532366636663734323034333431323032643230343733333331323633303234303630333535303430623063316434313730373036633635323034333635373237343639363636393633363137343639366636653230343137353734363836663732363937343739333131333330313130363033353530343061306330613431373037303663363532303439366536333265333130623330303930363033353530343036313330323535353333303165313730643331333433303335333033363332333333343336333333303561313730643332333933303335333033363332333333343336333333303561333037613331326533303263303630333535303430333063323534313730373036633635323034313730373036633639363336313734363936663665323034393665373436353637373236313734363936663665323034333431323032643230343733333331323633303234303630333535303430623063316434313730373036633635323034333635373237343639363636393633363137343639366636653230343137353734363836663732363937343739333131333330313130363033353530343061306330613431373037303663363532303439366536333265333130623330303930363033353530343036313330323535353333303539333031333036303732613836343863653364303230313036303832613836343863653364303330313037303334323030303466303137313138343139643736343835643531613565323538313037373665383830613265666465376261653464653038646663346239336531333335366435363635623335616532326430393737363064323234653762626130386664373631376365383863623736626236363730626563386538323938346666353434356133383166373330383166343330343630363038326230363031303530353037303130313034336133303338333033363036303832623036303130353035303733303031383632613638373437343730336132663266366636333733373032653631373037303663363532653633366636643266366636333733373033303334326436313730373036633635373236663666373436333631363733333330316430363033353531643065303431363034313432336632343963343466393365346566323765366334663632383663336661326262666432653462333030663036303335353164313330313031666630343035333030333031303166663330316630363033353531643233303431383330313638303134626262306465613135383333383839616134386139396465626562646562616664616362323461623330333730363033353531643166303433303330326533303263613032616130323838363236363837343734373033613266326636333732366332653631373037303663363532653633366636643266363137303730366336353732366636663734363336313637333332653633373236633330306530363033353531643066303130316666303430343033303230313036333031303036306132613836343838366637363336343036303230653034303230353030333030613036303832613836343863653364303430333032303336373030333036343032333033616366373238333531313639396231383666623335633335366361363262666634313765646439306637353464613238656265663139633831356534326237383966383938663739623539396639386435343130643866396465396332666530323330333232646435343432316230613330353737366335646633333833623930363766643137376332633231366439363466633637323639383231323666353466383761376431623939636239623039383932313631303639393066303939323164303030303331383230313863333038323031383830323031303133303831383633303761333132653330326330363033353530343033306332353431373037303663363532303431373037303663363936333631373436393666366532303439366537343635363737323631373436393666366532303433343132303264323034373333333132363330323430363033353530343062306331643431373037303663363532303433363537323734363936363639363336313734363936663665323034313735373436383666373236393734373933313133333031313036303335353034306130633061343137303730366336353230343936653633326533313062333030393036303335353034303631333032353535333032303834633330343134393531396435343336333030643036303936303836343830313635303330343032303130353030613038313935333031383036303932613836343838366637306430313039303333313062303630393261383634383836663730643031303730313330316330363039326138363438383666373064303130393035333130663137306433323330333033323332333133303330333133353332333835613330326130363039326138363438383666373064303130393334333131643330316233303064303630393630383634383031363530333034303230313035303061313061303630383261383634386365336430343033303233303266303630393261383634383836663730643031303930343331323230343230616435653436613565356166373866386464393561663539303861613633666663666334313931666631353163653866616265323933396333353835643761363330306130363038326138363438636533643034303330323034343733303435303232303037373464613634666637323236366464626430333361383564393431356135393739656430373136633735666534353232306565353437313830303065613130323231303064666163663134343263623538633238346664396666623132643961636437303266363138656139313834383334363032366361376563616663383634306631303030303030303030303030227D
  4. Complete a web server test:

    1. Make sure the web server identity file is accessible externally from your website.

    2. In a browser go to: https://www.yourdomain.com/./well-known/apple-developer-merchantid-domain-association

    3. Change the location to your website domain.

    4. Ensure that the apple-developer-merchantid-domain-association file is downloadable.

      Note

      Apple will use this location to check the validity of your domain. It is important this is externally accessible.

  5. Notify Judopay of the following details:

    JudoID(s)    

    List your JudoIDs you wish enabled for Apple Pay™

    Domain(s)   

    List your domain URLs you wish enabled for Apple Pay™  

    Note

    Judopay developer support will enable your account(s) with the Apple Pay™ configuration that will allow you to perform Apple Pay™ transactions from those domains.

    Once complete, we will reply to your original request notifying you that this has been actioned.

    Once this has been confirmed you can move onto the integration steps to continue: Step 1: Obtain a Payment Session.

Integration

Step 1: Obtain a Payment Session

To use Apple Pay™ with Judopay's Web SDK, you must first obtain a valid Payment Session. This is used to complete the Apple Pay™ Transaction.  

Note

Judopay's Web SDK now supports Payment Sessions for Card and Alternative Payment Methods, in order to ensure the security and authenticity of the transaction being requested.

It is recommended to use Payment Sessions from now on, as this flow supports the full payment flow handling of Alternative Payment Methods and 3D Secure transactions. The advantage being there is no need for you to handle any intermediate steps.

  1. To receive a valid Payment Session, the following call is made from your back office to Judopay's API (the JSON example is a sample POST Web Payment Request):

{
  "JudoId": "yourJudoID",
  "amount": 1.01,
  "yourConsumerReference": "yourConsumerReference",
  "yourPaymentReference": "yourUniquePaymentReference",
  "Currency":"GBP"
}
  1. To the following endpoint: https://api.judopay.com/webpayments/payments    

Caution

These are live endpoints as Apple Pay™ only works on live transactions. You can create the Apple Pay™ Button on Sandbox, but you will not be able to complete an Apple Pay™ Transaction on Sandbox accounts.

(Apple Wallet holds live credit card data, and it is this that is used to perform the transaction payment).

  1. You should receive the following response:

{
    "payByLinkUrl": "https://pay.judopay.com/jbv6Er",
    "postUrl": "https://pay.judopay.com/v1",
    "reference": "5QcAAAMA11222AAAADwAAAP35xxiieAjIBRllQdLR8fHhvKKEG9Z2lXevB8vpJlhvTozfNw"
}

Note

Your reference and payByLinkUrl will differ, as they are unique to each transaction.

  1. The reference field is the field you must reference in your Apple Pay™ transaction, within the Web SDK.

Sample PHP: Get Web Payment Reference

Note

Replace any field {{field}} with your own required values.

This is a sample direct API call, using PHP.

<?php

header('Content-Type: application/json');

$userEncode = base64_encode("{{yourAPIToken}}".":"."{{yourAPISecret}}");

$data = array(
        'judoId' => "{{yourJudoID}}",
        'amount' => "{{amount}}",
        'currency' => "{{currency}}",
        'yourConsumerReference' => "{{yourConsumerReference}}",
        'yourPaymentReference' => "{{yourUniquePaymentReference}}"
);

$dataJson = json_encode($data);

$headers = array(
  'Content-Type:application/json',
  'Authorization: Basic '.$userEncode,
  'API-Version: 6.2'
);

$environment = "https://api.judopay.com/webpayments/payments";
$response = "";

$ch = curl_init($environment);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FRESH_CONNECT, TRUE);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS,$dataJson);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);

echo $response;

?>

Step 2: Use Judopay's Web SDK

  1. To use Judopay's Web SDK, include the following script In your checkout page:

<script src="https://web.judopay.com/js/0.0.18/judopay.min.js"></script>

Step 3: Place the Apple Pay™ Button

Using Judopay's Web SDK:

  1. Within your checkout page code, add the following for placement of the Apple Pay™ Button:

<div id="apple-pay-button-container" width="100%" align="left"></div>   

Note

This <div> tag will be exchanged to display the Apple Pay™ Button.

(On a browser or device that can use Apple Pay™, for example an iPhone, or Safari Browser on a Mac).

Step 4: Update the Apple Pay™ Button

  1. Include the following script to create the Apple Pay™ Button:

<script>
var button = judo.digitalWallets.getApplePayButton({
height: 38, 
width: 240, 
language: 'EN', 
style: 'black', 
type: 'buy', // optional
onClick: handleApplePayButtonClick})

document.getElementById('apple-pay-button-container').appendChild(button)

</script>   

Note

This code sets up the Apple Pay™ Button in Step 2: Use Judopay's Web SDK (if a valid browser is detected and Apple has authorised the domain).

This sample will call the handleApplePayButtonClick function, when the button is clicked.

Style:

  • black

  • white

Type (Optional):

  • If set to buy:

    Buy now with Apple, will be displayed.

  • If omitted:

    The Apple Logo will be displayed.

Step 5: Handle the Apple Pay™ Button Click

  1. Include the following script to handle the Apple Pay™ Payment:

    Note

    Replace the items in {{brackets}} with your values.

<script>

function handleApplePayButtonClick() {

let configuration = {
  amount: '{{amount}}',
  currency: '{{currency}}',
  yourConsumerReference: '{{yourConsumerReference}}',
  yourPaymentReference: '{{yourPaymentReference}}’,
  judoId: '{{judoId}}',	
//initiativeContext: 'web.judopay.com' // optional, default = window.location.hostname
}

judo.digitalWallets
.invokePaymentWithApplePay({{paymentSession}}, configuration)
.then(response => console.log(JSON.stringify(response)))
.catch(error => console.error(error))

} 
</script>
  1. Ensure the configuration options for:

    - amount

    - currency

    - yourConsumerReference

    - yourPaymentReference match those used in Step 1: Obtain a Payment Session.

    (This is used to cross reference the validity of the transaction).

  2. The reference value for paymentSession, is obtained from Step 1: Obtain a Payment Session .

    For the purpose of this exercise, the reference obtained in Step 1 was: 5QcAAAMA11222AAAADwAAAP35xxiieAjIBRllQdLR8fHhvKKEG9Z2lXevB8vpJlhvTozfNw  

Therefore, the call would be:

judo.digitalWallets
.invokePaymentWithApplePay(’5QcAAAMA11222AAAADwAAAP35xxiieAjIBRllQdLR8fHhvKKEG9Z2lXevB8vpJlhvTozfNw’, configuration)
.then(response => console.log(JSON.stringify(response)))
.catch(error => console.error(error))

Step 6: Handle the Result

Handle the result within the handleApplePayButtonClick method.

You will either be given:

  • A response JSON object

    (a Judopay receipt object)

  • An error object  

In this sample, the response or error is logged to the console. You must handle this JSON object accordingly from here.