Ipay ApplePay API v1.0.1

• Загальна інформація
• Доступи й налаштування
• PaymentToken
• Загальна структура запиту
• Перелік запитів
  1. Попередній розрахунок комісії
  2. Створити платіж
  3. Завершити платіж
  4. Відмінити платіж
  5. Запросити квитанцію
  6. Статус запиту
• Інтеграція з Apple Pay Web
• Системні помилки
• Групи помилок

Загальна інформація

Даний сервіс дозволяє виконати списання коштів з картки доданої до ApplePay гаманця.

Доступи й налаштування

Для взаємодії слід отримати наступні значенння:

- login - ідентифікатор мерчанта

- sign_key - ключ для підпису

URL адреса для запитів - https://api-applepay.ipay.ua

Формат передачі - JSON методом POST

Кодування у UTF-8

Алгоритм підпису (поле sign у запиті):
Потрібно об'єднати наступні строки в одну: "час запиту" та ключ для підпису (sign_key) і зашифрувати алгоритмом SHA3-512.

Приклад на PHP:

$sign = hash('sha3-512', '2017-01-01 00:00:00' . $sign_key );

PaymentToken (передавання в запросі поля apple_data)

Обов'язкові процедури для формування поля:

1. Потрібно надати запит до нас на формування CertificateSigningRequest.certSigningRequest в форматі (ecc 256)

2. Згенерувати у appleDev кабінеті PaymentProcessing.cert під мерчанта який вказаний в додатку.

3. Передати нам діючий сертифікат.

Після проведення цих процедур Ви будете отримувати відповідь від Apple, яку потрібно буде попередньо закодувати
в Base64, та передавати нам у полі apple_data в запросі PaymentCreate

Приклад відповіді у форматі JSON який получено від Apple

        
{

    "paymentData":{
        "version":"EC_v1",
        "data":"gvMXusr6e.....qB5qSlCzNv9Ugy",
        "signature":"MIAGCSq ..... 0dMx/d80r97Pf1MPxkhAAAAAAA",
        "header":{
            "ephemeralPublicKey":"MFkwEwYH.....SXc10Qt5NVkFjSRq8tk0dDw==",
            "publicKeyHash":"aVc7v.....qepG4=",
            "transactionId":"3e80774bbc385ec08a57e02acbf00fc74a3d032be84c42481e2cfc4f4446082b"
        }
    },
    "paymentMethod":{
        "displayName":"Visa 4655",
        "network":"Visa",
        "type":"debit"
    },
    "transactionIdentifier":"3E80774BBC385EC08A57E02ACBF00FC74A3D032BE84C42481E2CFC4F4446082B"

}
        
        

Цю відповідь потрібно закодувати у Base64 та передати у полі apple_data в запросі PaymentCreate

Загальна структура запиту

Структура запитів відрізняється полями action (назва запиту) та body (тіло запиту).

Поле	Тип	Опис
request	object	Об'єкт запиту
request.auth	object	Об'єкт аутентифікації
request.auth.login	string	ID мерчанта
request.auth.time	string	Час запиту у часовому поясі Europe/Kiev Формат: YYYY-MM-DD HH:MM:SS Приклад: 2017-01-01 00:00:00
request.auth.sign	string	Підпис запиту
request.action	string	Назва запиту
request.body	object	Об'єкт тіла запиту

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

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00dc94b74a7cfdced473 ..."
        },
        "action": "PaymentCreate",
        "body": {
            "msisdn": "380931234567",
            "invoice": 100,
            "apple_data": "eyJwYXltZW50RGF0YSI6eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoiZ3ZNWHVzcjZlWDE3WWFkNTduRmt5UUJoRkxOUUc4WmtSS3BUZlZuak12V0V0K2RmYVpnSUVnWmpJRzV3ODgzUWozbkNNQTBpaWVnSUpFbkNuNkJJakJPZ0dhRlFXSXN2YkNBVXFaUDMrOGF3QWFZRy9oYjFHNm1SOHY1cFlGdFNYOVU3UUVyajVMREFERlJ1Q05ZQlUvOFplc04rZG0vdkUwVDA2VkpydjhJRVR6Zm5BT3JIVDdqZ2hPTEVYVkNHNWN0SlVXL25aZUQrVFN4Y1BoMC93RTdMY3BIRDJQK09waks2dlZVL1A5UlB3cERoSXlQODBvNHNMbDI4L2xZS0gxb1hBZTYzTC8wL1Rrc1YzN0g5cFQ3b2NzOWhPNjFXcGViUDkxemk5VTNZOEdBZGxkZ2U0VG1hbDZTWTJacjNkWXNCbk5WTGt1RkNQNHlqOFd2Yjc4dFN1Z2tLaDFvZ3lGN24wRjNJQ2hZaDJTd0FvbmVRM1dGZWhRbThHaGRQNDZIUU5XbURMdm9KRG8vU0xrOE1EYlFhTytxQjVxU2xDek52OVVneSIsInNpZ25hdHVyZSI6Ik1JQUdDU3FHU0liM0RRRUhBcUNBTUlBQ0FRRXhEekFOQmdsZ2hrZ0JaUU1FQWdFRkFEQ0FCZ2txaGtpRzl3MEJCd0VBQUtDQU1JSUQ0akNDQTRpZ0F3SUJBZ0lJSkVQeXFBYWQ5WGN3Q2dZSUtvWkl6ajBFQXdJd2VqRXVNQ3dHQTFVRUF3d2xRWEJ3YkdVZ1FYQndiR2xqWVhScGIyNGdTVzUwWldkeVlYUnBiMjRnUTBFZ0xTQkhNekVtTUNRR0ExVUVDd3dkUVhCd2JHVWdRMlZ5ZEdsbWFXTmhkR2x2YmlCQmRYUm9iM0pwZEhreEV6QVJCZ05WQkFvTUNrRndjR3hsSUVsdVl5NHhDekFKQmdOVkJBWVRBbFZUTUI0WERURTBNRGt5TlRJeU1EWXhNVm9YRFRFNU1Ea3lOREl5TURZeE1Wb3dYekVsTUNNR0ExVUVBd3djWldOakxYTnRjQzFpY205clpYSXRjMmxuYmw5VlF6UXRVRkpQUkRFVU1CSUdBMVVFQ3d3TGFVOVRJRk41YzNSbGJYTXhFekFSQmdOVkJBb01Da0Z3Y0d4bElFbHVZeTR4Q3pBSkJnTlZCQVlUQWxWVE1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRXdoVjM3ZXZXeDdJaGoyamRjSkNoSVkzSHNMMXZMQ2c5aEdDVjJVcjBwVUViZzBJTzJCSHpRSDZETXg4Y1ZNUDM2eklnMXJyVjFPLzBrb21KUG53UEU2T0NBaEV3Z2dJTk1FVUdDQ3NHQVFVRkJ3RUJCRGt3TnpBMUJnZ3JCZ0VGQlFjd0FZWXBhSFIwY0RvdkwyOWpjM0F1WVhCd2JHVXVZMjl0TDI5amMzQXdOQzFoY0hCc1pXRnBZMkV6TURFd0hRWURWUjBPQkJZRUZKUlgyMi9WZElHR2lZbDJMMzVYaFFmbm0xZ2tNQXdHQTFVZEV3RUIvd1FDTUFBd0h3WURWUjBqQkJnd0ZvQVVJL0pKeEUrVDVPOG41c1QyS0d3L29ydjlMa3N3Z2dFZEJnTlZIU0FFZ2dFVU1JSUJFRENDQVF3R0NTcUdTSWIzWTJRRkFUQ0IvakNCd3dZSUt3WUJCUVVIQWdJd2diWU1nYk5TWld4cFlXNWpaU0J2YmlCMGFHbHpJR05sY25ScFptbGpZWFJsSUdKNUlHRnVlU0J3WVhKMGVTQmhjM04xYldWeklHRmpZMlZ3ZEdGdVkyVWdiMllnZEdobElIUm9aVzRnWVhCd2JHbGpZV0pzWlNCemRHRnVaR0Z5WkNCMFpYSnRjeUJoYm1RZ1kyOXVaR2wwYVc5dWN5QnZaaUIxYzJVc0lHTmxjblJwWm1sallYUmxJSEJ2YkdsamVTQmhibVFnWTJWeWRHbG1hV05oZEdsdmJpQndjbUZqZEdsalpTQnpkR0YwWlcxbGJuUnpMakEyQmdnckJnRUZCUWNDQVJZcWFIUjBjRG92TDNkM2R5NWhjSEJzWlM1amIyMHZZMlZ5ZEdsbWFXTmhkR1ZoZFhSb2IzSnBkSGt2TURRR0ExVWRId1F0TUNzd0thQW5vQ1dHSTJoMGRIQTZMeTlqY213dVlYQndiR1V1WTI5dEwyRndjR3hsWVdsallUTXVZM0pzTUE0R0ExVWREd0VCL3dRRUF3SUhnREFQQmdrcWhraUc5Mk5rQmgwRUFnVUFNQW9HQ0NxR1NNNDlCQU1DQTBnQU1FVUNJSEtLbncrU295cTVtWFFyMVY2MmMwQlhLcGFIb2RZdTlUV1hFUFVXUHBicEFpRUFrVGVjZlc2K1c1bDByMEFEZnpUQ1BxMll0YlMzOXcwMVhJYXlxQk55OGJFd2dnTHVNSUlDZGFBREFnRUNBZ2hKYlMrL09wamFsekFLQmdncWhrak9QUVFEQWpCbk1Sc3dHUVlEVlFRRERCSkJjSEJzWlNCU2IyOTBJRU5CSUMwZ1J6TXhKakFrQmdOVkJBc01IVUZ3Y0d4bElFTmxjblJwWm1sallYUnBiMjRnUVhWMGFHOXlhWFI1TVJNd0VRWURWUVFLREFwQmNIQnNaU0JKYm1NdU1Rc3dDUVlEVlFRR0V3SlZVekFlRncweE5EQTFNRFl5TXpRMk16QmFGdzB5T1RBMU1EWXlNelEyTXpCYU1Ib3hMakFzQmdOVkJBTU1KVUZ3Y0d4bElFRndjR3hwWTJGMGFXOXVJRWx1ZEdWbmNtRjBhVzl1SUVOQklDMGdSek14SmpBa0JnTlZCQXNNSFVGd2NHeGxJRU5sY25ScFptbGpZWFJwYjI0Z1FYVjBhRzl5YVhSNU1STXdFUVlEVlFRS0RBcEJjSEJzWlNCSmJtTXVNUXN3Q1FZRFZRUUdFd0pWVXpCWk1CTUdCeXFHU000OUFnRUdDQ3FHU000OUF3RUhBMElBQlBBWEVZUVoxMlNGMVJwZUpZRUhkdWlBb3UvZWU2NU40STM4UzVQaE0xYlZabHMxcmlMUWwzWU5JazU3dWdqOWRoZk9pTXQydTJad3Zzam9LWVQvVkVXamdmY3dnZlF3UmdZSUt3WUJCUVVIQVFFRU9qQTRNRFlHQ0NzR0FRVUZCekFCaGlwb2RIUndPaTh2YjJOemNDNWhjSEJzWlM1amIyMHZiMk56Y0RBMExXRndjR3hsY205dmRHTmhaek13SFFZRFZSME9CQllFRkNQeVNjUlBrK1R2SitiRTlpaHNQNks3L1M1TE1BOEdBMVVkRXdFQi93UUZNQU1CQWY4d0h3WURWUjBqQkJnd0ZvQVV1N0Rlb1ZnemlKcWtpcG5ldnIzcnI5ckxKS3N3TndZRFZSMGZCREF3TGpBc29DcWdLSVltYUhSMGNEb3ZMMk55YkM1aGNIQnNaUzVqYjIwdllYQndiR1Z5YjI5MFkyRm5NeTVqY213d0RnWURWUjBQQVFIL0JBUURBZ0VHTUJBR0NpcUdTSWIzWTJRR0FnNEVBZ1VBTUFvR0NDcUdTTTQ5QkFNQ0EyY0FNR1FDTURyUGNvTlJGcG14aHZzMXcxYktZci8wRiszWkQzVk5vbzYrOFp5QlhrSzNpZmlZOTV0Wm41alZRUTJQbmVuQy9nSXdNaTNWUkNHd293VjNiRjN6T0R1UVovMFhmQ3doYlpaUHhuSnBnaEp2VlBoNmZSdVp5NXNKaVNGaEJwa1BDWklkQUFBeGdnR01NSUlCaUFJQkFUQ0JoakI2TVM0d0xBWURWUVFERENWQmNIQnNaU0JCY0hCc2FXTmhkR2x2YmlCSmJuUmxaM0poZEdsdmJpQkRRU0F0SUVjek1TWXdKQVlEVlFRTERCMUJjSEJzWlNCRFpYSjBhV1pwWTJGMGFXOXVJRUYxZEdodmNtbDBlVEVUTUJFR0ExVUVDZ3dLUVhCd2JHVWdTVzVqTGpFTE1Ba0dBMVVFQmhNQ1ZWTUNDQ1JEOHFnR25mVjNNQTBHQ1dDR1NBRmxBd1FDQVFVQW9JR1ZNQmdHQ1NxR1NJYjNEUUVKQXpFTEJna3Foa2lHOXcwQkJ3RXdIQVlKS29aSWh2Y05BUWtGTVE4WERURTVNREl3TlRFME1UZ3dNRm93S2dZSktvWklodmNOQVFrME1SMHdHekFOQmdsZ2hrZ0JaUU1FQWdFRkFLRUtCZ2dxaGtqT1BRUURBakF2QmdrcWhraUc5dzBCQ1FReElnUWdrcVhiV2lWUGI0KzIxWkg4Y2RGQVpISzJ3Y1M1cjhZc3l4L1p6YUpIbkdnd0NnWUlLb1pJemowRUF3SUVSekJGQWlFQTdjT3ZVK01QVHZMVnpmenJFckMwdGpJL1pCb2FsTmFiQWJUcWUvRFdzeVlDSUF5dTdGa1FZV0o4Z0doTW4wZE14L2Q4MHI5N1BmMU1QeGtobDlXVjNzNjdBQUFBQUFBQSIsImhlYWRlciI6eyJlcGhlbWVyYWxQdWJsaWNLZXkiOiJNRmt3RXdZSEtvWkl6ajBDQVFZSUtvWkl6ajBEQVFjRFFnQUVzaFhkdFl2dE5RL2JoNEJSWnZXQmM5Mk5aeUlYR0ltbU9PN0xoY0V4SG94YTZMS3U1aXhLZEpEcGx6cDNyTXJTWGMxMFF0NU5Wa0ZqU1JxOHRrMGREdz09IiwicHVibGljS2V5SGFzaCI6ImFWYzd2UTRTTzEyUnVEWUlyajhOT25zL05ncUJYZm1EaWE1ZmZKcWVwRzQ9IiwidHJhbnNhY3Rpb25JZCI6IjNlODA3NzRiYmMzODVlYzA4YTU3ZTAyYWNiZjAwZmM3NGEzZDAzMmJlODRjNDI0ODFlMmNmYzRmNDQ0NjA4MmIifX0sInBheW1lbnRNZXRob2QiOnsiZGlzcGxheU5hbWUiOiJWaXNhIDQ2NTUiLCJuZXR3b3JrIjoiVmlzYSIsInR5cGUiOiJkZWJpdCJ9LCJ0cmFuc2FjdGlvbklkZW50aWZpZXIiOiIzRTgwNzc0QkJDMzg1RUMwOEE1N0UwMkFDQkYwMEZDNzRBM0QwMzJCRTg0QzQyNDgxRTJDRkM0RjQ0NDYwODJCIn0=",
            "pmt_desc": "Тестовий платіж",
            "pmt_info": {
                "custom_merchant_field": 1234567
            },
            "guid": "AD68E7675FE111E79A65005056B960DF"
        }
    }
}    
            

Перелік запитів

1. CalculateFee (Попередній розрахунок комісії)

Структура тіла запиту

Поле	Тип	Опис
Обов'язкові поля
invoice	string	Сума платежу, у копійках
Опціональні поля
msisdn	string	Номер телефону
guid	string	Ідентифікатор запиту, сформований мерчантом

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

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00dc94b74a7cfdced473 ..."
        },
        "action": "CalculateFee",
        "body": {
            "msisdn": "380931234567",
            "invoice": 100,
            "guid": "AD68E7675FE111E79A65005056B960DF"
        }
    }
}    
            

Структура відповіді

Поле	Тип	Опис
response	object	Тіло відповіді
response.invoice	string	Сума платежу, у копійках
response.amount	string	Сума до сплати (з урахуванням комісії), у копійках
response.fee	string	Сума комісії, у копійках

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

{
    "response": {
        "invoice":"1000",
        "amount":"1100",
        "fee":"100",
    }
}
            

2. PaymentCreate (Створити платіж)

Структура тіла запиту

Поле	Тип	Опис
Обов'язкові поля
invoice	string	Сума платежу, у копійках
apple_data	string	PaymentToken ApplePay у форматі JSON закодований в Base64
pmt_desc	string	Опис платежу
pmt_info	object	Інформація до платежу, надається мерчантом при створенні, якщо присутнє значення (integer) smch_id - буде обиратись зазначена юридична особа
Опціональні поля
msisdn	string	Номер телефону
guid	string	Ідентифікатор запиту, сформований мерчантом

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

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00dc94b74a7cfdced473 ..."
        },
        "action": "PaymentCreate",
        "body": {
            "msisdn": "380931234567",
            "invoice": 100,
            "apple_data": "eyJwYXltZW50RGF0YSI6eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoiZ3ZNWHVzcjZlWDE3WWFkNTduRmt5UUJoRkxOUUc4WmtSS3BUZlZuak12V0V0K2RmYVpnSUVnWmpJRzV3ODgzUWozbkNNQTBpaWVnSUpFbkNuNkJJakJPZ0dhRlFXSXN2YkNBVXFaUDMrOGF3QWFZRy9oYjFHNm1SOHY1cFlGdFNYOVU3UUVyajVMREFERlJ1Q05ZQlUvOFplc04rZG0vdkUwVDA2VkpydjhJRVR6Zm5BT3JIVDdqZ2hPTEVYVkNHNWN0SlVXL25aZUQrVFN4Y1BoMC93RTdMY3BIRDJQK09waks2dlZVL1A5UlB3cERoSXlQODBvNHNMbDI4L2xZS0gxb1hBZTYzTC8wL1Rrc1YzN0g5cFQ3b2NzOWhPNjFXcGViUDkxemk5VTNZOEdBZGxkZ2U0VG1hbDZTWTJacjNkWXNCbk5WTGt1RkNQNHlqOFd2Yjc4dFN1Z2tLaDFvZ3lGN24wRjNJQ2hZaDJTd0FvbmVRM1dGZWhRbThHaGRQNDZIUU5XbURMdm9KRG8vU0xrOE1EYlFhTytxQjVxU2xDek52OVVneSIsInNpZ25hdHVyZSI6Ik1JQUdDU3FHU0liM0RRRUhBcUNBTUlBQ0FRRXhEekFOQmdsZ2hrZ0JaUU1FQWdFRkFEQ0FCZ2txaGtpRzl3MEJCd0VBQUtDQU1JSUQ0akNDQTRpZ0F3SUJBZ0lJSkVQeXFBYWQ5WGN3Q2dZSUtvWkl6ajBFQXdJd2VqRXVNQ3dHQTFVRUF3d2xRWEJ3YkdVZ1FYQndiR2xqWVhScGIyNGdTVzUwWldkeVlYUnBiMjRnUTBFZ0xTQkhNekVtTUNRR0ExVUVDd3dkUVhCd2JHVWdRMlZ5ZEdsbWFXTmhkR2x2YmlCQmRYUm9iM0pwZEhreEV6QVJCZ05WQkFvTUNrRndjR3hsSUVsdVl5NHhDekFKQmdOVkJBWVRBbFZUTUI0WERURTBNRGt5TlRJeU1EWXhNVm9YRFRFNU1Ea3lOREl5TURZeE1Wb3dYekVsTUNNR0ExVUVBd3djWldOakxYTnRjQzFpY205clpYSXRjMmxuYmw5VlF6UXRVRkpQUkRFVU1CSUdBMVVFQ3d3TGFVOVRJRk41YzNSbGJYTXhFekFSQmdOVkJBb01Da0Z3Y0d4bElFbHVZeTR4Q3pBSkJnTlZCQVlUQWxWVE1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRXdoVjM3ZXZXeDdJaGoyamRjSkNoSVkzSHNMMXZMQ2c5aEdDVjJVcjBwVUViZzBJTzJCSHpRSDZETXg4Y1ZNUDM2eklnMXJyVjFPLzBrb21KUG53UEU2T0NBaEV3Z2dJTk1FVUdDQ3NHQVFVRkJ3RUJCRGt3TnpBMUJnZ3JCZ0VGQlFjd0FZWXBhSFIwY0RvdkwyOWpjM0F1WVhCd2JHVXVZMjl0TDI5amMzQXdOQzFoY0hCc1pXRnBZMkV6TURFd0hRWURWUjBPQkJZRUZKUlgyMi9WZElHR2lZbDJMMzVYaFFmbm0xZ2tNQXdHQTFVZEV3RUIvd1FDTUFBd0h3WURWUjBqQkJnd0ZvQVVJL0pKeEUrVDVPOG41c1QyS0d3L29ydjlMa3N3Z2dFZEJnTlZIU0FFZ2dFVU1JSUJFRENDQVF3R0NTcUdTSWIzWTJRRkFUQ0IvakNCd3dZSUt3WUJCUVVIQWdJd2diWU1nYk5TWld4cFlXNWpaU0J2YmlCMGFHbHpJR05sY25ScFptbGpZWFJsSUdKNUlHRnVlU0J3WVhKMGVTQmhjM04xYldWeklHRmpZMlZ3ZEdGdVkyVWdiMllnZEdobElIUm9aVzRnWVhCd2JHbGpZV0pzWlNCemRHRnVaR0Z5WkNCMFpYSnRjeUJoYm1RZ1kyOXVaR2wwYVc5dWN5QnZaaUIxYzJVc0lHTmxjblJwWm1sallYUmxJSEJ2YkdsamVTQmhibVFnWTJWeWRHbG1hV05oZEdsdmJpQndjbUZqZEdsalpTQnpkR0YwWlcxbGJuUnpMakEyQmdnckJnRUZCUWNDQVJZcWFIUjBjRG92TDNkM2R5NWhjSEJzWlM1amIyMHZZMlZ5ZEdsbWFXTmhkR1ZoZFhSb2IzSnBkSGt2TURRR0ExVWRId1F0TUNzd0thQW5vQ1dHSTJoMGRIQTZMeTlqY213dVlYQndiR1V1WTI5dEwyRndjR3hsWVdsallUTXVZM0pzTUE0R0ExVWREd0VCL3dRRUF3SUhnREFQQmdrcWhraUc5Mk5rQmgwRUFnVUFNQW9HQ0NxR1NNNDlCQU1DQTBnQU1FVUNJSEtLbncrU295cTVtWFFyMVY2MmMwQlhLcGFIb2RZdTlUV1hFUFVXUHBicEFpRUFrVGVjZlc2K1c1bDByMEFEZnpUQ1BxMll0YlMzOXcwMVhJYXlxQk55OGJFd2dnTHVNSUlDZGFBREFnRUNBZ2hKYlMrL09wamFsekFLQmdncWhrak9QUVFEQWpCbk1Sc3dHUVlEVlFRRERCSkJjSEJzWlNCU2IyOTBJRU5CSUMwZ1J6TXhKakFrQmdOVkJBc01IVUZ3Y0d4bElFTmxjblJwWm1sallYUnBiMjRnUVhWMGFHOXlhWFI1TVJNd0VRWURWUVFLREFwQmNIQnNaU0JKYm1NdU1Rc3dDUVlEVlFRR0V3SlZVekFlRncweE5EQTFNRFl5TXpRMk16QmFGdzB5T1RBMU1EWXlNelEyTXpCYU1Ib3hMakFzQmdOVkJBTU1KVUZ3Y0d4bElFRndjR3hwWTJGMGFXOXVJRWx1ZEdWbmNtRjBhVzl1SUVOQklDMGdSek14SmpBa0JnTlZCQXNNSFVGd2NHeGxJRU5sY25ScFptbGpZWFJwYjI0Z1FYVjBhRzl5YVhSNU1STXdFUVlEVlFRS0RBcEJjSEJzWlNCSmJtTXVNUXN3Q1FZRFZRUUdFd0pWVXpCWk1CTUdCeXFHU000OUFnRUdDQ3FHU000OUF3RUhBMElBQlBBWEVZUVoxMlNGMVJwZUpZRUhkdWlBb3UvZWU2NU40STM4UzVQaE0xYlZabHMxcmlMUWwzWU5JazU3dWdqOWRoZk9pTXQydTJad3Zzam9LWVQvVkVXamdmY3dnZlF3UmdZSUt3WUJCUVVIQVFFRU9qQTRNRFlHQ0NzR0FRVUZCekFCaGlwb2RIUndPaTh2YjJOemNDNWhjSEJzWlM1amIyMHZiMk56Y0RBMExXRndjR3hsY205dmRHTmhaek13SFFZRFZSME9CQllFRkNQeVNjUlBrK1R2SitiRTlpaHNQNks3L1M1TE1BOEdBMVVkRXdFQi93UUZNQU1CQWY4d0h3WURWUjBqQkJnd0ZvQVV1N0Rlb1ZnemlKcWtpcG5ldnIzcnI5ckxKS3N3TndZRFZSMGZCREF3TGpBc29DcWdLSVltYUhSMGNEb3ZMMk55YkM1aGNIQnNaUzVqYjIwdllYQndiR1Z5YjI5MFkyRm5NeTVqY213d0RnWURWUjBQQVFIL0JBUURBZ0VHTUJBR0NpcUdTSWIzWTJRR0FnNEVBZ1VBTUFvR0NDcUdTTTQ5QkFNQ0EyY0FNR1FDTURyUGNvTlJGcG14aHZzMXcxYktZci8wRiszWkQzVk5vbzYrOFp5QlhrSzNpZmlZOTV0Wm41alZRUTJQbmVuQy9nSXdNaTNWUkNHd293VjNiRjN6T0R1UVovMFhmQ3doYlpaUHhuSnBnaEp2VlBoNmZSdVp5NXNKaVNGaEJwa1BDWklkQUFBeGdnR01NSUlCaUFJQkFUQ0JoakI2TVM0d0xBWURWUVFERENWQmNIQnNaU0JCY0hCc2FXTmhkR2x2YmlCSmJuUmxaM0poZEdsdmJpQkRRU0F0SUVjek1TWXdKQVlEVlFRTERCMUJjSEJzWlNCRFpYSjBhV1pwWTJGMGFXOXVJRUYxZEdodmNtbDBlVEVUTUJFR0ExVUVDZ3dLUVhCd2JHVWdTVzVqTGpFTE1Ba0dBMVVFQmhNQ1ZWTUNDQ1JEOHFnR25mVjNNQTBHQ1dDR1NBRmxBd1FDQVFVQW9JR1ZNQmdHQ1NxR1NJYjNEUUVKQXpFTEJna3Foa2lHOXcwQkJ3RXdIQVlKS29aSWh2Y05BUWtGTVE4WERURTVNREl3TlRFME1UZ3dNRm93S2dZSktvWklodmNOQVFrME1SMHdHekFOQmdsZ2hrZ0JaUU1FQWdFRkFLRUtCZ2dxaGtqT1BRUURBakF2QmdrcWhraUc5dzBCQ1FReElnUWdrcVhiV2lWUGI0KzIxWkg4Y2RGQVpISzJ3Y1M1cjhZc3l4L1p6YUpIbkdnd0NnWUlLb1pJemowRUF3SUVSekJGQWlFQTdjT3ZVK01QVHZMVnpmenJFckMwdGpJL1pCb2FsTmFiQWJUcWUvRFdzeVlDSUF5dTdGa1FZV0o4Z0doTW4wZE14L2Q4MHI5N1BmMU1QeGtobDlXVjNzNjdBQUFBQUFBQSIsImhlYWRlciI6eyJlcGhlbWVyYWxQdWJsaWNLZXkiOiJNRmt3RXdZSEtvWkl6ajBDQVFZSUtvWkl6ajBEQVFjRFFnQUVzaFhkdFl2dE5RL2JoNEJSWnZXQmM5Mk5aeUlYR0ltbU9PN0xoY0V4SG94YTZMS3U1aXhLZEpEcGx6cDNyTXJTWGMxMFF0NU5Wa0ZqU1JxOHRrMGREdz09IiwicHVibGljS2V5SGFzaCI6ImFWYzd2UTRTTzEyUnVEWUlyajhOT25zL05ncUJYZm1EaWE1ZmZKcWVwRzQ9IiwidHJhbnNhY3Rpb25JZCI6IjNlODA3NzRiYmMzODVlYzA4YTU3ZTAyYWNiZjAwZmM3NGEzZDAzMmJlODRjNDI0ODFlMmNmYzRmNDQ0NjA4MmIifX0sInBheW1lbnRNZXRob2QiOnsiZGlzcGxheU5hbWUiOiJWaXNhIDQ2NTUiLCJuZXR3b3JrIjoiVmlzYSIsInR5cGUiOiJkZWJpdCJ9LCJ0cmFuc2FjdGlvbklkZW50aWZpZXIiOiIzRTgwNzc0QkJDMzg1RUMwOEE1N0UwMkFDQkYwMEZDNzRBM0QwMzJCRTg0QzQyNDgxRTJDRkM0RjQ0NDYwODJCIn0=",
            "pmt_desc": "Тестовий платіж",
            "pmt_info": {
                "custom_merchant_field": 1234567,
                "smch_id": 112233
            },
            "guid": "AD68E7675FE111E79A65005056B960DF"
        }
    }
}    
            

Структура відповіді

Поле	Тип	Опис
response	object	Тіло відповіді
response.pmt_id	string	ID платежу в системі iPay
response.invoice	string	Сума платежу, у копійках
response.amount	string	Сума до сплати (з урахуванням комісії), у копійках
response.pmt_status	string	Статус платежу (1 - зареєстрований, 4 - неуспішний, 5 - успішний)
response.card_mask	string	Маска картки
response.bank_response	object	Відповідь банку
response.bank_response.error_group	integer	Група помилки
response.rrn	string	RRN (повертається для статусу платежу - 1, 5)

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

{
    "response": {
        "pmt_id":"1234567",
        "invoice":"100",
        "amount":"100",
        "pmt_status":"4",
        "card_mask":"****************",
        "bank_response": {
            "error_group":12
        },
        "rrn": "021705522966"
    }
}
            

3. PaymentSale (Завершити платіж)

Структура тіла запиту

Поле	Тип	Опис
Обов'язкові поля
pmt_id	string	ID платежу в системі iPay
Опціональні поля
guid	string	Ідентифікатор запиту, сформований мерчантом
invoice	string	invoice integer Остаточна сума покупки у копійках У випадку якщо сумма заменьша ніж була на запиті PaymentCreate, буде викононо повернення різниці

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

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00 ..."
        },
        "action": "PaymentSale",
        "body": {
            "pmt_id": "1234567",
            "invoice": 100,
            "guid": "e55f613987964042a92bfc2d4f0d610d"
        }
    }
}    

Структура відповіді

Поле	Тип	Опис
response	object	Тіло відповіді
response.pmt_id	string	ID платежу в системі iPay
response.invoice	string	Сума платежу, у копійках
response.amount	string	Сума до сплати (з урахуванням комісії), у копійках
response.pmt_status	string	Статус платежу (1 - зареєстрований, 4 - неуспішний, 5 - успішний)
response.card_mask	string	Маска картки
response.bank_response	object	Відповідь банку
response.bank_response.error_group	integer	Група помилки
response.rrn	string	RRN (повертається для статусу платежу - 1, 5)

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

{
    "response": {
        "pmt_id":"1234567",
        "invoice":"100",
        "amount":"100",
        "pmt_status":"4",
        "card_mask":"****************",
        "bank_response":{
            "error_group":12
        },
        "rrn": "021705522966"
    }
}

4. PaymentCancel (Відмінити платіж)

Структура тіла запиту

Поле	Тип	Опис
Обов'язкові поля
pmt_id	string	ID платежу в системі iPay
Опціональні поля
guid	string	Ідентифікатор запиту, сформований мерчантом

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

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00 ..."
        },
        "action": "PaymentCancel",
        "body": {
            "pmt_id": "1234567"
        }
    }
}    

Структура відповіді

Поле	Тип	Опис
response	object	Тіло відповіді
response.pmt_id	string	ID платежу в системі iPay
response.invoice	string	Сума платежу, у копійках
response.amount	string	Сума до сплати (з урахуванням комісії), у копійках
response.pmt_status	string	Статус платежу (1 - зареєстрований, 4 - неуспішний, 5 - успішний)
response.card_mask	string	Маска картки
response.bank_response	object	Відповідь банку
response.bank_response.error_group	integer	Група помилки

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

{
    "response": {
        "pmt_id":"1234567",
        "invoice":"100",
        "amount":"100",
        "pmt_status":"9",
        "card_mask":"****************",
        "bank_response":{
            "error_group":12
        }
    }
}

5. GetPaymentInvoice (Запросити квитанцію)

Структура тіла запиту

Поле	Тип	Опис
Обов'язкові поля
pmt_id	string	ID платежу в системі iPay

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

{
    "request":{
        "auth":{
            "login":"test",
            "time":"2019-02-19 10:47:35",
            "sign":"a468afe066f57e08d2b36dd74c03218f3701b17aba8fa15ebea..."
        },
        "action":"GetPaymentInvoice",
        "body":{
            "pmt_id":"1234567"
        }
    }
}

Структура відповіді

Поле	Тип	Опис
response	object	Тіло відповіді
response.invoice	string	Посилання на квитанцію

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

{
    "response": {
        "invoice": "https://example.com/invoice/23d53e29722d2b03c954718c1d54b53787985090"
    }
}

6. StatusRequest (Статус запиту)

Структура тіла запиту

Поле	Тип	Опис
Обов'язкові поля
guid	string	Ідентифікатор запиту мерчанта, що був переданий у попередніх запитах
Опціональні поля
msisdn	string	Номер телефону, довжина 12 цифр (наприклад 380931234567)

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

{
    "request":{
        "auth":{
            "login":"test",
            "time":"2019-02-19 10:47:35",
            "sign":"a468afe066f57e08d2b36dd74c03218f3701b17aba8fa15ebea..."
        },
        "action":"StatusRequest",
        "body":{
            "guid":"AD68E7675FE111E79A65005056B960DFF"
        }
    }
}

Структура відповіді

Поле	Тип	Опис
response	array	Тіло відповіді
response[].action	string	Назва запиту
response[].msisdn	string	Номер телефону, довжина 12 цифр (наприклад 380931234567)
response[].response	string	Відповідь у форматі json
response[].date	string	Дата на момент запиту

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

{
    "response": [
        {
            "action": "PaymentCreate",
            "msisdn": "380931234567",
            "response": "{"pmt_id":"1234567","invoice":"200000","amount":"200000","pmt_status":"1",
                        "card_alias":"TEST","card_mask":"111122********44","msisdn":"380931234567",
                        "bank_response":"{"bank_id":28,"rc":"00","action":"0","error_group":""}"}",
            "date": "2017-01-01 15:47:27"
        }
    ]
}

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

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

1. Ваш сайт повинен працювати за схемою HTTPS і підтримувати протокол TLS 1.2.

2. Потрібно погодитись з умовами надання послуг Apple Pay.

3. Необхідно укласти договір з Ipay.ua

Інтеграції Apple Pay на сайт :

1. Необхідно мати аккаунт в Apple Developer

2. Додайте новий Merchant ID в Apple Developer Account

• Оберіть створений вами Merchant ID та натисніть «Edit».
• У розділі «Merchant Domains» натисніть «Add Domain».
• Зареєструйте та підтвердьте свій домен

3. Створіть Apple Pay Merchant Identity Certificate:

• У розділі «Apple Pay Merchant Identity Certificate» натисніть «Create Certificate»
• Виконайте дії, описані на сайті Apple, а потім натисніть «Continue».
• Скопіюйте створений сертифікат у форматі .pem на сервер. Це буде необхідно для створення Apple Pay Payment Session в процесі перевірки магазину.

3. Створіть Apple Pay Payment processing certificate :
developer.apple.com/documentation/passkit/apple_pay/setting_up_apple_pay_requirements

• Запросити у відповідального менеджера CSR-файл, сформований Ipay.ua
• Сформуйте Apple Pay Payment Processing Certificate та передайте його відповідальному менеджеру

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

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

Перевірте можливість оплати з Apple Pay

        if(window.ApplePaySession && window.ApplePaySession.canMakePayments() ){
      
        var merchantIdentifier='{YourMchName}';
        var  promise = ApplePaySession.canMakePaymentsWithActiveCard(merchantIdentifier);
        promise.then(function (canMakePayments) {
            if (canMakePayments){
            }
         });
    }
});      
       

Обробка кліка по кнопці ApplePay

       function applePayButtonClick() {

     var merchantID = '{YourMchName}';

     var  session= new ApplePaySession(3,createPaymentRequest());

      session.begin();

     session.onvalidatemerchant = (event) => {

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

     };

     session.onpaymentauthorized = function (event) {

         if (event.payment.token) {
         
          //event.payment.token  (Токен який треба передаты до  Ipay.ua)
         
             session.completePayment(ApplePaySession.STATUS_SUCCESS);
         } else {
             session.completePayment(ApplePaySession.STATUS_FAILURE);
            
         }


     };
 }
       
       

Створення інформації платежу

developer.apple.com/documentation/apple_pay_on_the_web/applepayrequest

          
          function createPaymentRequest() {

        var request = {
            "countryCode": "UA",
            "currencyCode": "UAH",
            "merchantCapabilities": [
                "supports3DS"
            ],
            "supportedNetworks": [
                "visa",
                "masterCard"
            ],
            "total": {
                "label": "{yourLabel}",
                "type": "final",
                "amount": "{yourAmount}"
            }
        };

        return request;
    }
          
          

Запит на Ваш сервер для отримання об'єкта сесії

developer.apple.com/documentation/apple_pay_on_the_web/apple_pay_js_api/requesting_an_apple_pay_payment_session

       function performValidation(valURL) {


    return new Promise(function(resolve, reject) {

        var body='url='+valURL;
        var xhr = new XMLHttpRequest();
        xhr.onload = function() {

            var data = JSON.parse(this.responseText);

            resolve(data);
        };
        xhr.onerror = reject;
        xhr.open('POST','{yourUrlForGetAppleSession}',true);
        xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
        xhr.send(body);
    });
}
       
       

Системні помилки

Структура відповіді

Поле	Тип	Опис
response	object	Тіло відповіді
response.error	string	Назва помилки, що виникла

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

{
    "response": {
        "error": "invalid request structure"
    }
}

Перелік можливіх помилок

Помилка	Опис
overall error	Загальна помилка
invalid request structure	Невірна структура запиту
unknown field {field_name}	У запиті передано поле, яке невідоме системі
invalid pan	Невірне значення pan
invalid expm	Невірне значення expm
invalid expy	Невірне значення expy
invalid cvv	Невірне значення cvv
invalid auth	Помилка аутентифікації
invalid auth time	Невірний час запиту
access denied	Доступ заборонено

Групи помилок

Якщо при виконанні запиту PaymentCreate або PaymentSale був отриманий статус 4, в об'єкті error поле bnk_error_group містить групу помилки банку.

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

{  
    "response":{  
        "pmt_id":"1234567",
        "invoice":"100",
        "amount":"100",
        "pmt_status":"4",
        "card_mask":"****************",
        "bank_response": {
            "error_group":12
        }
    }
}

Перелік груп помилок

Група помилки	Опис
41	Відмова емітента
42	Недостатньо коштів
43	Ліміт емітента
50	Невірний CVV
51	Помилка верифікації (3D Secure)
52	Помилка з'єднання
55	Невідома помилка

Історія змін

Дата	Версія	Опис змін
2019-02-10	1.0.0	Налаштування запитів PaymentCreate, PaymentSale.
2019-04-04	1.0.1	Додано запит CalculateFee - розрахунок коміссії перед створенням платежу. PaymentCreate - у pmt_info опис переданого значення smch_id PaymentSale - invoice переведений в опціональне поле