Інтеграція з ApplePay

Матеріал з apidocs
Версія від 12:44, 14 серпня 2025, створена Nozdrina.viktoriia (обговорення | внесок)
(різн.) ← Попередня версія | Поточна версія (різн.) | Новіша версія → (різн.)
Перейти до: навігація, пошук

Merchant API

Головна сторінка

(Токенізація з передачею даних картки у запиті

Загальні вимоги

  1. Ваш сайт повинен працювати за схемою HTTPS та підтримувати протокол TLS 1.2;
  2. Потрібно погодитись з умовами надання послуг Apple Pay;
  3. Необхідно укласти договір із Easypay.ua.


Оплата з платіжної сторінки EasyPay

При такому способі підключення немає потреби у додаткових інтеграціях. Кнопка Apple Pay буде відображена на сторінці оплати EasyPay


Оплата ApplePay з додатку

Вимоги:

  1. Необхідно мати акаунт у Apple Developer, в який потрібно зареєструвати індивідуальний Merchant ID
  2. Необхідно дотримуватися вимоги до брендування


Реєстрація та перевірка в системі ApplePay

  1. Зареєструйте MerchantID та надішліть до EasyPay:
    1. Увійдіть до свого облікового запису Apple Developer Account.
    2. Перейдіть до розділу «Certificates, Identifiers & Profiles».
    3. У розділі "Identifiers" виберіть "Merchant IDs".
    4. Додайте новий Merchant ID, натиснувши на "+" у верхньому правому куті екрана.
    5. Заповніть поля * і натисніть «Continue».
    6. Натисніть Register, щоб підтвердити введені дані.
    7. Повідомте EasyPay ваш MerchantID.


💡 Примітка


Description — опис.
Identifier — домен вашого сайту у зворотному порядку з додаванням merchant на початку.

Приклад: сайт shop.ua → merchant.ua.shop


  1. Отримайте від EasyPay сформований CSR-файл, який буде необхідний для подальших кроків.
  2. Сформуйте Apple Pay Payment Processing Certificate та надішліть до EasyPay:
    1. Увійдіть до свого облікового запису Apple Developer Account.
    2. Перейдіть до розділу «Certificates, Identifiers & Profiles».
    3. У розділі "Identifiers" виберіть "Merchant IDs".
    4. Виберіть створений вами Merchant ID та натисніть «Edit».
    5. У розділі Apple Pay Payment Processing Certificate, натисніть "Create Certificate".
    6. На наступному екрані натисніть Continue.
    7. Візьміть отриманий від EasyPay CSR-файл і завантажте його на сайт, натиснувши Choose File, а потім Continue.
    8. Завантажте згенерований сертифікат.
    9. Надішліть сертифікат (файл apple_pay.cer) до EasyPay


Технічна інтеграція з ApplePay

1. Щоб інтегрувати Apple Pay у мобільний додаток, дотримуйтесь інструкцій за посиланням: developer.apple.com


Приклад відповіді ApplePay 

{
 "paymentData":
  {
    "version":"EC_v1",    "data":"FDXK/fkIXGh07D5QU5eUK3ZK8BxKk6syu+Hf0DH6DBZ8/loNHFWHULxsmfIAyaKzvkUjm2dHaR36pS4x8UXuQ3JhzeB7AfDmZsP8JcL16OOyZKZP3JjOwdkUVvzUyPWtjtlrtXDaBmJ5jPcT8bgnLZV/7RcC9HpRkdmUqVyJ042wAvPNxF7SVt57PcMyMeccVL6yWUk6N2oV7ESFoGVbAeJdpn5zZT8lebigrnhZRhvwoJ5ZJ/dGK9UZDP/swhH8nMLjK620Wu9rvidhsSheJCwM2sCH27fKpeEO2x+vWaLlL9ukwDms9ciOGvSyb+tDvRD9MheecGri1XCC6DxQT5JkHDH7mi1vev0QFjjVY6bmh26iNC0lIB4FKVznNv03yjkKNJhEMbp/clv4",    "signature":"UdHwQwMC4wLKAqoCiGJmh0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlcm9vdGNhZzMuY3JsMA4GA1UdDwEB/wQEAwIBBjAQBgoqhkJvjg3qQ0QAAAAAAAA=",
    "header":
    {      "ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXaMJN7PRXhkoMa1n1wOnut4KIkIX0WuyXenzRukdDUzo/GZ+TRqTSPjZDOPoZkisqifaroXUJZP9xCUlJQ3iqQ==",
      "publicKeyHash":"48145ri0BI4zYNGguvfW+7qJc3kQlcGdil64a4cg+Ag=",
      "transactionId":"cd80b9fc31c9a850c14c697bd4c258aa51e63bf72bba46394eebbc3fae1b58e4"
    }
  },
  "paymentMethod":
  {
    "displayName":"MasterCard 5179",
    "network":"MasterCard",
    "type":"debit"
  },  "transactionIdentifier":"CD80B9FC31C9A850C14C697BD4C258AA51E63BF72BBA46394EEBBC3FAE1B58E4"
}

2. Надішліть paymentData в поле userPaymentInstrument / token в Easypay (Створення замовлення).

Приклад запиту createOrder:

{
  "order":{
    "serviceKey":"MERCHANT-TEST",
    "orderId":"test_20210309-171148",
    "description":"Test payment",
    "amount":"1"
  },
  "userPaymentInstrument":{
    "instrumentType":"ApplePay",
    "token":"{\"paymentData\": {\"version\":\"EC_v1\",  \"data\":\"FDXK\/fkIXGh07D5QU5eUK3ZK8BxKk6syu+Hf0DH6DBZ8\/loNHFWHULxsmfIAyaKzvkUjm2dHaR36pS4x8UXuQ3JhzeB7AfDmZsP8JcL16OOyZKZP3JjOwdkUVvzUyPWtjtlrtXDaBmJ5jPcT8bgnLZV\/7RcC9HpRkdmUqVyJ042wAvPNxF7SVt57PcMyMeccVL6yWUk6N2oV7ESFoGVbAeJdpn5zZT8lebigrnhZRhvwoJ5ZJ\/dGK9UZDP\/swhH8nMLjK620Wu9rvidhsSheJCwM2sCH27fKpeEO2x+vWaLlL9ukwDms9ciOGvSyb+tDvRD9MheecGri1XCC6DxQT5JkHDH7mi1vev0QFjjVY6bmh26iNC0lIB4FKVznNv03yjkKNJhEMbp\/clv4\",  \"signature\":\"UdHwQwMC4wLKAqoCiGJmh0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlcm9vdGNhZzMuY3JsMA4GA1UdDwEB\/wQEAwIBBjAQBgoqhkJvjg3qQ0QAAAAAAAA=\",\"header\":{  \"ephemeralPublicKey\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXaMJN7PRXhkoMa1n1wOnut4KIkIX0WuyXenzRukdDUzo\/GZ+TRqTSPjZDOPoZkisqifaroXUJZP9xCUlJQ3iqQ==\", \"publicKeyHash\":\"48145ri0BI4zYNGguvfW+7qJc3kQlcGdil64a4cg+Ag=\",\"transactionId\":\"cd80b9fc31c9a850c14c697bd4c258aa51e63bf72bba46394eebbc3fae1b58e4\"}  },  \"paymentMethod\":  {   \"displayName\":\"MasterCard 5179\",\"network\":\"MasterCard\",\"type\":\"debit\"  },  \"transactionIdentifier\":\"CD80B9FC31C9A850C14C697BD4C258AA51E63BF72BBA46394EEBBC3FAE1B58E4\"}",
    "gatewayMerchantId":"{ApplePayMerchantId}"
  }
}

Оплата ApplePay з сайту

Вимоги:

  1. Необхідно мати акаунт у Apple Developer, до якого потрібно зареєструвати індивідуальний Merchant ID.
  2. Необхідно дотримуватися вимог до брендування.


Реєстрація та перевірка в системі Apple Pay

  1. Зареєструйте MerchantID та надішліть до EasyPay:
    1. Увійдіть до свого облікового запису Apple Developer Account.
    2. Перейдіть до розділу «Certificates, Identifiers & Profiles».
    3. У розділі "Identifiers" виберіть "Merchant IDs".
    4. Додайте новий Merchant ID, натиснувши на "+" у верхньому правому куті екрана.
    5. Заповніть поля * і натисніть «Continue».
    6. Натисніть Register, щоб підтвердити введені дані.
    7. Повідомте EasyPay ваш MerchantID.


💡 Примітка


Description — опис.
Identifier — домен вашого сайту у зворотному порядку з додаванням merchant на початку.

Приклад: сайт shop.ua → merchant.ua.shop


  1. Отримайте від EasyPay сформований CSR-файл, який буде необхідний для подальших кроків.
  2. Сформуйте Apple Pay Payment Processing Certificate та надішліть до EasyPay:
    1. Увійдіть до свого облікового запису Apple Developer Account.
    2. Перейдіть до розділу «Certificates, Identifiers & Profiles».
    3. У розділі "Identifiers" виберіть "Merchant IDs".
    4. Виберіть створений вами Merchant ID та натисніть «Edit».
    5. У розділі Apple Pay Payment Processing Certificate, натисніть "Create Certificate".
    6. На наступному екрані натисніть Continue.
    7. Візьміть отриманий від EasyPay CSR-файл і завантажте його на сайт, натиснувши Choose File, а потім Continue.
    8. Завантажте згенерований сертифікат.
    9. Надішліть сертифікат (файл apple_pay.cer) до EasyPay
  3. Зареєструйте та підтвердіть свій домен:
    1. Увійдіть до свого облікового запису Apple Developer Account.
    2. Перейдіть до розділу «Certificates, Identifiers & Profiles».
    3. У розділі "Identifiers" виберіть "Merchant IDs".
    4. Виберіть створений вами Merchant ID та натисніть «Edit».
    5. У розділі "Merchant Domains" натисніть "Add Domain".
    6. Введіть ім'я домену та натисніть "Continue" *.
    7. Завантажте файл apple-developer-merchantid-domain-association.txt.
    8. Збережіть файл на сервері від Apple.
    9. Натисніть Verify.


💡 Примітка

Домен повинен підтримувати HTTPS.


  1. Створіть Apple Pay Merchant Identity Certificate:
    1. Увійдіть до свого облікового запису Apple Developer Account.
    2. Перейдіть до розділу «Certificates, Identifiers & Profiles».
    3. У розділі "Identifiers" виберіть "Merchant IDs".
    4. Виберіть створений вами Merchant ID та натисніть «Edit».
    5. У розділі Apple Pay Merchant Identity Certificate натисніть Create Certificate.
    6. Виконайте дії, описані на сайті Apple, а потім натисніть «Continue».
    7. Скопіюйте згенерований CSR-файл, вибравши Choose File, а потім Continue.
    8. Завантажте згенерований сертифікат (merchant_id.cer) і відкрийте його у програмі Keychain Access на комп'ютері Mac.
    9. У Keychain Access виберіть сертифікат, що імпортується, та експортувати його у формат .p12 (Personal Information Exchange).
    10. Виконайте команду: openssl pkcs12 -in merchant_id.p12 -out merchant_id.pem -nodes -clcerts
    11. Скопіюйте створений сертифікат у форматі PEM на сервер. Це буде потрібно для створення Apple Pay Payment Session в процесі перевірки магазину.


Технічна інтеграція з ApplePay

Для створення сертифікату (-ів) від Партнера потрібні:

  1. Country Name (2 letter code) [AU]: ?
  2. State or Province Name (full name) [Some-State]: ?
  3. Locality Name (eg, city) []: ?
  4. Organization Name (eg, company) [Internet Widgits Pty Ltd]: ?
  5. Organizational Unit Name (eg, section) []: ?
  6. Common Name (e.g. server FQDN or YOUR name) []:?
  7. Email Address []: ?


Повідомте, чи буде оплата тільки в додатку, або також і на WEB.

Щоб інтегрувати Apple Pay на сайт, дотримуйтесь інструкцій за посиланням

1. Перевірте можливість оплати з Apple Pay. Виконується перевірка, підтримує або браузер оплату з Apple Pay, а також є у Wallet картку, якою можна оплачувати. 


if (window.ApplePaySession) {
    var promise = ApplePaySession.canMakePaymentsWithActiveCard({YOUR_MERCHANT_ID});
    promise.then(function(canMakePayments) {
        if (canMakePayments)
    });
} else {
}

2. Сформуйте структуру платежу для сесії

document.getElementById("apple-pay-button").onclick = function(event) {
    var paymentRequest = {
        currencyCode: 'UAH',
        countryCode: 'UA',
        total: {
            label: {PRODUCT_NAME},
            amount: {PAYMENT_AMOUNT}
        },
        merchantCapabilities: ['supports3DS'],
        supportedNetworks: ['masterCard', 'visa']
    };

var session = new ApplePaySession(3, paymentRequest)

3. Відкрити платіжну сесію з Apple, отримати від них paymentData:

POST /api/applePay/validateSession

headers 

--header "Content-Type: application/json"
--header "AppId: cd7fde18-15db-4d94-a91b-7cf8edd81209" 
--header "PageId: 3e7bf353-417a-410c-a22e-df8bdcccb760"
--header "PartnerKey: easypay-test"
--header "locale: ua"

body
{
  "url": "https://apple-pay-gateway.apple.com/paymentservices/startSession",
  "merchantIdentifier": "string", /ідентифікатор мерчанту в Apple/
  "displayName": "test", /ідентифікатор магазина/послуги/товару (латиниці) ; буде відображатися в toolBar/
  "initiative": "web", /Канал оплати/
  "initiativeContext": "string" /Доменне ім’я, Доменное имя, пов'язане із сертифікатом Apple Identity/
}

*response з цього методу передається в сесію Apple, після чого при успішній авторизації платежу, повернеться до необхідний для завершення платежу.

4. Приклад відповіді ApplePay

{
 "paymentData":
  {
    "version":"EC_v1",    "data":"FDXK/fkIXGh07D5QU5eUK3ZK8BxKk6syu+Hf0DH6DBZ8/loNHFWHULxsmfIAyaKzvkUjm2dHaR36pS4x8UXuQ3JhzeB7AfDmZsP8JcL16OOyZKZP3JjOwdkUVvzUyPWtjtlrtXDaBmJ5jPcT8bgnLZV/7RcC9HpRkdmUqVyJ042wAvPNxF7SVt57PcMyMeccVL6yWUk6N2oV7ESFoGVbAeJdpn5zZT8lebigrnhZRhvwoJ5ZJ/dGK9UZDP/swhH8nMLjK620Wu9rvidhsSheJCwM2sCH27fKpeEO2x+vWaLlL9ukwDms9ciOGvSyb+tDvRD9MheecGri1XCC6DxQT5JkHDH7mi1vev0QFjjVY6bmh26iNC0lIB4FKVznNv03yjkKNJhEMbp/clv4",    "signature":"UdHwQwMC4wLKAqoCiGJmh0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlcm9vdGNhZzMuY3JsMA4GA1UdDwEB/wQEAwIBBjAQBgoqhkJvjg3qQ0QAAAAAAAA=",
    "header":
    {      "ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXaMJN7PRXhkoMa1n1wOnut4KIkIX0WuyXenzRukdDUzo/GZ+TRqTSPjZDOPoZkisqifaroXUJZP9xCUlJQ3iqQ==",
      "publicKeyHash":"48145ri0BI4zYNGguvfW+7qJc3kQlcGdil64a4cg+Ag=",
      "transactionId":"cd80b9fc31c9a850c14c697bd4c258aa51e63bf72bba46394eebbc3fae1b58e4"
    }
  },
  "paymentMethod":
  {
    "displayName":"MasterCard 5179",
    "network":"MasterCard",
    "type":"debit"
  },  "transactionIdentifier":"CD80B9FC31C9A850C14C697BD4C258AA51E63BF72BBA46394EEBBC3FAE1B58E4"
}

5. Надішліть paymentData в поле userPaymentInstrument / token в Easypay (Створення замовлення). Перед цим потрібно викликати метод EasyPayApi CreateApp. Приклад запиту  createOrder:

{
  "order":{
    "serviceKey":"MERCHANT-TEST",
    "orderId":"test_20210309-171148",
    "description":"Test payment",
    "amount":"1"
  },
  "userPaymentInstrument":{
    "instrumentType":"ApplePay",
    "token":"{\"paymentData\": {\"version\":\"EC_v1\",  \"data\":\"FDXK\/fkIXGh07D5QU5eUK3ZK8BxKk6syu+Hf0DH6DBZ8\/loNHFWHULxsmfIAyaKzvkUjm2dHaR36pS4x8UXuQ3JhzeB7AfDmZsP8JcL16OOyZKZP3JjOwdkUVvzUyPWtjtlrtXDaBmJ5jPcT8bgnLZV\/7RcC9HpRkdmUqVyJ042wAvPNxF7SVt57PcMyMeccVL6yWUk6N2oV7ESFoGVbAeJdpn5zZT8lebigrnhZRhvwoJ5ZJ\/dGK9UZDP\/swhH8nMLjK620Wu9rvidhsSheJCwM2sCH27fKpeEO2x+vWaLlL9ukwDms9ciOGvSyb+tDvRD9MheecGri1XCC6DxQT5JkHDH7mi1vev0QFjjVY6bmh26iNC0lIB4FKVznNv03yjkKNJhEMbp\/clv4\",  \"signature\":\"UdHwQwMC4wLKAqoCiGJmh0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlcm9vdGNhZzMuY3JsMA4GA1UdDwEB\/wQEAwIBBjAQBgoqhkJvjg3qQ0QAAAAAAAA=\",\"header\":{  \"ephemeralPublicKey\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXaMJN7PRXhkoMa1n1wOnut4KIkIX0WuyXenzRukdDUzo\/GZ+TRqTSPjZDOPoZkisqifaroXUJZP9xCUlJQ3iqQ==\", \"publicKeyHash\":\"48145ri0BI4zYNGguvfW+7qJc3kQlcGdil64a4cg+Ag=\",\"transactionId\":\"cd80b9fc31c9a850c14c697bd4c258aa51e63bf72bba46394eebbc3fae1b58e4\"}  },  \"paymentMethod\":  {   \"displayName\":\"MasterCard 5179\",\"network\":\"MasterCard\",\"type\":\"debit\"  },  \"transactionIdentifier\":\"CD80B9FC31C9A850C14C697BD4C258AA51E63BF72BBA46394EEBBC3FAE1B58E4\"}",
    "gatewayMerchantId":"{YOUR_MERCHANT_ID}"
  }
}
Отримано з https://apidocs.easypay.ua/index.php?title=Інтеграція_з_ApplePay&oldid=2127