Інтеграція з Apple Pay

1. Вступ

Apple Pay надає простий та безпечний спосіб проведення платежів у додатках iOS, watchOS та веб-сайтах Safari. Використовуючи Face ID, Touch ID або двічі клацнувши Apple Watch, користувачі можуть швидко і безпечно передавати свої платіжні дані для оплати.

Попередні умови

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

2. Підключення через сторінку Portmone.com

При такому способі підключення немає необхідності у додаткових інтеграціях. Кнопка Apple Pay буде відображена на сторінці оплати Portmone.com. Керувати методами оплати та порядком, в якому відображаються платіжні інструменти (в тому числі й Apple Pay), можливо за допомогою JSON-запиту (див. розділ 3.2 документації) або звернувшись до менеджера із співпраці.

3. Підключення через Apple Pay API

Попередні умови

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

Кроки для інтеграції Apple Pay у мобільний додаток

Крок 1. Реєстрація та перевірка у системі Apple Pay

Ознайомтесь з відео-інструкцією, яка детально пояснює реєстрацію та перевірку у системі Apple Pay. Детальна відео-інструкція з налаштування Apple Pay.

1. Реєстрація Merchant ID
Ідентифікатор мерчанта унікально ідентифікує вас в Apple Pay як мерчанта, який може приймати платежі. Ідентифікатор мерчанта ніколи не втрачає чинності, і ви можете використовувати один і той самий ідентифікатор для кількох додатків.

• Увійдіть до облікового запису Apple Developer Account.
• Перейдіть у розділ Certificates, Identifiers & Profiles.
• Натисніть Identifiers у боковій панелі, а потім кнопку додавання (+) у верхньому лівому куті.
• Виберіть Merchant IDs, а потім натисніть Continue.
• Введіть Description та Identifier*, після чого натисніть Continue.
• Перегляньте налаштування та натисніть Register.
• Надішліть ваш Merchant ID до Portmone на адресу: [email protected].
• Отримайте зворотнім листом CSR-файл, сформований Portmone, який буде необхідним для створення Apple Pay Payment Processing Certificate.

Примітка:
Description – опис мерчанта.
Identifier – домен вашого сайту у зворотному порядку з додаванням "merchant" на початку (наприклад, для сайту shop.ua ідентифікатор буде merchant.ua.shop).

2. Створення Apple Pay Payment Processing Certificate

Apple Pay Payment Processing Certificate пов’язаний з вашим ідентифікатором мерчанта та використовується для шифрування платіжної інформації. Термін дії сертифіката обробки платежів закінчується кожні 25 місяців. Якщо сертифікат буде відкликано, ви можете створити його знову.

• Увійдіть до облікового запису Apple Developer Account.
• У розділі Certificates, Identifiers & Profiles натисніть Identifiers у боковій панелі.
• У розділі Identifiers використайте фільтр у верхньому правому куті та виберіть Merchant IDs.
• Справа оберіть ваш ідентифікатор мерчанта*.
• У розділі Apple Pay Payment Processing Certificate натисніть Create Certificate.
• Завантажте CSR-файл, отриманий від Portmone, натиснувши Choose File, а потім Continue.
• Натисніть Download.
• Надішліть завантажений сертифікат (apple_pay.cer) до Portmone на адресу: [email protected].

Примітка:
Якщо у верхній частині сторінки з’являється банер із повідомленням про необхідність прийняття угоди, натисніть кнопку Review Agreement та дотримуйтесь інструкцій перед продовженням.

Крок 2. Технічна інтеграція з ApplePay

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

2. Надішліть значення paymentData до Portmone API (див. Крок 3).

Приклад набору даних, що повертаються від Apple Pay:

{
  "paymentData":
  {
    "version":"EC_v1",
    "data":"FDXK/fkIXGh07D5QU5eUK3ZK8BxKk6syu+Hf0DH6DBZ8/loNHFWHULxsmfIAyaKzvkUjm2dHaR36pS4x8UXuQ3JhzeB7AfDmZsP8JcL16OOyZKZP3JjOwdkUVvzUyPWtjtlrtXDaBmJ5jPcT8bgnLZV/7RcC9HpRkdmUqVyJ042wAvPNxF7SVt57PcMyMeccVL6yWUk6N2oV7ESFoGVbAeJdpn5zZT8lebigrnhZRhvwoJ5ZJ/dGK9UZDP/swhH8nMLjK620Wu9rvidhsSheJCwM2sCH27fKpeEO2x+vWaLlL9ukwDms9ciOGvSyb+tDvRD9MheecGri1XCC6DxQT5JkHDH7mi1vev0QFjjVY6bmh26iNC0lIB4FKVznNv03yjkKNJhEMbp/clv4",
    "signature":"MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID4zCCA4igAwIBAgIITDBBSVGdVDYwCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE5MDUxODAxMzI1N1oXDTI0MDUxNjAxMzI1N1owXzElMCMGA1UEAwwcZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtUFJPRDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwhV37evWx7Ihj2jdcJChIY3HsL1vLCg9hGCV2Ur0pUEbg0IO2BHzQH6DMx8cVMP36zIg1rrV1O/0komJPnwPE6OCAhEwggINMAwGA1UdEwEB/wQCMAAwHwYDVR0jBBgwFoAUI/JJxE+T5O8n5sT2KGw/orv9LkswRQYIKwYBBQUHAQEEOTA3MDUGCCsGAQUFBzABhilodHRwOi8vb2NzcC5hcHBsZS5jb20vb2NzcDA0LWFwcGxlYWljYTMwMjCCAR0GA1UdIASCARQwggEQMIIBDAYJKoZIhvdjZAUBMIH+MIHDBggrBgEFBQcCAjCBtgyBs1JlbGlhbmNlIG9uIHRoaXMgY2VydGlmaWNhdGUgYnkgYW55IHBhcnR5IGFzc3VtZXMgYWNjZXB0YW5jZSBvZiB0aGUgdGhlbiBhcHBsaWNhYmxlIHN0YW5kYXJkIHRlcm1zIGFuZCBjb25kaXRpb25zIG9mIHVzZSwgY2VydGlmaWNhdGUgcG9saWN5IGFuZCBjZXJ0aWZpY2F0aW9uIHByYWN0aWNlIHN0YXRlbWVudHMuMDYGCCsGAQUFBwIBFipodHRwOi8vd3d3LmFwcGxlLmNvbS9jZXJ0aWZpY2F0ZWF1dGhvcml0eS8wNAYDVR0fBC0wKzApoCegJYYjaHR0cDovL2NybC5hcHBsZS5jb20vYXBwbGVhaWNhMy5jcmwwHQYDVR0OBBYEFJRX22/VdIGGiYl2L35XhQfnm1gkMA4GA1UdDwEB/wQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0kAMEYCIQC+CVcf5x4ec1tV5a+stMcv60RfMBhSIsclEAK2Hr1vVQIhANGLNQpd1t1usXRgNbEess6Hz6Pmr2y9g4CJDcgs3apjMIIC7jCCAnWgAwIBAgIISW0vvzqY2pcwCgYIKoZIzj0EAwIwZzEbMBkGA1UEAwwSQXBwbGUgUm9vdCBDQSAtIEcz***MjM0NjMwWjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATwFxGEGddkhdUaXiWBB3bogKLv3nuuTeCN/EuT4TNW1WZbNa4i0Jd2DSJOe7oI/XYXzojLdrtmcL7I6CmE/1RFo4H3MIH0MEYGCCsGAQUFBwEBBDowODA2BggrBgEFBQcwAYYqaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZXJvb3RjYWczMB0GA1UdDgQWBBQj8knET5Pk7yfmxPYobD+iu/0uSzAPBgNVHRMBAf8EBTADAQH/MB8GA1UdIwQYMBaAFLuw3qFYM4iapIqZ3r6966/ayySrMDcGA1UdHwQwMC4wLKAqoCiGJmh0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlcm9vdGNhZzMuY3JsMA4GA1UdDwEB/wQEAwIBBjAQBgoqhkiG92NkBgIOBAIFADAKBggqhkjOPQQDAgNnADBkAjA6z3KDURaZsYb7NcNWymK/9Bft2Q91TaKOvvGcgV5Ct4n4mPebWZ+Y1UENj53pwv4CMDIt1UQhsKMFd2xd8zg7kGf9F3wsIW2WT8ZyaYISb1T4en0bmcubCYkhYQaZDwmSHQAAMYIBjTCCAYkCAQEwgYYwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTAghMMEFJUZ1UNjANBglghkgBZQMEAgEFAKCBlTAYBgkqhkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0xOTEwMDcwOTAzMzlaMCoGCSqGSIb3DQEJNDEdMBswDQYJYIZIAWUDBAIBBQChCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEINit/iw3WwwTnehkerYBQk/4vdByMbbliBcTPyT7FRiPMAoGCCqGSM49BAMCBEgwRgIhAKvTEMlNfyLdg9slvO6Ignu+y//nAmevtrQa8Yk2qw0/AiEAhivZamhbazis3+5Nd5dZWxgM1gv/PpsAykJvjg3qQ0QAAAAAAAA=",
    "header":
    {
      "ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXaMJN7PRXhkoMa1n1wOnut4KIkIX0WuyXenzRukdDUzo/GZ+TRqTSPjZDOPoZkisqifaroXUJZP9xCUlJQ3iqQ==",
      "publicKeyHash":"48145ri0BI4zYNGguvfW+7qJc3kQlcGdil64a4cg+Ag=",
      "transactionId":"cd80b9fc31c9a850c14c697bd4c258aa51e63bf72bba46394eebbc3fae1b58e4"
    }
  },
  "paymentMethod":
  {
    "displayName":"MasterCard 5179",
    "network":"MasterCard",
    "type":"debit"
  },
  "transactionIdentifier":"CD80B9FC31C9A850C14C697BD4C258AA51E63BF72BBA46394EEBBC3FAE1B58E4"
}

Крок 3.Технічна інтеграція з Portmone.com

До API Portmone.com необхідно надіслати дані paymentData.

Важливо:
Криптограма, отримана з Apple Pay, повинна використовуватися лише один раз у межах однієї транзакції. Повторне використання тієї самої криптограми може призвести до відхилення платежу банком-еквайєром. Для кожної нової транзакції необхідно отримувати нову криптограму з Apple Pay.

Метод: APay

URL: https://www.portmone.com.ua/r3/api/gateway.

Параметри запиту:

Параметр	Опис	Обов'язковий
login	Логін Інтернет-магазину для доступу до управління акаунтом	Так
password	Пароль Інтернет-магазину	Так
aPayMerchantName	Merchant ID у Apple Developer Account	Так
paymentData	Значення параметру paymentData, що отриманий мерчантом у відповіді від системи Apple Pay	Так
payeeId	Унікальний ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
billAmount	Сума оплати. Розділювач крапка. Наприклад: "10.21"	Так
description	Коментар до замовлення / опис призначення платежу	Ні
shopOrderNumber	Номер замовлення (рахунку) у системі Інтернет-магазину	Ні
emailRecipient	Адреса електронної пошти Клієнта	Ні
preauthFlag	Ознака преавторизації платежу (значення "Y" вказує на те, що ця оплата здійснюється з використанням процедури преавторизації, значення "N" – звичайна оплата без преавторизації)	Ні
billCurrency	Валюта проведення платежу. Можливі значення: UAH, USD, EUR, GBP, KZT, (значення без задання – UAH)	Ні
shop_site_id	Канал оплати у системі Portmone	Ні
threeDs	Секція параметрів, що використовується для зазначення URL мерчанта (termUrl або appUrl), на який буде перенаправлено клієнта після успішного проходження перевірки 3D Secure	Ні
termUrl	Необхідно встановити значення "Y" або не використовувати цей параметр	Ні
appUrl	Значення appUrl мерчанта (у разі інтеграції GPay у мобільний додаток)	Ні
clientIp	Значення IP адреси платника	Ні

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

{
    "method":"APay",
    "params": {
        "data":{
            "login":"wdishop",
            "password":"11111111",
            "aPayMerchantName":"",
            "paymentData":{
                "version":"EC_v1",
                "data":"7p8TndxxyLvLxzkD****xnjJj5Gf5vtmHGHEN",
                "signature":"MIAGCSqGSI****b05ZOreRp5zAt+Zx+ukgAAAAAAAA==",
                "header":{
                    "ephemeralPublicKey":"MFkwEwY****hc7lmaYq8I8Nr111pStGhQ==",
                    "publicKeyHash":"48145ri0BI***il64a4cg+Ag=",
                    "transactionId":"16d32ec****da49c41c36a5a6c7cc"
                }
            },
            "payeeId":"11344",
            "billAmount":"1.01",
            "description":"test",
            "shopOrderNumber":"AP-01",
            "attribute1":"",
            "attribute2":"",
            "attribute3":"",
            "attribute4":"",
            "emailRecipient":"",
            "billCurrency":"UAH",
            "preauthFlag":"N",
            "shop_site_id":"",
            "threeDs":{
                "termUrl":"Y",
                "appUrl":"https://portmone2.com/r3/ecommerce/test/master-test-from"
            },
        "clientIp": "127.0.0.7"    
        }
    },
    "id": "1"
}

Параметри відповіді:

Параметр	Опис
status	Результат оплати. Можливі значення: - PAYED – оплата успішна, - REJECTED – відмова, - CREATED – замовлення створено, але не оплачено
errorCode	Код помилки. Якщо значення параметру "0" – оплата успішна. Якщо значення параметру більше за 0 або порожнє – сталася помилка
error	Текст помилки (див. Таблицю кодів відмов)
shopBillId	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com
billAmount	Передана у запиті сума транзакції
billNumber	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів
attribute1	Службове поле, заповнюється на розсуд компанії
attribute2	Службове поле, заповнюється на розсуд компанії
attribute3	Службове поле, заповнюється на розсуд компанії
attribute4	Службове поле, заповнюється на розсуд компанії
cardMask	Маска Картки/ Токену платника
actionMPI	URL банку, на який треба перенаправити клієнта для проходження 3D Secure перевірки
pareq	Параметр, який треба передати на actionMPI при проходженні 3D Secure перевірки
authCode	Код авторизації
description	Коментар до замовлення / опис призначення оплати. До 250 символів
lang	Мова відповіді. Залежить від локалізації endpoint, на який надсилали запит*
md	Параметр, який треба передати на actionMPI при проходженні 3D Secure перевірки
isNeed3DS	Ознака необхідності проходження перевірки 3D Secure ("Y" – необхідно пройти процедуру перевірки 3D Secure, "N" – додаткові дії не потрібні)
token	Значення Токену для подальших оплат. Для методів оплати GPay та APay не формується
billCurrency	Валюта платежу
transactionId	Ідентифікатор транзакції в системі банка-еквайера
termUrl	URL мерчанта, на який мають повернутись параметри відповіді від банку після проходження 3D Secure. Значення генерується системою Portmone
successUrl	Значення appUrl мерчанта, на який мають повернутись параметри відповіді від банку після проходження 3D Secure (якщо це значення було передане в параметрі appUrl у запиті на оплату)
pdfUrl	Посилання для збереження квитанції про оплату. Надається клієнтові лише якщо status=PAYED
shop_site_id	Канал оплати у системі Portmone

Примітка: * – для отримання локалізованих текстів відмов необхідно надсилати запит на відповідний endpoint:

https://www.portmone.com.ua/r3/api/gateway – стандартно українською мовою https://www.portmone.com.ua/r3/uk/api/gateway – для відповідей українською мовою https://www.portmone.com.ua/r3/en/api/gateway – для відповідей англійською мовою

Приклад успішної відповіді:

{
    "result": {
        "status": "PAYED",
        "errorCode": "0",
        "error": "",
        "shopBillId": "550298815",
        "billAmount": "1.01",
        "billNumber": "SHP-00000002",
        "attribute1": "",
        "attribute2": "",
        "attribute3": "",
        "attribute4": "",
        "cardMask": "535560******3735",
        "actionMPI": "",
        "pareq": "",
        "authCode": "67037Z",
        "description": "test payment",
        "lang": "uk",
        "md": "",
        "isNeed3DS": "N",
        "token": "",
        "billCurrency": "UAH",
        "transactionId": "927500948048",
        "pdfUrl": "https://www.portmone.com.ua/r3/services/receipts/get-receipts/shop-bill-id/35357a20f10b49519794e81b48b20d0402cd2b7654553048021cb230400befdf94bacfbb12bd77983adae9422fbcc51cf0987a171403f08b33b2d119249845bad4e457",
        "shop_site_id":""
    },
    "id": "1"
}

Приклад відмови:

{
    "result": {
        "status": "REJECTED",
        "errorCode": "5",
        "error": "Transactions has exceeded the limit by your bank",
        "shopBillId": "5530964511",
        "billAmount": "1",
        "billNumber": "P55309624511",
        "attribute1": "A",
        "attribute2": "",
        "attribute3": "",
        "attribute4": "",
        "cardMask": "535560******3735",
        "actionMPI": "",
        "pareq": "",
        "authCode": "",
        "description": "test payment",
        "lang": "en",
        "md": "",
        "isNeed3DS": "N",
        "token": "",
        "billCurrency": "UAH",
        "transactionId": "928199458716",
        "pdfUrl": "",
        "shop_site_id":""
    },
    "id": "1"
}

Приклад відповіді, якщо необхідна 3D Secure перевірка:

{
    "result": {
        "status": "CREATED",
        "errorCode": "0",
        "error": "",
        "shopBillId": "663526924",
        "billAmount": "1.2",
        "billNumber": "123456.14052020.05",
        "attribute1": "1",
        "attribute2": "2",
        "attribute3": "3",
        "attribute4": "4",
        "cardMask": "516874******5179",
        "actionMPI": "https://acs.privatbank.ua/pPaReqMC.jsp",
        "pareq": "eJxVUcluwjAQ/RWUY6XiJZtBE6MUuh0CKYVDj1FiQSqy4IQCf99xCNDKGmne7H4PJqdiN/hRusmrMrDYkFoDVaZVlpebwFqvXh6FNZGw2mqlZp8qPWglIVJNk2zUIM8CK06Was/cEXWY8LjjuB4Xtuc7jNr4RkJ49ohbEuIQ6yT0myQuGnIgV4gjdbpNylZCku6f3ufSdYTnCiA9hELp95n0GHN8HxsvEMqkUDJeLFfRYv48nC6ih9c4/ALSxSGtDmWrz1JQB8gVwEHv5LZt62ZMSF3ptqhKNUyrAojJALmfEh+M1+CkU57JaBYe0c5oLPpen+ZneoxWH2hRAMRUQJa0SnLKKXW5O2DO2PXHZncXh6QwJ+DXOcV/XQDUZkfYZ0zibwCQb41ynOVIYOqGQJ1qvBorkIqbD+R+8PTNMJm2SJIRxmM2E6yjs4uZATmSwTll3QQDgJgu0itFepXR+6f+L1ndtBw=",
        "authCode": "",
        "description": "test payment",
        "lang": "uk",
        "md": "194203287",
        "isNeed3DS": "Y",
        "token": "",
        "billCurrency": "UAH",
        "transactionId": "",
        "termUrl": "https://www.portmone.com.ua/r3/pg/confirmapigateway/3332633904a34c326a772f1256a70958bdaa4cc092a3fa86bdd5712dc033654d2582a3e4668f52230428/?shopBillId=303977a031fa486ee5e571aa119b89ba9eacd8&3ds=Y&py=303523031e7bb72dc8c426146af248",
        "successUrl": "https://portmone2.com/r3/ecommerce/test/master-test-from",
        "pdfUrl": ""
    },
    "id": "1"
}

Для проходження процедури 3D Secure мерчанту необхідно відкрити сторінку перевірки від банку (action), передавши на неї POST-запитом параметри перевірки (PaReq, MD) та URL для повернення після 3D Secure (TermUrl).

Параметри виклику сторінки банку:

Параметр	Опис
action	Отримане від Portmone значення actionMPI
PaReq	Отримане від Portmone значення pareq
MD	Отримане від Portmone значення md
TermUrl	URL партнера, на який мають повернутись параметри відповіді від банку після проходження 3D Secure. Якщо оплата здійснюється з додатку – app url

Під час проходження процедури 3-D Secure можливі два варіанти обробки відповіді від банку:

1. Обробка на стороні Portmone
   Якщо під час виклику actionMPI параметр TermUrl не передається, відповідь (PaRes, MD) надходить безпосередньо в систему Portmone. Portmone самостійно завершує обробку 3-D Secure.

2. Обробка на стороні мерчанта
   Якщо під час виклику actionMPI передано значення параметру TermUrl, банк повертає результат (PaRes, MD) на адресу мерчанта. У цьому випадку мерчант повинен прийняти дані та самостійно викликати метод confirmMpi для завершення оплати.

Приклад HTML-форми для виклику сторінки банку:

<form id="TheForm" action="https://acs.privatbank.ua/pPaReqMC.jsp" method="POST"
    name="TheForm">
    <input type="hidden" name="PaReq" value="eJxVUdtugkAQ/RXDY5O6u1wW1oxrqPbiA0KtfegjwY
        1iBHTBFvv1nUWs7SabzJnrmTMwaYv94FPpOq/KscWG1BqoMqvWebkZW++rp/vAmkhYbbVSszeVnbSSE
        Km6TjdqkK/HVpIu1ZF5nsMDfK7g3Oc2FUwI6nmccSE45ZaEJMQ8Cf0kiYOGNpArxJY626ZlIyHNjg/z
        hfTcgHsBkB5CofR8Jjljru9j4QVCmRZKJvFyFcWLx+E0ju6ek/ADSOeHrDqVjT7LgLpArgBOei+3TXO
        oR4QcKt0UVamGWVUAMREgNyrJyVg1dmrztYxm4Rf+Nl6F39EuaxdTyqJZRKPd6xiIyYB12ihpUyaoY/
        sDZo+YO3JxdueHtDAUcHXbwb0uAA5mRthHTOCvA1Bvjec4SxFQXOGKQLUHZI0ZKMWvDeRGePpilMwaF
        MlxHN/2fY+KTs7OZxrkKIaNZLsOBgAxVaS/FOmvjNa/6/8AWHOz+w=="/>
    <input type="hidden" name="MD" value="166765657"/>
	<input type="hidden" name="TermUrl" value="https://portmone2.com/r3/ecommerce/test/"/>
</form>

Після вводу коду на сторінці банку клієнт буде повернений назад на TermUrl, що вказаний у запиті, і на нього банком будуть передані параметри MD та PaRes, значення яких необхідно надіслати у Portmone для отримання результатів авторизації.

Параметри запиту у Portmone для підтвердження 3D Secure:

Параметр	Опис
MD	Значення MD, отримане від банку на ваш URL
PaRes	Значення PaRes, отримане від банку на ваш URL
shopBillId	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com, отриманий у попередніх запитах

Приклад запиту до Portmone для підтвердження 3D Secure:

{
    "method": "confirmMpi",
    "params": {
        "data": {
            "MD": "166765657",
            "PaRes": "eJzVWFeP47iy/iuLvY/GrrJsLTwNUNGSLcmKlvSmZOVgBSv8+it3T88O+s4eHNyXgyPAMFmsKhZZ4SN5NNMujlkjDscufjvKcd/7SfxbFn37/err8QMhCIw8bB9OkeSeRGEKoSiYIEiEpCgSJn9/O16BHvcfEq8WhmF7dL8nYOqwDT7jrs+a+g35E/4TPUKf3W2iLkz9eng7+uGDFpU3Aj+QxOEIfe8eq7gT2TcSQfD9fhP86B6hv",
            "shopBillId": "476986520"
        }
    },
    "id": "1"
}

Відповідь від Portmone.com буде містити результат оплати.

Кроки для інтеграції Apple Pay на сайт

Крок 1. Реєстрація та перевірка у системі Apple Pay

Ознайомтесь з відео-інструкцією, яка детально пояснює реєстрацію та перевірку у системі Apple Pay. Детальна відео-інструкція з налаштування Apple Pay.

1. Реєстрація Merchant ID
Ідентифікатор мерчанта унікально ідентифікує вас в Apple Pay як мерчанта, який може приймати платежі. Ідентифікатор мерчанта ніколи не втрачає чинності, і ви можете використовувати один і той самий ідентифікатор для кількох додатків.

• Увійдіть до облікового запису Apple Developer Account.
• Перейдіть у розділ Certificates, Identifiers & Profiles.
• Натисніть Identifiers у боковій панелі, а потім кнопку додавання (+) у верхньому лівому куті.
• Виберіть Merchant IDs, а потім натисніть Continue.
• Введіть Description та Identifier*, після чого натисніть Continue.
• Перегляньте налаштування та натисніть Register.
• Надішліть ваш Merchant ID до Portmone на адресу: [email protected].
• Отримайте зворотнім листом CSR-файл, сформований Portmone, який буде необхідним для створення Apple Pay Payment Processing Certificate.

Примітка:
Description – опис мерчанта.
Identifier – домен вашого сайту у зворотному порядку з додаванням "merchant" на початку (наприклад, для сайту shop.ua ідентифікатор буде merchant.ua.shop).

2. Створення Apple Pay Payment Processing Certificate

Apple Pay Payment Processing Certificate пов’язаний з вашим ідентифікатором мерчанта та використовується для шифрування платіжної інформації. Термін дії сертифіката обробки платежів закінчується кожні 25 місяців. Якщо сертифікат буде відкликано, ви можете створити його знову.

• Увійдіть до облікового запису Apple Developer Account.
• У розділі Certificates, Identifiers & Profiles натисніть Identifiers у боковій панелі.
• У розділі Identifiers використайте фільтр у верхньому правому куті та виберіть Merchant IDs.
• Справа оберіть ваш ідентифікатор мерчанта*.
• У розділі Apple Pay Payment Processing Certificate натисніть Create Certificate.
• Завантажте CSR-файл, отриманий від Portmone, натиснувши Choose File, а потім Continue.
• Натисніть Download.
• Надішліть завантажений сертифікат (apple_pay.cer) до Portmone на адресу: [email protected].

Примітка:
Якщо у верхній частині сторінки з’являється банер із повідомленням про необхідність прийняття угоди, натисніть кнопку Review Agreement та дотримуйтесь інструкцій перед продовженням.

3. Реєстрація та верифікація домену

• Увійдіть до облікового запису Apple Developer Account.
• У розділі Certificates, Identifiers & Profiles натисніть Identifiers у боковій панелі, а потім виберіть Merchant IDs у випадаючому меню у верхньому правому куті.
• Оберіть ваш Merchant ID.
• У розділі Merchant Domains натисніть Add Domain.
• Введіть назву свого домену та натисніть Save.
• Завантажте файл apple-developer-merchantid-domain-association.txt.
• Розмістіть файл у кореневій директорії вашого домену за наступним шляхом:

  https://<your-domain>/.well-known/apple-developer-merchantid-domain-association.txt
• Переконайтесь, що файл доступний через браузер за вказаним URL.
• Натисніть Verify.
• Якщо все налаштовано правильно, статус домену зміниться на Verified.

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

4. Створення Apple Pay Merchant Identity Certificate
Для роботи з Apple Pay необхідний Merchant Identity Certificate. Цей сертифікат забезпечує безпечне здійснення операцій і ідентифікує мерчанта. Також він потрібний для створення Apple Pay Payment Session під час верифікації магазину.

Перед створенням Apple Pay Merchant Identity Certificate вам необхідно отримати Certificate Signing Request (CSR). Це можна зробити одним із декількох способів:

• Отримання CSR і приватного ключа від Portmone. (Рекомендований спосіб)
  Надішліть лист на адресу: [email protected] с запитом на отримання CSR для створення Apple Pay Merchant Identity Certificate, у відповідь отримайте підготовлений CSR-файл, що відповідає вимогам Apple, разом із приватним ключем. Цей спосіб є рекомендованим, оскільки він спрощує процес і гарантує сумісність.

• Самостійна генерація CSR та приватного ключа

  Є декілька шляхів самостійного створення CSR та приватного ключа: використання Keychain Access на macOS (посилання на інструкцію Apple.) або через OpenSSL. Нижче наведено інструкцію для створення за допомогою Keychain Access:

  • Відкрийте Keychain Access, що знаходиться в /Applications/Utilities.
  • У меню оберіть: Keychain Access → Certificate Assistant → Request a Certificate from a Certificate Authority.
  • У вікні, що з'явиться, заповніть поля:
    • User Email Address: вкажіть вашу електронну пошту.
    • Common Name: введіть назву ключа.
    • CA Email Address: залиште пустим.
  • Оберіть опцію I will provide the key pair information, щоб вручну створити пару ключів, необхідних для CSR.
  • Оберіть опцію Saved to disk і натисніть Continue. Збережіть файл із розширенням .certSigningRequest.
  • Використовуйте алгоритм і розмір ключа: RSA(2048). Apple Pay on the Web troubleshooting guide / Create a merchant identity certificate

Після отримання CSR виконайте наступні дії для створення сертифікату:

• Увійдіть до облікового запису Apple Developer Account.
• У розділі Certificates, Identifiers & Profiles натисніть Identifiers у боковій панелі, а потім виберіть Merchant IDs у випадаючому меню у верхньому правому куті.
• У списку знайдіть створений Merchant ID та натисніть на нього.
• У розділі Apple Pay Merchant Identity Certificate натисніть Create Certificate.
• Завантажте CSR-файл, натиснувши Choose File, оберіть файл і натисніть Continue.
• Завершіть процес, натиснувши Download, щоб зберегти готовий сертифікат.
• Надішліть згенерований сертифікат (merchant_id.cer) та приватний ключ (якщо ви генерували його самостійно) до Portmone на адресу [email protected].

Крок 2. Технічна інтеграція з ApplePay

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

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. Провалідуйте мерчанта

session.onvalidatemerchant = function(event) {
    var promise = validateMerchant(event.validationURL);
    promise.then(function(merchantSession) {
        session.completeMerchantValidation(merchantSession);
    });
}

function validateMerchant(validationURL) {
    return new Promise(function(resolve, reject) {
        var applePayPayload = {
            'merchantId': {YOUR_MERCHANT_ID},
            'validationURL': {YOUR_VALIDATION_URL},
            'body': {
                'merchantIdentifier': {YOUR_MERCHANT_ID},
                'domainName': {YOUR_DOMAIN_NAME},
                'displayName': {PRODUCT_NAME}
            }
        };

        var xhr = new XMLHttpRequest();
        xhr.onload = function() {
            var data = JSON.parse(this.responseText);
            resolve(data);
        };
        xhr.onerror = reject;
        xhr.open('POST', merchantValidationEndpoint, true);
        xhr.setRequestHeader('Content-Type', 'application/json;charset=utf-8');
        xhr.send(JSON.stringify(applePayPayload));
    });
}

4. Запустіть сесію та опрацюйте платіж

session.onpaymentauthorized = function(event) {

    session.completePayment(ApplePaySession.STATUS_SUCCESS);
}
session.begin();

Приклад набору даних, що повертаються від Apple Pay:

{
  "paymentData":
  {
    "version":"EC_v1",
    "data":"FDXK/fkIXGh07D5QU5eUK3ZK8BxKk6syu+Hf0DH6DBZ8/loNHFWHULxsmfIAyaKzvkUjm2dHaR36pS4x8UXuQ3JhzeB7AfDmZsP8JcL16OOyZKZP3JjOwdkUVvzUyPWtjtlrtXDaBmJ5jPcT8bgnLZV/7RcC9HpRkdmUqVyJ042wAvPNxF7SVt57PcMyMeccVL6yWUk6N2oV7ESFoGVbAeJdpn5zZT8lebigrnhZRhvwoJ5ZJ/dGK9UZDP/swhH8nMLjK620Wu9rvidhsSheJCwM2sCH27fKpeEO2x+vWaLlL9ukwDms9ciOGvSyb+tDvRD9MheecGri1XCC6DxQT5JkHDH7mi1vev0QFjjVY6bmh26iNC0lIB4FKVznNv03yjkKNJhEMbp/clv4",
    "signature":"MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID4zCCA4igAwIBAgIITDBBSVGdVDYwCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE5MDUxODAxMzI1N1oXDTI0MDUxNjAxMzI1N1owXzElMCMGA1UEAwwcZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtUFJPRDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwhV37evWx7Ihj2jdcJChIY3HsL1vLCg9hGCV2Ur0pUEbg0IO2BHzQH6DMx8cVMP36zIg1rrV1O/0komJPnwPE6OCAhEwggINMAwGA1UdEwEB/wQCMAAwHwYDVR0jBBgwFoAUI/JJxE+T5O8n5sT2KGw/orv9LkswRQYIKwYBBQUHAQEEOTA3MDUGCCsGAQUFBzABhilodHRwOi8vb2NzcC5hcHBsZS5jb20vb2NzcDA0LWFwcGxlYWljYTMwMjCCAR0GA1UdIASCARQwggEQMIIBDAYJKoZIhvdjZAUBMIH+MIHDBggrBgEFBQcCAjCBtgyBs1JlbGlhbmNlIG9uIHRoaXMgY2VydGlmaWNhdGUgYnkgYW55IHBhcnR5IGFzc3VtZXMgYWNjZXB0YW5jZSBvZiB0aGUgdGhlbiBhcHBsaWNhYmxlIHN0YW5kYXJkIHRlcm1zIGFuZCBjb25kaXRpb25zIG9mIHVzZSwgY2VydGlmaWNhdGUgcG9saWN5IGFuZCBjZXJ0aWZpY2F0aW9uIHByYWN0aWNlIHN0YXRlbWVudHMuMDYGCCsGAQUFBwIBFipodHRwOi8vd3d3LmFwcGxlLmNvbS9jZXJ0aWZpY2F0ZWF1dGhvcml0eS8wNAYDVR0fBC0wKzApoCegJYYjaHR0cDovL2NybC5hcHBsZS5jb20vYXBwbGVhaWNhMy5jcmwwHQYDVR0OBBYEFJRX22/VdIGGiYl2L35XhQfnm1gkMA4GA1UdDwEB/wQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0kAMEYCIQC+CVcf5x4ec1tV5a+stMcv60RfMBhSIsclEAK2Hr1vVQIhANGLNQpd1t1usXRgNbEess6Hz6Pmr2y9g4CJDcgs3apjMIIC7jCCAnWgAwIBAgIISW0vvzqY2pcwCgYIKoZIzj0EAwIwZzEbMBkGA1UEAwwSQXBwbGUgUm9vdCBDQSAtIEcz***MjM0NjMwWjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATwFxGEGddkhdUaXiWBB3bogKLv3nuuTeCN/EuT4TNW1WZbNa4i0Jd2DSJOe7oI/XYXzojLdrtmcL7I6CmE/1RFo4H3MIH0MEYGCCsGAQUFBwEBBDowODA2BggrBgEFBQcwAYYqaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZXJvb3RjYWczMB0GA1UdDgQWBBQj8knET5Pk7yfmxPYobD+iu/0uSzAPBgNVHRMBAf8EBTADAQH/MB8GA1UdIwQYMBaAFLuw3qFYM4iapIqZ3r6966/ayySrMDcGA1UdHwQwMC4wLKAqoCiGJmh0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlcm9vdGNhZzMuY3JsMA4GA1UdDwEB/wQEAwIBBjAQBgoqhkiG92NkBgIOBAIFADAKBggqhkjOPQQDAgNnADBkAjA6z3KDURaZsYb7NcNWymK/9Bft2Q91TaKOvvGcgV5Ct4n4mPebWZ+Y1UENj53pwv4CMDIt1UQhsKMFd2xd8zg7kGf9F3wsIW2WT8ZyaYISb1T4en0bmcubCYkhYQaZDwmSHQAAMYIBjTCCAYkCAQEwgYYwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTAghMMEFJUZ1UNjANBglghkgBZQMEAgEFAKCBlTAYBgkqhkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0xOTEwMDcwOTAzMzlaMCoGCSqGSIb3DQEJNDEdMBswDQYJYIZIAWUDBAIBBQChCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEINit/iw3WwwTnehkerYBQk/4vdByMbbliBcTPyT7FRiPMAoGCCqGSM49BAMCBEgwRgIhAKvTEMlNfyLdg9slvO6Ignu+y//nAmevtrQa8Yk2qw0/AiEAhivZamhbazis3+5Nd5dZWxgM1gv/PpsAykJvjg3qQ0QAAAAAAAA=",
    "header":
    {
      "ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXaMJN7PRXhkoMa1n1wOnut4KIkIX0WuyXenzRukdDUzo/GZ+TRqTSPjZDOPoZkisqifaroXUJZP9xCUlJQ3iqQ==",
      "publicKeyHash":"48145ri0BI4zYNGguvfW+7qJc3kQlcGdil64a4cg+Ag=",
      "transactionId":"cd80b9fc31c9a850c14c697bd4c258aa51e63bf72bba46394eebbc3fae1b58e4"
    }
  },
  "paymentMethod":
  {
    "displayName":"MasterCard 5179",
    "network":"MasterCard",
    "type":"debit"
  },
  "transactionIdentifier":"CD80B9FC31C9A850C14C697BD4C258AA51E63BF72BBA46394EEBBC3FAE1B58E4"
}

5. Надішліть значення paymentData до Portmone API (див. Крок 3).

Важливо:
Криптограма, отримана з Apple Pay, повинна використовуватися лише один раз у межах однієї транзакції. Повторне використання тієї самої криптограми може призвести до відхилення платежу банком-еквайєром. Для кожної нової транзакції необхідно отримувати нову криптограму з Apple Pay.

Крок 3. Технічна інтеграція з Portmone.com

До API Portmone.com необхідно надіслати дані paymentData.

Метод: APay

URL: https://www.portmone.com.ua/r3/api/gateway.

Параметри запиту:

Параметр	Опис	Обов'язковий
login	Логін Інтернет-магазину для доступу до управління акаунтом	Так
password	Пароль Інтернет-магазину	Так
aPayMerchantName	Merchant ID у Apple Developer Account	Так
paymentData	Значення параметру paymentData, що отриманий мерчантом у відповіді від системи Apple Pay	Так
payeeId	Унікальний ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
billAmount	Сума оплати. Розділювач крапка. Наприклад: "10.21"	Так
description	Коментар до замовлення / опис призначення платежу	Ні
shopOrderNumber	Номер замовлення (рахунку) у системі Інтернет-магазину	Ні
emailRecipient	Адреса електронної пошти Клієнта	Ні
preauthFlag	Ознака преавторизації платежу (значення "Y" вказує на те, що ця оплата здійснюється з використанням процедури преавторизації, значення "N" – звичайна оплата без преавторизації)	Ні
billCurrency	Валюта проведення платежу. Можливі значення: UAH, USD, EUR, GBP, KZT (значення без задання – UAH)	Ні
shop_site_id	Канал оплати у системі Portmone	Ні
threeDs	Секція параметрів, що використовується для зазначення URL мерчанта (termUrl або appUrl), на який буде перенаправлено клієнта після успішного проходження перевірки 3D Secure	Ні
termUrl	Необхідно встановити значення "Y" або не використовувати цей параметр	Ні
appUrl	Значення appUrl мерчанта (у разі інтеграції GPay у мобільний додаток)	Ні

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

{
    "method":"APay",
    "params": {
        "data":{
            "login":"wdishop",
            "password":"11111111",
            "aPayMerchantName":"",
            "paymentData":{
                "version":"EC_v1",
                "data":"7p8TndxxyLvLxzkD****xnjJj5Gf5vtmHGHEN",
                "signature":"MIAGCSqGSI****b05ZOreRp5zAt+Zx+ukgAAAAAAAA==",
                "header":{
                    "ephemeralPublicKey":"MFkwEwY****hc7lmaYq8I8Nr111pStGhQ==",
                    "publicKeyHash":"48145ri0BI***il64a4cg+Ag=",
                    "transactionId":"16d32ec****da49c41c36a5a6c7cc"
                }
            },
            "payeeId":"11344",
            "billAmount":"1.01",
            "description":"test",
            "shopOrderNumber":"AP-01",
            "attribute1":"",
            "attribute2":"",
            "attribute3":"",
            "attribute4":"",
            "emailRecipient":"",
            "billCurrency":"UAH",
            "preauthFlag":"N",
            "shop_site_id" : "",
            "threeDs":{
                "termUrl":"Y",
                "appUrl":"https://portmone2.com/r3/ecommerce/test/master-test-from"
            }
        }
    },
    "id": "1"
}

Параметри відповіді:

Параметр	Опис
status	Результат оплати. Можливі значення: - PAYED – оплата успішна, - REJECTED – відмова, - CREATED – замовлення створено, але не оплачено
errorCode	Код помилки. Якщо значення параметру "0" – оплата успішна. Якщо значення параметру більше за 0 або порожнє – сталася помилка
error	Текст помилки (див. Таблицю кодів відмов)
shopBillId	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com
billAmount	Передана у запиті сума транзакції
billNumber	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів
attribute1	Службове поле, заповнюється на розсуд компанії
attribute2	Службове поле, заповнюється на розсуд компанії
attribute3	Службове поле, заповнюється на розсуд компанії
attribute4	Службове поле, заповнюється на розсуд компанії
cardMask	Маска Картки/ Токену платника
actionMPI	URL банку, на який треба перенаправити клієнта для проходження 3D Secure перевірки
pareq	Параметр, який треба передати на actionMPI при проходженні 3D Secure перевірки
authCode	Код авторизації
description	Коментар до замовлення / опис призначення оплати. До 250 символів
lang	Мова відповіді. Залежить від локалізації endpoint, на який надсилали запит*
md	Параметр, який треба передати на actionMPI при проходженні 3D Secure перевірки
isNeed3DS	Ознака необхідності проходження перевірки 3D Secure ("Y" – необхідно пройти процедуру перевірки 3D Secure, "N" – додаткові дії не потрібні)
token	Значення Токену для подальших оплат. Для методів оплати GPay та APay не формується
billCurrency	Валюта платежу
transactionId	Ідентифікатор транзакції в системі банка-еквайера
termUrl	URL мерчанта, на який мають повернутись параметри відповіді від банку після проходження 3D Secure. Значення генерується системою Portmone
successUrl	Значення appUrl мерчанта, на який мають повернутись параметри відповіді від банку після проходження 3D Secure (якщо це значення було передане в параметрі appUrl у запиті на оплату)
pdfUrl	Посилання для збереження квитанції про оплату. Надається клієнтові лише якщо status=PAYED
shop_site_id	Канал оплати у системі Portmone

Примітка: * – для отримання локалізованих текстів відмов необхідно надсилати запит на відповідний endpoint:

https://www.portmone.com.ua/r3/api/gateway – стандартно українською мовою https://www.portmone.com.ua/r3/uk/api/gateway – для відповідей українською мовою https://www.portmone.com.ua/r3/en/api/gateway – для відповідей англійською мовою

Приклад успішної відповіді:

{
    "result": {
        "status": "PAYED",
        "errorCode": "0",
        "error": "",
        "shopBillId": "550298815",
        "billAmount": "1.01",
        "billNumber": "SHP-00000002",
        "attribute1": "",
        "attribute2": "",
        "attribute3": "",
        "attribute4": "",
        "cardMask": "535560******3735",
        "actionMPI": "",
        "pareq": "",
        "authCode": "67037Z",
        "description": "test payment",
        "lang": "uk",
        "md": "",
        "isNeed3DS": "N",
        "token": "",
        "billCurrency": "UAH",
        "transactionId": "927500948048",
        "pdfUrl": "https://www.portmone.com.ua/r3/services/receipts/get-receipts/shop-bill-id/35357a20f10b49519794e81b48b20d0402cd2b7654553048021cb230400befdf94bacfbb12bd77983adae9422fbcc51cf0987a171403f08b33b2d119249845bad4e457",
        "shop_site_id" : ""
    },
    "id": "1"
}

Приклад відмови:

{
    "result": {
        "status": "REJECTED",
        "errorCode": "5",
        "error": "Transactions has exceeded the limit by your bank",
        "shopBillId": "5530964511",
        "billAmount": "1",
        "billNumber": "P55309624511",
        "attribute1": "A",
        "attribute2": "",
        "attribute3": "",
        "attribute4": "",
        "cardMask": "535560******3735",
        "actionMPI": "",
        "pareq": "",
        "authCode": "",
        "description": "test payment",
        "lang": "en",
        "md": "",
        "isNeed3DS": "N",
        "token": "",
        "billCurrency": "UAH",
        "transactionId": "928199458716",
        "pdfUrl": "",
        "shop_site_id" : ""
    },
    "id": "1"
}

Приклад відповіді, якщо необхідна 3D Secure перевірка:

{
    "result": {
        "status": "CREATED",
        "errorCode": "0",
        "error": "",
        "shopBillId": "663526924",
        "billAmount": "1.2",
        "billNumber": "123456.14052020.05",
        "attribute1": "1",
        "attribute2": "2",
        "attribute3": "3",
        "attribute4": "4",
        "cardMask": "516874******5179",
        "actionMPI": "https://acs.privatbank.ua/pPaReqMC.jsp",
        "pareq": "eJxVUcluwjAQ/RWUY6XiJZtBE6MUuh0CKYVDj1FiQSqy4IQCf99xCNDKGmne7H4PJqdiN/hRusmrMrDYkFoDVaZVlpebwFqvXh6FNZGw2mqlZp8qPWglIVJNk2zUIM8CK06Was/cEXWY8LjjuB4Xtuc7jNr4RkJ49ohbEuIQ6yT0myQuGnIgV4gjdbpNylZCku6f3ufSdYTnCiA9hELp95n0GHN8HxsvEMqkUDJeLFfRYv48nC6ih9c4/ALSxSGtDmWrz1JQB8gVwEHv5LZt62ZMSF3ptqhKNUyrAojJALmfEh+M1+CkU57JaBYe0c5oLPpen+ZneoxWH2hRAMRUQJa0SnLKKXW5O2DO2PXHZncXh6QwJ+DXOcV/XQDUZkfYZ0zibwCQb41ynOVIYOqGQJ1qvBorkIqbD+R+8PTNMJm2SJIRxmM2E6yjs4uZATmSwTll3QQDgJgu0itFepXR+6f+L1ndtBw=",
        "authCode": "",
        "description": "test payment",
        "lang": "en",
        "md": "194203287",
        "isNeed3DS": "Y",
        "token": "",
        "billCurrency": "UAH",
        "transactionId": "",
        "termUrl": "https://www.portmone.com.ua/r3/pg/confirmapigateway/3332633904a34c326a772f1256a70958bdaa4cc092a3fa86bdd5712dc033654d2582a3e4668f52230428/?shopBillId=303977a031fa486ee5e571aa119b89ba9eacd8&3ds=Y&py=303523031e7bb72dc8c426146af248",
        "successUrl": "https://portmone2.com/r3/ecommerce/test/master-test-from",
        "pdfUrl": ""
    },
    "id": "1"
}

Для проходження процедури 3D Secure мерчанту необхідно відкрити сторінку перевірки від банку (action), передавши на неї POST-запитом параметри перевірки (PaReq, MD) та URL для повернення після 3D Secure (TermUrl).

Параметри виклику сторінки банку:

Параметр	Опис
action	Отримане від Portmone значення actionMPI
PaReq	Отримане від Portmone значення pareq
MD	Отримане від Portmone значення md
TermUrl	URL партнера, на який мають повернутись параметри відповіді від банку після проходження 3D Secure. Якщо оплата здійснюється з додатку – app url

Під час проходження процедури 3-D Secure можливі два варіанти обробки відповіді від банку:

1. Обробка на стороні Portmone
   Якщо під час виклику actionMPI параметр TermUrl не передається, відповідь (PaRes, MD) надходить безпосередньо в систему Portmone. Portmone самостійно завершує обробку 3-D Secure.

2. Обробка на стороні мерчанта
   Якщо під час виклику actionMPI передано значення параметру TermUrl, банк повертає результат (PaRes, MD) на адресу мерчанта. У цьому випадку мерчант повинен прийняти дані та самостійно викликати метод confirmMpi для завершення оплати.

Приклад HTML-форми для виклику сторінки банку:

<form id="TheForm" action="https://acs.privatbank.ua/pPaReqMC.jsp" method="POST"
    name="TheForm">
    <input type="hidden" name="PaReq" value="eJxVUdtugkAQ/RXDY5O6u1wW1oxrqPbiA0KtfegjwY
        1iBHTBFvv1nUWs7SabzJnrmTMwaYv94FPpOq/KscWG1BqoMqvWebkZW++rp/vAmkhYbbVSszeVnbSSE
        Km6TjdqkK/HVpIu1ZF5nsMDfK7g3Oc2FUwI6nmccSE45ZaEJMQ8Cf0kiYOGNpArxJY626ZlIyHNjg/z
        hfTcgHsBkB5CofR8Jjljru9j4QVCmRZKJvFyFcWLx+E0ju6ek/ADSOeHrDqVjT7LgLpArgBOei+3TXO
        oR4QcKt0UVamGWVUAMREgNyrJyVg1dmrztYxm4Rf+Nl6F39EuaxdTyqJZRKPd6xiIyYB12ihpUyaoY/
        sDZo+YO3JxdueHtDAUcHXbwb0uAA5mRthHTOCvA1Bvjec4SxFQXOGKQLUHZI0ZKMWvDeRGePpilMwaF
        MlxHN/2fY+KTs7OZxrkKIaNZLsOBgAxVaS/FOmvjNa/6/8AWHOz+w=="/>
    <input type="hidden" name="MD" value="166765657"/>
	<input type="hidden" name="TermUrl" value="https://portmone2.com/r3/ecommerce/test/"/>
</form>

Після вводу коду на сторінці банку клієнт буде повернений назад на TermUrl, що вказаний у запиті, і на нього банком будуть передані параметри MD та PaRes, значення яких необхідно надіслати у Portmone для отримання результатів авторизації.

Параметри запиту у Portmone для підтвердження 3D Secure:

Параметр	Опис
MD	Значення MD, отримане від банку на ваш URL
PaRes	Значення PaRes, отримане від банку на ваш URL
shopBillId	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com, отриманий у попередніх запитах

Приклад запиту у Portmone для підтвердження 3D Secure:

{
    "method": "confirmMpi",
    "params": {
        "data": {
            "MD": "166765657",
            "PaRes": "eJzVWFeP47iy/iuLvY/GrrJsLTwNUNGSLcmKlvSmZOVgBSv8+it3T88O+s4eHNyXgyPAMFmsKhZZ4SN5NNMujlkjDscufjvKcd/7SfxbFn37/err8QMhCIw8bB9OkeSeRGEKoSiYIEiEpCgSJn9/O16BHvcfEq8WhmF7dL8nYOqwDT7jrs+a+g35E/4TPUKf3W2iLkz9eng7+uGDFpU3Aj+QxOEIfe8eq7gT2TcSQfD9fhP86B6hv",
            "shopBillId": "476986520"
        }
    },
    "id": "1"
}

Відповідь від Portmone.com буде містити результат оплати.

Додаток 1. Схема обробки параметрів відповіді

Додаток 2. Таблиця кодів відмов

Код	Опис	Повідомлення про помилку (en)	Повідомлення про помилку (uk)	Рекомендовані дії
0				Оплата успішна
1	Declined by bank	Transaction declined by bank	Операція відхилена банком	Операция отклонена банком
2	Transaction is prohibited by acquiring bank	Transaction is prohibited by acquiring bank	Операція відхилена банком-еквайером	Операция отклонена банком-эквайером
3	Transaction is prohibited by issuing bank	Transaction is prohibited by issuing bank	Операція відхилена вашим банком	Операция отклонена вашим банком
4	Technical/ communication problem	Technical problems. Please try again later	Технічні проблеми. Спробуйте пізніше	Технические проблемы. Попробуйте позже
5	Transaction has exceeded the limit by your bank	Transaction has exceeded the limit by your bank	Операція відхилена банком. Перевищення лімітів	Операция отклонена банком. Превышение лимитов
6	Not sufficient funds	Transaction declined by bank. Insufficient funds	Операція відхилена банком. Недостатньо коштів	Операция отклонена банком. Недостаточно средств
7	Invalid CVV or card expiry date	Transaction declined by bank. Invalid CVV or card expiry date	Операція відхилена банком. Некоректний CVV або термін дії картки	Операция отклонена банком. Некорректный CVV или срок действия карты
8	Invalid OTP code	Transaction declined. Invalid OTP code	Операція відхилена. Введено невірний код	Операция отклонена. Введен некорректный код
9	Invalid 3DS data	Transaction declined by bank. Invalid 3DS code	Операція відхилена. Введено невірний код	Операция отклонена. Введен неверный код
10	Duplicate transactions	Transaction declined. Duplicate transactions	Операція відхилена. Повторна транзакція	Операция отклонена. Повторная транзакция
11	Format error	Transaction declined. Format error	Операція відхилена. Некоректний формат запиту	Операция отклонена. Некорректный формат запроса
12	Portmone verification	Additional card verification required	Необхідно пройти додаткову перевірку картки	Необходимо пройти дополнительную верификацию карты
13	System error. Please try again.	System error. Please contact Portmone.com support	Системна помилка. Зверніться до служби підтримки Portmone.com	Системная ошибка. Обратитесь в службу поддержки Portmone.com
14	Wrong signature	Transaction declined. Authentication failed or invalid request	Операція відхилена. Не пройдена аутентифікація або некоректний запит	Операция отклонена. Не пройдена аутентификация или некорректный запрос
15	Query time exceeded	Transaction declined. Timeout. Contact Portmone.com support	Операція відхилена. Перевищено час очікування. Зверніться до служби підтримки Portmone.com	Операция отклонена. Превышено время ожидания. Обратитесь в службу поддержки Portmone.com
16	Invalid request data	Transaction declined. Invalid request	Операція відхилена. Некоректний запит	Операция отклонена. Некорректный запрос
17	Transaction has exceeded system limits	Transaction declined. Limit is exceeded. Contact Portmone.com support	Операція відхилена. Перевищено ліміт. Зверніться до служби підтримки Portmone.com	Операция отклонена. Превышен лимит. Обратитесь в службу поддержки Portmone.com
18	Fraud	Transaction declined by Portmone.com monitoring system. Please contact support	Операція відхилена моніторинговою системою Portmone.com. Зверніться до служби підтримки	Операция отклонена мониторинговой системой Portmone.com. Обратитесь в службу поддержки
19	Order not found	Order not found	Замовлення не знайдено	Заказ не найден