When a customer uses Apple Pay™ to pay for goods or services on a merchant’s website or mobile app, use the Apple Pay JS API to retrieve the customer’s encrypted payment details. You can then use our API to run a transaction with the encrypted details.

Before you begin

Apple Pay merchant ID

To add Apple Pay to your integration, you must have an Apple Pay merchant ID. For information about how to sign up for an Apple Pay merchant ID, go to https://developer.apple.com/documentation/applepaywebmerchantregistrationapi/registering_with_apple_pay_and_applying_to_use_the_api.

Bearer tokens

Use our Identity Service to generate a Bearer token to include in the header of your requests to our API. To generate your Bearer token, include your API key in the x-api-key parameter in the header of a POST request, and then send it to our Identity Service.
Test endpoint: https://identity.uat.payroc.com/authorize
Production endpoint: https://identity.payroc.com/authorize

You need to generate a new Bearer token before the previous Bearer token expires.

Example request

curl --location --request POST  'https://identity.payroc.com/authorize' --header 'x-api-key: <api key>'

Example response

If your request is successful, we return a response that contains your Bearer token, information about its scope, and when it expires.

{
"access_token": "eyJhbGc....adQssw5c",
"expires_in": 3600,
"scope": "service_a service_b",
"token_type": "Bearer"
}

Headers

To create the header of each POST request to our API, you must include the following parameters:

Content-Type: Include application/json as the value for this parameter.
Authorization: Include your Bearer token in this parameter.
Idempotency-Key: Include a UUID v4 to make the request idempotent.

curl
-H "Content-Type: application/json"
-H "Authorization: <Bearer token>"
-H "Idempotency-Key: <UUID v4>"

Errors

If your request is unsuccessful, we return an error. For more information about errors, see Errors.

Integration steps

Create an Apple Pay certificate:
a. Create a certificate signing request (CSR).
b. Upload the CSR to Apple.
c. Send us the Apple Pay certificate.
Integrate with the Apple Pay JS API to retrieve the encrypted payment details.
Run a sale.
Register your integration.

Step 1. Create an Apple Pay certificate

You can create only one Apple Pay certificate from a CSR. If you switch your Apple Pay merchant ID, you must create a new CSR and Apple Pay certificate.

To create an Apple Pay certificate, complete the following steps:

Create a CSR

Log in to the Self Care Portal or the UAT version of the Self Care Portal.
From the side menu, select Settings > Apple Pay Certificate.
Enter the following details:
a. Email address – Email address that you want to add to the certificate.
b. Common name – Name that you want to add to the certificate.
From the Algorithm dropdown menu, select ECC (256 bits).
Select CREATE .CSR.
Select DOWNLOAD .CSR.

Upload the CSR to Apple

Log in to your Apple Developer account.
Upload the CSR.
Download your Apple Pay certificate.

Send us the Apple Pay certificate

From the Self Care Portal, complete the following steps:

Select CHOOSE FILE, and then upload your Apple Pay certificate.
Select SAVE.

Step 2. Integrate with the Apple Pay JS API

To integrate with the Apple Pay JS API, go to https://developer.apple.com/apple-pay/. After you integrate with the Apple Pay JS API, you can send requests to the Apple Pay JS API to retrieve encrypted details that represent the customer’s payment details. Convert the encrypted payment details into hexadecimal format.

Step 3. Run a sale

Important: If you use Apple Pay as the payment method, you can’t use our API to save the customer's payment details as a secure token.

To run a sale, send a POST request to our Payments endpoint. Test endpoint: https://api.uat.payroc.com/v1/payments
Production endpoint: https://api.payroc.com/v1/payments In your request, send the following parameters in the paymentMethod object:

type – Provide a value of digitalWallet.
serviceProvider – Provide a value of apple.
encryptedData – Provide the encrypted payment details that you retrieved from the Apple Pay JS API in hexadecimal format.

For more information about how to run other transaction types with our API, go to our API Explorer.

Example request

{
    "channel": "web",
    "processingTerminalId": "3204001",
    "operator": "001",
    "order": {
        "orderId": "1234567890W",
        "description": "Card Transaction (WEB) - Sale - digital_wallet (APPLE)",
        "amount": 99,
        "currency": "USD"
    },
    "paymentMethod": {
        "type": "digitalWallet",
        "serviceProvider": "apple",
        "encryptedData": "7b22746f6b656e223a7b227061796d656e7444617461225a7b2276657273696f6e223a2245435f7631222c2264617461225a2275417239476a6470394869492f676f634f4d7068706c666c415a624172557050344f304149797a305666724b4e6c73576a6478523356566b793955746476387145335052523469772b4a5a4944426661786664576568734874514d37416a6c54524b5572587a6564524c367577685257676f387746463157626f4f674546776a64394155306857375944394a496c55715636494672792f4d3157375433314c72366e3044696e4f645454426b6e66686a5339424234694f2f476431505152715946545a48365558517647774169616c576d2f727971784e4348486a755a6e6a424168495269676530756f46645a51304331417733726c684b564c4b6b656c4c2f47682b63566b3248415655706241424566316b4f413445336f34336158537139427a45544d706375634279714d5971305949327945777368566147734133472f5755472b683951517243567630486e536f5a685a6549793748576b6d72416636523563564b57795572323667454d7735767672434c7856557a4e785878594a4c387248584d3970377a37616348795758627347764f392f326c7572506f4b716e386e53543843426c222c227369676e6174757265223a224d494147435371475349623344514548417143414d49414341514578447a414e42676c67686b67425a514d45416745464144434142676b71686b69473977304242774541414b43414d494944356a4343413475674177494241674949614744326d646e4d70773877436759494b6f5a497a6a304541774977656a45754d437747413155454177776c51584277624755675158427762476c6a5958527062323467535735305a5764795958527062323467513045674c5342484d7a456d4d435147413155454377776451584277624755675132567964476c6d61574e6864476c76626942426458526f62334a7064486b78457a415242674e5642416f4d436b46776347786c49456c7559793478437a414a42674e5642415954416c56544d423458445445324d4459774d7a45344d5459304d466f58445449784d4459774d6a45344d5459304d466f77596a456f4d43594741315545417777665a574e6a4c584e7463433169636d39725a58497463326c6e626c3956517a51745530464f52454a50574445554d424947413155454377774c6155395449464e356333526c62584d78457a415242674e5642416f4d436b46776347786c49456c7559793478437a414a42674e5642415954416c56544d466b77457759484b6f5a497a6a3043415159494b6f5a497a6a30444151634451674145676a443971384f63393134674c46445a6d305553356a666971514864624c50677363314c556d65592b4d394f766567614a616a43486b777a3363364f4b70624339712b686b774e46784f68365243624f6c5273536c614f43416845776767494e4d45554743437347415155464277454242446b774e7a4131426767724267454642516377415959706148523063446f764c32396a633341755958427762475575593239744c32396a633341774e433168634842735a5746705932457a4d444977485159445652304f424259454641496b4d417561377531474d5a656b706c6f706e6b4a78676878464d41774741315564457745422f7751434d414177487759445652306a42426777466f4155492f4a4a78452b54354f386e357354324b47772f6f7276394c6b73776767456442674e5648534145676745554d4949424544434341517747435371475349623359325146415443422f6a4342777759494b77594242515548416749776762594d67624e535a5778705957356a5a5342766269423061476c7a49474e6c636e52705a6d6c6a5958526c49474a35494746756553427759584a306553426863334e316257567a4947466a593256776447467559325567623259676447686c4948526f5a5734675958427762476c6a59574a735a53427a644746755a4746795a4342305a584a7463794268626d5167593239755a476c3061573975637942765a6942316332557349474e6c636e52705a6d6c6a5958526c4948427662476c6a65534268626d51675932567964476c6d61574e6864476c7662694277636d466a64476c6a5a53427a644746305a57316c626e527a4c6a4132426767724267454642516343415259716148523063446f764c33643364793568634842735a53356a623230765932567964476c6d61574e68644756686458526f62334a7064486b764d44514741315564487751744d4373774b61416e6f43574749326830644841364c79396a636d77755958427762475575593239744c3246776347786c59576c6a59544d7559334a734d41344741315564447745422f775145417749486744415042676b71686b694739324e6b42683045416755414d416f4743437147534d343942414d4341306b414d4559434951446148474f75692b583254343452364756704e376d326e456372365436734d6a4f685a354e75536f316567774968414c31612b2f68703838444b4a3073763365543346785763733731786d624c4b442f514a336d576167724a4e4d494943376a4343416e5767417749424167494953573076767a715932706377436759494b6f5a497a6a3045417749775a7a45624d426b4741315545417777535158427762475567556d397664434244515341744945637a4d5359774a4159445651514c44423142634842735a5342445a584a3061575a7059324630615739754945463164476876636d6c30655445544d424547413155454367774b51584277624755675357356a4c6a454c4d416b474131554542684d4356564d774868634e4d5451774e5441324d6a4d304e6a4d775768634e4d6a6b774e5441324d6a4d304e6a4d77576a42364d5334774c4159445651514444435642634842735a5342426348427361574e6864476c766269424a626e526c5a334a6864476c7662694244515341744945637a4d5359774a4159445651514c44423142634842735a5342445a584a3061575a7059324630615739754945463164476876636d6c30655445544d424547413155454367774b51584277624755675357356a4c6a454c4d416b474131554542684d4356564d775754415442676371686b6a4f5051494242676771686b6a4f50514d4242774e4341415477467847454764646b68645561586957424233626f674b4c76336e75755465434e2f45755434544e5731575a624e613469304a643244534a4f65376f492f5859587a6f6a4c6472746d634c374936436d452f3152466f3448334d4948304d45594743437347415155464277454242446f774f444132426767724267454642516377415959716148523063446f764c32396a633341755958427762475575593239744c32396a633341774e433168634842735a584a766233526a5957637a4d42304741315564446751574242516a386b6e455435506b3779666d7850596f62442b69752f3075537a415042674e5648524d4241663845425441444151482f4d42384741315564497751594d426141464c7577337146594d3469617049715a3372363936362f61797953724d44634741315564487751774d4334774c4b41716f4369474a6d6830644841364c79396a636d77755958427762475575593239744c3246776347786c636d397664474e685a7a4d7559334a734d41344741315564447745422f77514541774942426a415142676f71686b694739324e6b4267494f424149464144414b42676771686b6a4f5051514441674e6e4144426b416a41367a334b445552615a735962374e634e57796d4b2f394266743251393154614b4f767647636756354374346e346d506562575a2b593155454e6a353370777634434d44497431555168734b4d4664327864387a67376b476639463377734957325754385a796159495362315434656e30626d63756243596b685951615a44776d53485141414d5949426a444343415967434151457767595977656a45754d437747413155454177776c51584277624755675158427762476c6a5958527062323467535735305a5764795958527062323467513045674c5342484d7a456d4d435147413155454377776451584277624755675132567964476c6d61574e6864476c76626942426458526f62334a7064486b78457a415242674e5642416f4d436b46776347786c49456c7559793478437a414a42674e5642415954416c56544167686f5950615a3263796e447a414e42676c67686b67425a514d4541674546414b43426c54415942676b71686b69473977304243514d784377594a4b6f5a496876634e415163424d42774743537147534962334451454a42544550467730784f44417a4d6a6b784d7a4d324d4456614d436f4743537147534962334451454a4e4445644d4273774451594a59495a49415755444241494242514368436759494b6f5a497a6a3045417749774c77594a4b6f5a496876634e41516b454d5349454944677a61314873582b6f334d4c6e2f6176674a2f6141753877737a426746746d397a6e433144506e426a314d416f4743437147534d343942414d43424563775251496841495870622b4c4f2f784f34497953773743697765623737426a56456d67472f5a6562317a416f7544354d6d416942566e4672327759335932462f72444867765a3137516443634b70414f782f42615773474c4a756b3657574141414141414141413d3d222c22686561646572223a7b22657068656d6572616c5075626c69634b6579223a224d466b77457759484b6f5a497a6a3043415159494b6f5a497a6a304441516344516741454c3846326b3952584c56746c5979564353624b79694e394337526669676e52386f504a38774e4c6f575232334e317a424a4e7153364e38346e634e7a347549384b657576446147526d6c435445396756346f776d39413d3d222c227075626c69634b657948617368223a226f587657624266474c43494d6c4158776f473553716f6747633930516f6f5657636f5a646e3379555042303d222c227472616e73616374696f6e4964223a2235333332356537653336396163313364373461313833623161653839626236386362636162383330646263633163363861373632383339616639646434616331227d7d2c227061796d656e744d6574686f64223a7b22646973706c61794e616d65223a22566973612030343932222c226e6574776f726b223a2256697361222c2274797065223a226465626974227d2c227472616e73616374696f6e4964656e746966696572223a2235333332354537453336394143313344373441313833423141453839424236384342434142383330444243433143363841373632383339414639444434414331227d7d"
    }
}

Step 4. Register your integration

To complete your integration and run live transactions with Apple Pay, contact our Integrations Team at [email protected].

Add Apple Pay to your integration

Example request

Example response