Wat is Apple Pay?
Apple Pay is een mobiele betaalservice op basis van een portemonnee van Apple Inc. waarmee gebruikers betalingen kunnen afhandelen met een iPhone, iPad of Mac. Klanten profiteren van een vertrouwde en gestroomlijnde betaalervaring, waarbij hun factuurgegevens vooraf kunnen worden ingevuld, klaar voor aankoop. Klanten worden snel geverifieerd door hun vinger op de ingebouwde lezer te plaatsen of door gezichtsherkenning. Apple Pay gebruikt tokens om ervoor te zorgen dat er geen gevoelige betalingsinformatie wordt opgeslagen bij Apple, op het apparaat van de klant of op je eigen servers.
In dit artikel wordt uitgelegd hoe je Apple Pay kunt integreren in je betaaloplossing met behulp van onze JavaScript Library.
Alleen in aanmerking komende klanten kunnen transacties uitvoeren via Apple Pay. Klanten moeten bijvoorbeeld een ondersteund Apple apparaat gebruiken en zich in een land bevinden waar Apple Pay actief is. Raadpleeg de documentatie van Apple (link naar externe site) voor de volledige lijst met vereisten.
In mei 2024 hebben we het integratieproces met Apple Pay
Als je Apple Pay vóór deze wijziging hebt geïntegreerd met Trust Payments :
- Je kunt onze oudere documentatie vinden door hier te klikken.
- Maar we raden u aan het onderstaande proces door te nemen wanneer u uw certificaten de volgende keer vernieuwt.
Vereisten
Zorg ervoor dat u aan de volgende vereisten voldoet voordat u Apple Pay in uw kassa-oplossing integreert:
Uw acquiring bank moet
Apple Pay ondersteunen met Trust Payments.
Neem contact op met het Support Team als u het niet zeker weet
Uw server moet aan de volgende eisen voldoen:
- Moet het Transport Layer Security (TLS) 1.2 protocol of hoger ondersteunen.
- Moet één van de cipher suites ondersteunen die vermeld staan in de documentatie van Apple (link naar externe site).
- Moet voldoen aan hoge veiligheidsnormen (bijv. bij gebruik van SSL Labs (link naar externe site) om certificaat te controleren, is een A-cijfer vereist).
Om je oplossing te kunnen testen, moet je toegang hebben tot een apparaat dat de sandboxtests van Apple voor Apple Pay ondersteunt.
Je hebt een sandboxtesteraccount nodig om testkaarten aan je portemonnee toe te voegen, zodat je Apple Pay testtransacties kunt verwerken.
Uw domeinen instellen en verifiëren
-
Begin met het downloaden van het onderstaande domeinverificatiebestand en plaats dit op je domeinen waar Apple Pay moet worden weergegeven:
U moet elk domein voorbereiden door het ontvangen domeinverificatiebestand op deze locatie te hosten, aangezien dit publiekelijk zal worden opgevraagd om het domeinregistratieproces te voltooien:
https://[DOMAIN_NAME]/.well-known/apple-developer-merchantid-domain-associationEnsure the file and the hidden .well-known directory are given read and execute permissions. (For Unix, this is typically done by using the command chmod 755 <filename or folder>).
Als onderdeel van het Apple Pay validatieproces vereist Apple dat het validatiebestand een HTTP 200 OK respons geeft. Elke andere HTTP-antwoordcode, zoals 301 Permanent verplaatst, wordt behandeld als een mislukking. Om ervoor te zorgen dat Apple Pay goed werkt, moet het validatiebestand zo worden geconfigureerd dat het altijd een HTTP 200 OK-antwoord terugstuurt.
-
Laat je geautoriseerde contactpersoon contact opnemen met ons Support Team en een verzoek indienen om Apple Pay in te schakelen op je site referentie(s). In uw e-mail vragen we u een CSV-bestand bij te voegen met een lijst van alle sitereferenties die u wilt registreren en hun bijbehorende domein(en).
Het formaat van het CSV-bestand moet als volgt zijn:
Site reference, Domain nameBijvoorbeeld:
site10001, example.com site10002, trustpayments.com test_site10003, trustpayments.comNeem alle relevante test- en live sitereferenties en domeinen op in het bestand.
Formatteer domeinen zoals deze: example.com
Stuur ons dit niet! www.example.comJe kunt tot 99 domeinen registreren per site referentie.
-
Ons Support Team zal je op de hoogte houden zodra het registratieproces voor de opgegeven domeinen is voltooid en je kunt beginnen met het verwerken van Apple Pay transacties.
Als je eerder Apple Pay hebt geïntegreerd met behulp van onze JavaScript Library , maar sindsdien het nieuwe registratieproces hebt overgenomen dat hierboven is beschreven, moet je ervoor zorgen dat de eigenschap merchantId in de configuratie die wordt doorgegeven aan de st.js ApplePay methode is bijgewerkt om uw site referentie te specificeren in plaats van de Apple Pay Merchant Id. De domeinen zijn nu namelijk gekoppeld aan uw site referentie in plaats van uw Apple Pay Merchant Id.
Configureer Apple Pay oplossing
Nadat u uw domeinen hebt ingesteld en geverifieerd voor Apple Pay, moet u integreren met behulp van een van de volgende stromen die hieronder worden beschreven:
Stroom 1 - JavaScript bepaalt wanneer de AUTH wordt ingediend
- Wanneer de klant op de knop Apple Pay drukt, krijgt hij het betalingsformulier Apple Pay te zien.
- De klant keurt de betaling goed met Touch ID, Face ID of zijn wachtwoord.
- Wanneer de klant akkoord gaat met de betaling, wordt een AUTH verzoek ingediend bij Trust Payments.
- Trust Payments neemt contact op met de overnemende bank om autorisatie aan te vragen voor de transactie.
Uw JWT configureren
JSON Web Tokens (JWT) zijn een open, industriestandaard RFC 7519 methode om gegevens veilig tussen twee partijen te verzenden. Ze beschermen tegen de wijziging van kritieke transactiegegevens (bv. het af te schrijven bedrag) door onbevoegde partijen tijdens de betalingssessie.
Daarom is dit veld vereist om betalingen te verwerken met Trust Payments.
Klik hier om te leren hoe je een JWT genereert
Afhankelijk van uw voorkeursconfiguratie moet u misschien een extra veld in de payload bij het genereren van de JWT voor uw afrekenformulier.
Om de klant in staat te stellen een factuuradres of leveringsadres te kiezen dat is opgeslagen op zijn Apple-account vanaf de betalingsfiche (in plaats van een adres dat is ingevoerd bij het afrekenen), moet u de optionele velden billingcontactdetailsoverride en customercontactdetailsoverride respectievelijk opnemen met de waarde "1".
Anders hoeft het JWT niet te worden gewijzigd om Apple Pay transacties te verwerken.
Apple Pay bibliotheek
Wanneer de klant op de knop Apple Pay tikt, neemt onze st.js contact op met Apple om de betalingssessie te starten en het betalingsformulier weer te geven. Om dit gedrag mogelijk te maken, moet u verwijzen naar de bibliotheek Apple Pay door extra opmaak op uw betalingsformulier op te nemen, zoals aangegeven in de onderstaande tabbladen.
Allereerst moet u een div-plaatshouder toevoegen aan het betalingsformulier, als volgt:
<div id="st-apple-pay"></div>
Dan moet u uw Javascript bijwerken om ook onze Apple Pay bibliotheek aan te roepen:
st.ApplePay({
buttonStyle: 'white-outline',
buttonText: 'plain',
merchantId: 'test_site12345',
paymentRequest: {
countryCode: 'US',
currencyCode: 'USD',
merchantCapabilities: ['supports3DS', 'supportsCredit', 'supportsDebit'],
supportedNetworks: ["visa","masterCard","amex"],
requiredBillingContactFields: ["postalAddress"],
requiredShippingContactFields: ["postalAddress","name", "phone", "email"],
total: {
label: 'Trust Payments Merchant',
amount: '10.00'
}
},
buttonPlacement: 'st-apple-pay'
});
In het bovenstaande voorbeeld is de knop Apple Pay geconfigureerd om een transactie te verwerken voor $10,00, met een krediet- of debetkaart. Bovendien zijn vereiste factuur- en leveringsvelden gespecificeerd. Voor deze transactie zou de klant deze gegevens moeten verstrekken om de betaling te voltooien. Vereiste velden kunnen worden aangepast aan uw voorkeur, of helemaal worden verwijderd als ze niet nodig zijn.
De uiteindelijke opmaak ziet er als volgt uit:
<html>
<head>
</head>
<body>
<div id="st-notification-frame"></div>
<form id="st-form" action="https://www.example.com"/>
<div id="st-apple-pay"></div>
<script src="<CDN_DOMAIN>"></script>
<script>
(function() {
var st = SecureTrading({
jwt: 'INSERT YOUR JWT HERE',
});
st.ApplePay({
buttonStyle: 'white-outline',
buttonText: 'plain',
merchantId: 'test_site12345',
paymentRequest: {
countryCode: 'US',
currencyCode: 'USD',
merchantCapabilities: ['supports3DS', 'supportsCredit', 'supportsDebit'],
supportedNetworks: ["visa","masterCard","amex"],
requiredBillingContactFields: ["postalAddress"],
requiredShippingContactFields: ["postalAddress","name", "phone", "email"],
total: {
label: 'Trust Payments Merchant',
amount: '10.00'
}
},
buttonPlacement: 'st-apple-pay'
});
})();
</script>
</body>
</html>
Vervang <CDN_DOMAIN> met een ondersteund domein. Klik hier voor een volledige lijst.
Specificatie veld
Knopvelden
| Veld | Formaat | Beschrijving | |
| buttonStyle | Alfanumeriek | Wordt gebruikt om het uiterlijk van de knop Apple Pay te veranderen. Klik hier voor meer informatie (link naar externe site). |
|
| buttonText | Alfanumeriek | Wordt gebruikt om de tekst te wijzigen die verschijnt op de knop Apple Pay . Klik hier voor meer informatie (link naar externe site). |
|
| buttonPlacement | Alfanumeriek |
Standaard zoekt de bibliotheek naar een div id genaamd "st-apple-pay" om te bepalen waar de knop Apple Pay op het formulier moet komen. Als u niet de standaard div id, moet u uw aangepaste id opgeven als de waarde van de buttonPlacement eigendom. b.v. Dev notitie: Eigendom placement is verouderd en wordt niet langer ondersteund. Gebruik de vervangende buttonPlacement eigenschap in plaats daarvan. |
Nuttige bronnen met betrekking tot de knop Apple Pay
U kunt de kleur van de knop en de weergegeven tekst aanpassen aan de behoeften van uw kassa.
Klik hier voor meer informatie (link naar externe site).
Apple heeft richtlijnen gepubliceerd voor de beste positie van de Apple Pay knop op uw kassa.
Klik hier voor meer informatie (link naar externe site).
st.ApplePay({
buttonStyle: 'white-outline',
buttonText: 'plain',
buttonPlacement: 'st-apple-pay'
});
Handelsvelden
| Veld | Formaat | Beschrijving | ||
| merchantId | Alfanumeriek & underscore (50) |
De waarde die is toegewezen aan merchantId moet de site referentie zijn die is gekoppeld aan het domein dat de ApplePay methodezoals gespecificeerd in de CSV die naar het Support Team is gestuurd tijdens het domeinverificatieproces. De merchantId die hier wordt ingediend moet dezelfde zijn als de sitereference in het JWT. |
||
| paymentRequest | Object | Dit object bevat informatie over de betaling, die in het eerste verzoek naar Apple wordt gestuurd (onze Javascript stuurt dit). | ||
| countryCode | Alpha (2) | De landcode van de handelaar in ISO2a-formaat. | ||
| merchantCapabilities | Lijst |
De door de merchant ondersteunde betalingsmogelijkheden. Het veld moet bevatten “supports3DS” (om Touch ID / Face ID verificatie mogelijk te maken), en ten minste één van de volgende extra waarden:
|
||
| supportedNetworks | Lijst | De door de handelaar ondersteunde betalingsnetwerken. De waarde moet een of meer van de volgende zijn: "amex", "masterCard" of "visa". | ||
| supportedCountries | Array van strings |
Een lijst met landcodes van twee tekens die u opgeeft (in ISO2a-formaat). Apple Pay transacties zijn beperkt tot kaarten die zijn uitgegeven in landen die in deze eigenschap worden vermeld. De supportedCountries lijst heeft geen invloed op de Munt die voor de transactie wordt gebruikt, en geldt voor alle betaalkaarten in de portemonnee. |
||
st.ApplePay({
merchantId: 'test_site12345',
paymentRequest: {
countryCode: 'US',
merchantCapabilities: ['supports3DS', 'supportsCredit', 'supportsDebit'],
supportedNetworks: ["visa","masterCard","amex"],
},
});
Transactievelden
| Veld | Formaat | Beschrijving | |||
| paymentRequest | Object | Dit object bevat informatie over de betaling, die in het eerste verzoek naar Apple wordt gestuurd (onze Javascript stuurt dit). | |||
| requiredBillingContactFields | Lijst |
Op het betalingsformulier wordt dit veld gebruikt om de klant te vragen om vóór de aankoop het factuuradres van zijn Apple Pay -account te kiezen. Het betalingsblad zal GEEN factuuradresgegevens weergeven die bij de kassa zijn ingevoerd. U kunt de volgende veldwaarden opgeven:
Dit is vereist wanneer de klant de aankoop moet voltooien met behulp van de velden voor het factuuradres die zijn opgeslagen op zijn Apple Pay -account. |
|||
| requiredShippingContactFields | Lijst |
Op het betalingsformulier wordt dit veld gebruikt om de klant te vragen het leveringsadres van zijn/haar voorkeur te kiezen via zijn/haar Apple Pay account, vóór de aankoop. Het betalingsformulier zal GEEN leveringsadresgegevens weergeven die bij de kassa zijn ingevoerd. U kunt de volgende veldwaarden opgeven:
Dit is nodig wanneer de klant de aankoop moet afronden met behulp van de velden voor het leveringsadres die zijn opgeslagen op zijn Apple Pay account. |
|||
| currencyCode | Alpha (3) | De transactie Munt code in ISO3a formaat. | |||
| total | N/A | Een post die het totaal van de betaling weergeeft. | |||
| amount | Numeriek inclusief decimaal (14) | Het bedrag van de transactie in hoofdeenheden, waarbij een decimale punt wordt gebruikt om decimale waarden aan te geven, zodat €10 wordt teruggegeven als 10.00. Dit moet hetzelfde bedrag zijn als binnen de payload van het JWT. Het is essentieel dat het in het JWT opgegeven bedrag correct is, omdat dit de waarde is die bepaalt hoeveel de klant moet afschrijven. | |||
| label | Alfanumeriek, inclusief symbolen | Dit is een opmerking die op het betalingsblad Apple Pay naast het totaalbedrag moet worden weergegeven voordat de klant met de betaling instemt. | |||
st.ApplePay({
paymentRequest: {
currencyCode: 'USD',
requiredBillingContactFields: ["postalAddress"],
requiredShippingContactFields: ["postalAddress","name", "phone", "email"],
total: {
label: 'Trust Payments Merchant',
amount: '10.00'
}
},
});
Stroom 2 - Merchant bepaalt wanneer de AUTH wordt ingediend
Voor handelaren die liever de Apple wallettoken gegevens en stuur een API-verzoek om de AUTH zelf te verwerken, de eigenschap merchantUrl moet worden ingesteld in de st.js st.ApplePay methode config.
- Wanneer de klant op de knop Apple Pay drukt, krijgt hij het betalingsformulier Apple Pay te zien.
- De klant keurt de betaling goed met Touch ID, Face ID of zijn wachtwoord.
- merchantUrl krijgt een verzoek van het JavaScript met de portefeuillegegevens.
- Een AUTH verzoek wordt verzonden door de merchantUrl naar Trust Payments met behulp van onze Webservices API.
- Zodra het betalingsresultaat is teruggestuurd door Trust Payments naar de merchantUrl, moet een antwoord JWT worden teruggestuurd naar de st.js library om de Apple Payment sheet bij te werken.
Eerst voegen we de merchantUrl eigenschap aan de ApplePay methode config:
st.ApplePay({
buttonStyle: 'white-outline',
buttonText: 'plain',
merchantId: 'test_site12345',
paymentRequest: {
countryCode: 'US',
currencyCode: 'USD',
merchantCapabilities: ['supports3DS', 'supportsCredit', 'supportsDebit'],
supportedNetworks: ["visa","masterCard"],
requiredBillingContactFields: ["postalAddress"],
requiredShippingContactFields: ["postalAddress","name", "phone", "email"],
total: {
label: 'Trust Payments Merchant',
amount: '10.00'
}
},
buttonPlacement: 'st-apple-pay'
merchantUrl:'<payment URL endpoint>'
});
Het volgende is een voorbeeldverzoek dat vanuit het JavaScript wordt verzonden naar merchantUrl zodra de klant de transactie heeft geauthenticeerd met Touch ID, Face ID of passcode:
{
"request": [
{
"walletsource": "APPLEPAY",
"wallettoken": "<json encoded string>",
}
],
"jwt": "<jwt token>",
"acceptcustomeroutput": "2.00",
"version": "1.00",
"versioninfo": "STJS::N/A::3.2.0::N/A"
}
Op dit punt wordt aangenomen dat de merchantUrl zal een API-verzoek doen aan Trust Payments om de autorisatie te verwerken.
Voor een voorbeeld van het versturen van de AUTH met behulp van onze webservices API, zie de "AUTH request" sectie op dit artikel.
De merchantUrl response to the st.js should be a JWT response. You will need to parse the AUTH response and include the returned fields in the payload of the response <JWT Token>, as shown below.
{
jwt:<JWT Token>
}
De payload van de JWT token moet worden gecodeerd met het volgende object:
{'version': '1.00',
'response': [{
'walletsource': 'APPLEPAY',
'errormessage': 'Ok',
'sitereference': '<test or live sitereference>',
'errorcode': '0',
'requesttypedescription': 'AUTH'
}]
}
Het betalingsformulier begrijpen
Voordat de aankoop wordt afgerond, krijgt de klant de betalingsfiche te zien. Dit toont de klant de eerder op zijn account opgeslagen kaarten, opties voor levering, contactinformatie en het volledige aankoopbedrag (inclusief belasting en kosten). Hij kan de bestelling bekijken en eventueel aanpassingen doen alvorens verder te gaan.
Kaart
De klant zal kunnen kiezen uit de kaarten die zijn opgeslagen in zijn Apple Wallet (link naar externe site).
De voor betaling ondersteunde kaarten zijn afhankelijk van de merchantCapabilities veld bij de kassa.
Bijvoorbeeld als “supportsDebit” niet is opgenomen in het veld, zal de klant zijn betaling met een debetkaart niet kunnen voltooien.
Adres
Het factuur- en verzendadres worden alleen op het betalingsformulier weergegeven als de velden requiredBillingContactFields en requiredShippingContactFields zijn ingediend met geldige waarden. Hierdoor kan de klant kiezen uit factuur- en/of verzendadressen die in zijn Apple-account zijn opgeslagen.
Het op het betalingsformulier geselecteerde adres wordt alleen opgenomen in het AUTH verzoek indien de velden billingcontactdetailsoverride en customercontactdetailsoverride zijn ingediend, met de waarde "1".
Etiket en bedrag
De mainamount waarde wordt weergegeven op het betalingsformulier, naast de label, geplaatst op de kassa. In het voorbeeld hier is de label werd ingediend met de waarde “Outstanding balance”.
Authenticatie
De verificatiemethode verschilt afhankelijk van het apparaat waarmee de betaling wordt uitgevoerd. De klant kan worden gevraagd zijn vinger op de Touch ID-sensor te plaatsen of naar de Face ID-sensor te kijken.
Klik hier voor meer informatie over Apple Pay-verificatie (link naar externe site).
Voltooiing van de betaling
Zodra de klant met succes is geverifieerd op het betalingsformulier, is de volgende stap het verwerken van de transactie:
- Als je Flow 1 gebruikt, wordt de autorisatie automatisch uitgevoerd door st.js.
- Als je Flow 2 gebruikt, moet je configuratie het AUTH verzoek handmatig verwerken met behulp van de Webservices API en het betalingsformulier bijwerken met het resultaat.
Het betalingsblad Apple Pay wordt bijgewerkt om een bericht van succes of mislukking te tonen, afhankelijk van het resultaat van de betaling. Na een succesvol geval wordt de betalingsfiche gesloten om aan te geven dat de betaling is voltooid.
MyST
Net als bij gewone kaartbetalingen kunnen records van alle met Apple Pay verwerkte AUTH transacties worden bekeken in MyST. Bij het bekijken van Apple Pay transacties in MyST wordt de "Bron portefeuille" weergegeven als “APPLEPAY”. Klik hier om onze MyST documentatie te bekijken.
Test
Uw test site referentie maakt verbinding met de testzandbak Apple Pay . Om betalingen op uw test site referentie te verwerken, moet u dus testkaartgegevens toevoegen aan de Apple Wallet op uw ondersteunde toestel(len).
Je moet de testkaartgegevens gebruiken die Apple je heeft verstrekt. Raadpleeg de volgende URL:
https://developer.apple.com/support/apple-pay-sandbox/ (link naar externe site)
Het bovenstaande veronderstelt dat u op uw apparaat bent ingelogd met een Apple Sandbox-account.
Houd er rekening mee dat de testkaartgegevens die wij in onze testdocumentatie verstrekken, niet kunnen worden gebruikt bij de verwerking van Apple Pay testtransacties.
Als u User-Defined Rules (UDR) hebt ingeschakeld op uw site referentie(s), moet u ervoor zorgen dat u begrijpt hoe deze uw Apple Pay transacties kunnen beïnvloeden.
Als u hulp nodig hebt, neem dan contact op met ons Support Team.
Aanvullende verzoeken uitvoeren
Wanneer u e-commerce betalingen verwerkt met Apple Pay, kunt u uw oplossing configureren om extra verzoeken op te nemen om extra taken uit te voeren. Deze zijn als volgt:
U moet de JWT payload om de lijst op te nemen requesttypedescriptions met de volgende ondersteunde verzoekcombinaties:
Als uw app naast Apple Pay ook andere kaartbetalingsmethoden aanbiedt, is het absoluut noodzakelijk dat u "THREEDQUERY" in de lijst requesttypedescriptions opneemt, omdat zonder deze 3-D Secure de authenticatie niet zou worden uitgevoerd voor de voornoemde kaartbetalingsmethoden. Als de klant ervoor kiest om de betaling te verwerken met Apple Pay, zal de gateway met opzet de THREEDQUERY automatisch weglaten, omdat die in dat geval niet nodig is.
- [“ACCOUNTCHECK”, “THREEDQUERY”, “AUTH”]
- [“RISKDEC”, “ACCOUNTCHECK”, “THREEDQUERY”, “AUTH”]
- [“RISKDEC”, “ACCOUNTCHECK”, “THREEDQUERY”, “AUTH”, “SUBSCRIPTION”]
- [“RISKDEC”, “THREEDQUERY”, “AUTH”]
- [“RISKDEC”, “THREEDQUERY”, “AUTH”, “SUBSCRIPTION”]
- [“THREEDQUERY”, “ACCOUNTCHECK”, “SUBSCRIPTION”]
- [“THREEDQUERY”, “AUTH”]
- [“THREEDQUERY”, “AUTH”, “RISKDEC”]
- [“THREEDQUERY”, “AUTH”, “SUBSCRIPTION”]
