Перейти к содержанию

Подключение

Чтобы использовать сервис Masterpass, необходимо:

  1. Стать партнером программы Masterpass. Это можно сделать напрямую или с помощью вашего аккаунт-менеджера.

  2. Обратиться к аккаунт-менеджеру для настройки параметров доступа в Masterpass.

  3. Реализовать дополнительные методы интеграции для сервиса Masterpass:

  4. Добавить на всех страницах логотип Masterpass. Ваш аккант-менеджер подскажет требования к размещению логотипа.

Открытие сессии пользователя в системе Masterpass

Метод используется для авторизации пользователя в Masterpass. Например, в случаях:

  1. Первый и последующие входы в приложение
  2. Истечения срока жизни пользовательской сессии (от Masterpass была получена ошибка с Error_Code=8 или Error_Code=16). Необходимо выполнить повторный запрос на открытие сессии пользователя и получение списка карт.
Запрос

Для открытия сессии пользователя отправьте POST запрос на https://processing.ecomcharge.com/masterpass/login со следующими параметрами:

Параметр Тип Описание
phone * обязательный
 string Номер телефона пользователя.
fingerprint * обязательный
 string base64 Цифровой отпечаток устройства - набор уникальных параметров, преобразованных в формат Base64. Руководство по созданию значения параметра опубликовано в личном кабинете Masterpass (запросить у аккаунт-менеджера)
phone_check_date string Последняя успешная дата подтверждения телефона на стороне Мерчанта в формате Date(1612341218000), где 1612341218000 время в миллисекундах в формате Epoch
channel integer 0 = Recurring
1 = WEB
2 = APP iOS
3 = APP Android
4 = TVE
5 = SmartTV
6 = Smart devices
7 = USSD
8 = IVR
9 = Offline
10 = Other
test boolean true или false. Операция будет тестовой, если значение true
Пример запроса 
{
"fingerprint": "SGVpZ2h0PTg5NjtXaWR0aD00MTQ7T1NWZXJzaW9uPVZlcnNpb24gMTIuMS40IChCdWlsZCAxNkQ1Nyk7RGV2aWNlSWQ9Njk5NkI3QTYtMjREOS00Rj\nVBLUJFMDktOTlBRDQyMEFBRkZGO1RpbWVab25lPUV1cm9wZS9Nb3Njb3c7TW9kZWw9aVBob25lIFhSO09TPWlPUztQaG9uZUlkPTRDNDQzQzI2LUNE\nQTItNDYxQS05QUVGLTNEQkNFMTJCMkVFNztWZXJzaW9uUmVsZWFzZT0xMi4xLjQ7IFJlbW90ZUlwPTkxLjIzOC4xMjAuMTcxO1Bhc3N3b3JkPWNhMz\ndiMzEzMmFhNTE2YzQ1MzdiYWYyOGJiYzI1OTk5OWU0ZDA5ZTZlZTE1NWFkYjNkOGRiMDMzODJlYWI5ODk7WEZvcndhcmRlZEZvcj05MS4yMzguMTIw\nLjE3MSwyMTYuMTE5LjIwOS42NDtPVFA9MDNBQzY3NDIxNkYzRTE1Qzc2MUVFMUE1RTI1NUYwNjc5NTM2MjNDOEIzODhCNDQ1OUUxM0Y5NzhEN0M4ND\nZGNDtBQT1VMA==",
"phone": "77707811122",
"phone_check_date": "Date(1612341218000)",
"channel": 2,
"test": true
}
Ответ

При обработке запроса на открытие сессии система вернет ответ со следующими параметрами:

Параметр Тип Описание
status string Статус запроса.
error_code integer Код ошибки.
error string Сообщение об ошибке.
is_otp_required boolean Требуется проверка OTP
session string Идентификатор сессии пользователя в Masterpass
user_status integer Статус пользователя в Masterpass. Если статус не равен 1, то делать запрос на получение списка карт не нужно.
Пример успешного ответа 
{
"session": "c96fe83d-366c-420c-9038-da0fae844f0c",
"is_otp_required": false,
"user_status": 1
}
Коды ошибок

В случае возникновения ошибки при открытии сессии пользователя в системе Masterpass, чтобы понять причину ошибки, воспользуйтесь пояснением кодов для параметра error_code.

Код ошибки Описание Пояснение описания
0 None Успешное завершение вызова.
1 The service is not available for this card/user Текущий пользователь находится в черном списке.
2 Api not allowed Вызов метода запрещен после превышения допустимого количества запросов.
8 No user was found by the passed session Передана не существующая сессия или срок действия сессии истек. Необходимо заново активировать сессию.
10 Wrong phone format Неверный формат телефонного номера.
11 Empty DeviceId Обязательный параметр DeviceId не передан в Fingerprint, передано пустое поле или состоящее из пробелов.
13 Internal error while encrypting the response Внутренняя системная ошибка, требуется дополнительная проверка командой Masterpass
15 Merchant with such a name and password not found Обязательное поле Merchant не передано в запросе или мерчант с таким названием не найден.
19 The service is not available for this card/user or Wrong params Пользователь находится в черном списке. Превышено максимальное количество попыток отправки OTP. Ограничение считается одновременно для всех мерчантов. Запрос был отправлен с неверным или неполным набором параметров.
20 Internal error Внутренняя системная ошибка, требуется дополнительная проверка командой Masterpass
23 RequestTokenNotFound Переданное значение RequestToken не существует.
35 Wrong params В Fingerprint не переданы обязательные параметры
44 API_NOT_ALLOWED Сертификат не найден или истек срок действия сертификата, или ошибка подписи.

Сохранение новой карты в Masterpass

Прежде чем начать

Откройте сессию пользователя перед сохранением новой карты в Masterpass.

Запрос

Для сохранения карты в Masterpass используйте запросы оплаты или авторизации со следующими дополнительными параметрами:

Параметр Тип Описание
additional_data object Секция, содержащая дополнительную информацию о платеже.
contract * обязательный
 array Массив с элементом:

recurring - eComCharge вернет токен карты для осуществления последующих платежей без повторного ввода реквизитов карты. Пользователь, соглашаясь с условиями регулярного списания, единожды производит оплату, вводя реквизиты карты, включая проверочный код карты CVC/CVV и проходя авторизацию по протоколу 3-D ­Secure.
masterpass object Секция для работы с сервисом Masterpass.
params object Секция для параметров Masterpass.
session * обязательный
 string ID пользовательской сессии.
Пример запроса для операции оплаты 
{
"request": {
    "amount": 100,
    "currency": "USD",
    "description": "www",
    "tracking_id": "save_card_test_masterpass_success_2",
    "billing_address": {
    "first_name": "John",
    "last_name": "Doe",
    "country": "US",
    "city": "Denver",
    "state": "CO",
    "zip": "96002",
    "address": "1st Street"
    },
    "credit_card": {
    "number": "4200000000000000",
    "verification_value": "123",
    "holder": "John Doe",
    "exp_month": "05",
    "exp_year": "2026"
    },
    "additional_data": {
    "contract": [
        "recurring"
    ],
    "masterpass": {
        "params": {
        "session": "a6fd8624-8060-46b3-b343-7a93126fd57f"
        }
    }
    },
    "customer": {
    "ip": "127.0.0.1",
    "email": "email@example.com",
    "birth_date": "1998-01-31"
    },
    "test": true
}
}
Ответ

Если магазин участвует в программе Masterpass, то после проведения платежа, eComCharge направит запрос на сохранение карты в Masterpass. В ответе будет получен токен Masterpass и результат сохранения карты в Masterpass.

Info

Если проводится платеж только для сохранения карты, то после получения результатов сохранения, необходимо сделать возврат по этой транзакции.

Пример ответа для типа операции оплаты при успешном сохранении карты 
{
  "transaction": {
    "uid": "10134-ca74085dff",
    "status": "successful",
    "amount": 100,
    "currency": "USD",
    "description": "www",
    "type": "payment",
    "payment_method_type": "credit_card",
    "tracking_id": null,
    "message": "Successfully processed",
    "test": true,
    "created_at": "2021-03-15T07:47:27.904Z",
    "updated_at": "2021-03-15T07:47:31.095Z",
    "paid_at": "2021-03-15T07:47:31.055Z",
    "expired_at": null,
    "closed_at": null,
    "settled_at": null,
    "manually_corrected_at": null,
    "language": "en",
    "redirect_url": "https://processing.ecomcharge.com/process/10134-ca74085dff",
    "credit_card": {
      "holder": "John Doe",
      "stamp": "b3839d334ba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
      "brand": "visa",
      "last_4": "0000",
      "first_1": "4",
      "bin": "420000",
      "issuer_country": null,
      "issuer_name": null,
      "product": null,
      "exp_month": 5,
      "exp_year": 2026,
      "token_provider": null,
      "token": "495f97d6-862a-4445-b537-06d4b3fa392f"
    },
    "receipt_url": "https://gateway.ecomcharge.com/customer/transactions/10134-ca74085dff/f3dcf8284bbe70f87d1714095eb8101053ec4de77dd04e5c74aa280e54276b3d",
    "id": "10134-ca74085dff",
    "additional_data": {
      "contract": [
        "recurring"
      ],
      "masterpass": {
        "params": {
          "session": "35b55f8e-36d4-467a-b41f-28468a031898"
        },
        "result": {
          "status": "successful",
          "message": "Postback successfully finished.",
          "token": "31b1e418-6a56-490d-bb5b-15f11a2040d8"
        }
      }
    },
    "payment": {
      "auth_code": "654321",
      "bank_code": "05",
      "rrn": "999",
      "ref_id": "777888",
      "message": "Payment was approved",
      "amount": 100,
      "currency": "USD",
      "billing_descriptor": "test descriptor",
      "gateway_id": 288,
      "status": "successful"
    },
    "avs_cvc_verification": {
      "avs_verification": {
        "result_code": "1"
      },
      "cvc_verification": {
        "result_code": "1"
      }
    },
    "customer": {
      "ip": "127.0.0.1",
      "email": "email@example.com",
      "device_id": null,
      "birth_date": "1998-01-31"
    },
    "billing_address": {
      "first_name": "John",
      "last_name": "Doe",
      "address": "1st Street",
      "country": "US",
      "city": "Denver",
      "zip": "96002",
      "state": "CO",
      "phone": null
    }
  }
}
Коды ошибок

В случае возникновения ошибок при сохранении новой карты в Masterpass воспользуйтесь пояснением кодов для параметра error_code.

Код ошибки Описание Пояснение описания
0 Успешное завершение вызова.
1 The service is not available for this card/user Карта находится в черном списке. Рекомендуется обновить список карт вызовом GetCards или позволить пользователю сохранить новую карту.
2 Card is not activated Реквизиты карты в этом статусе не могут быть получены в GetCard. Рекомендуется обновить список карт вызовом GetCards или позволить пользователю сохранить новую карту
3 The card was not found by the token Карта с таким токеном не найдена. Рекомендуется обновить список карт вызовом GetCards или позволить пользователю сохранить новую карту
5 Customer with this phone number not found Пользователь с таким телефоном не найден.
12 This transaction is marked as fraud Операция отклонена системой фрод-мониторинга.
15 Merchant with such a name and password not found Обязательное поле Merchant не передано в запросе или мерчант с таким названием не найден.
16 Session for the card not found and it is not recurrent Передана не существующая сессия или срок действия сессии истек.
17 Amount <= 0 Значение параметра Amount должно быть строго больше 0
19 Wrong params Обязательный параметр Amount не передан в запросе, пустое поле или содержит что-либо кроме цифр. Запрос был отправлен с неверным или неполным набором параметров. Не переданы обязательные параметры или Amount= 0
44 API_NOT_ALLOWED Сертификат не найден или истек срок действия сертификата или ошибка подписи.
Пример ответа в случае ошибки при сохранении карты в Masterpass 
{
  "transaction": {
    "uid": "9706-fde9808c80",
    "status": "successful",
    "amount": 100,
    "currency": "USD",
    "description": "www",
    "type": "payment",
    "payment_method_type": "credit_card",
    "tracking_id": "save_card_test_masterpass_success_2",
    "message": "Successfully processed",
    "test": true,
    "created_at": "2021-02-12T12:13:43.314Z",
    "updated_at": "2021-02-12T12:13:49.492Z",
    "paid_at": "2021-02-12T12:13:49.439Z",
    "expired_at": null,
    "closed_at": null,
    "settled_at": null,
    "manually_corrected_at": null,
    "language": "en",
    "redirect_url": "https://processing.ecomcharge.com/process/9706-fde9808c80",
    "credit_card": {
      "holder": "John Doe",
      "stamp": "b3839d334ba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
      "brand": "visa",
      "last_4": "0000",
      "first_1": "4",
      "bin": "420000",
      "issuer_country": null,
      "issuer_name": null,
      "product": null,
      "exp_month": 5,
      "exp_year": 2026,
      "token_provider": null,
      "token": "330e7e46-2958-41f1-8272-42ea3e05ec4a"
    },
    "receipt_url": "https://gateway.ecomcharge.com/customer/transactions/9706-fde9808c80/c13d59bea3867441f360af4d4a7a75d6398d7d2eed34dd48185ee2e6df0522b4",
    "id": "9706-fde9808c80",
    "additional_data": {
      "contract": [
        "recurring"
      ],
      "masterpass": {
        "params": {
          "session": "session"
        },
        "result": {
          "status": "failed",
          "message": "SaveCard failed.",
          "error": "Masterpass error response",
          "error_message": null,
          "error_code": 8
        }
      }
    },
    "payment": {
      "auth_code": "654321",
      "bank_code": "05",
      "rrn": "999",
      "ref_id": "777888",
      "message": "Payment was approved",
      "amount": 100,
      "currency": "USD",
      "billing_descriptor": "test descriptor",
      "gateway_id": 288,
      "status": "successful"
    },
    "avs_cvc_verification": {
      "avs_verification": {
        "result_code": "1"
      },
      "cvc_verification": {
        "result_code": "1"
      }
    },
    "customer": {
      "ip": "127.0.0.1",
      "email": "email@example.com",
      "device_id": null,
      "birth_date": "1998-01-31"
    },
    "billing_address": {
      "first_name": "John",
      "last_name": "Doe",
      "address": "1st Street",
      "country": "US",
      "city": "Denver",
      "zip": "96002",
      "state": "CO",
      "phone": null
    }
  }
}

Получение списка карт из Masterpass

Прежде чем начать

Откройте сессию пользователя перед получением списка карт из Masterpass.

Info

eComCharge убирает из списка карт бренды, по которым eComCharge не сможет провести оплату (шлюз магазина может не поддерживать карточный бренд пользователя, который он ранее привязал в Masterpass).

Запрос

Для получения списка карт из Masterpass отправьте POST запрос на https://processing.ecomcharge.com/masterpass/get_cards со следующими параметрами:

Параметр Тип Описание
session * обязательный
 string ID пользовательской сессии.
test boolean true или false. Операция будет тестовой, если значение true
Пример запроса 
{
    "session": "c96fe83d-366c-420c-9038-da0fae844f0c",
    "test": true
}
Ответ

Прежде, чем направить ответ, eComCharge проводит его трансформацию:

  1. Убирает карты с истекшим сроком действия (CardStatus=5) из списка карт
  2. Убирает карты, по которым не сможет провести транзакцию, из списка карт.

При успешной обработке запроса система вернет ответ со следующими параметрами:

Параметр Тип Описание
card_list array Список карт с их параметрами.
card_holder * обязательный
 string Имя владельца карты: только латинские буквы, цифры, пробелы, тире.
token * обязательный
 string Токен карты в Masterpass
date * обязательный
 string Дата добавления карты. Время в миллисекундах в формате Epoch
expiry_date * обязательный
 string Дата окончания срока действия
pan_mask * обязательный
 string Первые 6 цифр и последние 4 цифры номера карты
card_status * обязательный
 integer Статус карты. Возможные значения:

0 - Inactive. Карта неактивна
1 - Active. Карта активна
2 - CVC2Always. Необходима проверка CVC2
5 - Expired. Срок действия карты истек.
is_recurring * обязательный
 boolean Рекуррентная карта.
card_name * обязательный
 string Имя карты: буквы должны быть русскими / латинскими, пробелы, тире, * _- +, символы валюты
comment1 string Поле для комментариев 1
comment2 string Поле для комментариев 2
comment3 string Поле для комментариев 3
Пример ответа при наличии у пользователя карт в Masterpass 
{
"card_list": [
    {
    "card_holder": "Masterpass",
    "token": "8358d402-1111-1111-1111-9dc9811debe",
    "expiry_date": "02/21",
    "pan_mask": "511111xxxxxx8278",
    "card_status": 2,
    "is_recurring": false,
    "card_name": "My card"
    }
]
}
Пример ответа, если у пользователя нет карт в Masterpass 
{
"card_list": []
}

При ошибке система вернет ответ со следующими параметрами:

Параметр Тип Описание
status * обязательный
 string Статус запроса.
error_code * обязательный
 integer Код ошибки.
error * обязательный
 string Сообщение об ошибке.
Коды ошибок

В случае возникновения ошибок при получении списка карт из Masterpass воспользуйтесь пояснением кодов для параметра error_code.

Код ошибки Описание Пояснение описания
0 None Успешное завершение вызова.
2 Api not allowed Вызов метода запрещен после превышения допустимого количества запросов.
8 No user was found by the passed session Передана не существующая сессия или срок действия сессии истек. Необходимо заново активировать сессию
35 Wrong params Запрос был отправлен с неверным или неполным набором параметров.
Пример ответа в случае ошибки 
{
"status": "failed",
"error": "Masterpass error response",
"error_code": 8
}

Получение карты из Masterpass

Прежде чем начать

Получите список карт до запроса карты из Masterpass.

Метод используется для каждой транзакции с участием пользователя, чтобы получить актуальные сведения по карте.

Для рекуррентных платежей по токену, метод вызывается автоматически eComCharge.

Запрос

Для получения карты из Masterpass отправьте POST запрос на https://processing.ecomcharge.com/masterpass/get_card со следующими параметрами:

Параметр Тип Описание
token * обязательный
 string Токен Masterpass (из запроса на получение списка карт)
amount * обязательный
 integer Cумма в минимальных денежных единицах. Например, $32.45 должна быть отправлена как 3245 (равна или больше 0)
session * условно обязательный
 string Идентификатор сессии пользователя в Masterpass. Обязательный для нерекуррентных карт.
currency * обязательный
 string Валюта в ISO-4217 формате, например USD
test boolean true или false. Операция будет тестовой, если значение true
Пример запроса 
{
"session": "a6fd8624-8060-46b3-b343-7a93126fd57f",
"token": "2887f05c-ff7e-4e67-90e6-7d5e75abc036",
"amount": 10000,
"currency ": "USD",
"test": true
}
Ответ

При успешной обработке запроса система вернет ответ со следующими параметрами:

Параметр Тип Описание
credit_card object Информация о карте.
stamp * обязательный
 string Хэш карты
brand * обязательный
 string Название бренда карты
last_4 * обязательный
 integer Последние 4 цифры номера карты
first_1 * обязательный
 integer Первая цифра номера карты
bin * обязательный
 integer BIN-номер карты
issuer_country * обязательный
 string Страна выпуска карты
issuer_name * обязательный
 string Название эмитента карты
product * обязательный
 string Название карточного продукта.
exp_month * обязательный
 integer Месяц окончания срока действия карты. 2 цифры
exp_year * обязательный
 integer Год окончания срока действия карты. Последние 2 цифры
token_provider * обязательный
 string Провайдер токена. Возможные значения или null.
token * обязательный
 string Токен карты в системе eComCharge
holder * обязательный
 string Имя владельца карты: только латинские буквы, цифры, пробелы, тире.
recommendation * обязательный
 integer Рекомендация Masterpass (выполнение не обязательно):
0 - Рекомендации отсутствуют;
1 - Выполнить проверку CVC2;
2 - Выполнить проверку 3DS;
3 - Выполнить проверку 3DS и CVC2 или CVC2;
4 - Выполнить проверку 3DS и CVC2.
required * обязательный
 integer Требования Masterpass (выполнение обязательно):
0 - Требования отсутствуют;
1 - Выполнить проверку CVC2;
2 - Выполнить проверку 3DS;
3 - Выполнить проверку 3DS и CVC2 или CVC2;
4 - Выполнить проверку 3DS и CVC2.
Пример успешного ответа 
{
"credit_card": {
    "holder": "JOHN DOE",
    "stamp": "80b274398e413d7bddd4d7df8c9b8aa1f9b0a9233bfb7b9cb6de16d06ea31144",
    "brand": "visa",
    "last_4": "0019",
    "first_1": "4",
    "bin": "400555",
    "issuer_country": null,
    "issuer_name": null,
    "product": null,
    "exp_month": 10,
    "exp_year": 2026,
    "token_provider": null,
    "token": "4d9e681b-498f-4f68-a4cd-89018a381c70"
},
"recommendation": 0,
"required": 0
}

При ошибке система вернет ответ со следующими параметрами:

Параметр Тип Описание
status * обязательный
 string Статус запроса.
error_code * обязательный
 integer Код ошибки.
error * обязательный
 string Сообщение об ошибке.
Коды ошибок

В случае возникновения ошибок при получении карты из Masterpass воспользуйтесь пояснением кодов для параметра error_code.

Код ошибки Описание Пояснение описания
0 Успешное завершение вызова.
1 The service is not available for this card/user Карта находится в черном списке. Рекомендуется обновить список карт вызовом GetCards или позволить пользователю сохранить новую карту
2 Card is not activated Реквизиты карты в этом статусе не могут быть получены в GetCard. Рекомендуется обновить список карт вызовом GetCards или позволить пользователю сохранить новую карту
3 The card was not found by the token Карта с таким токеном не найдена. Рекомендуется обновить список карт вызовом GetCards или позволить пользователю сохранить новую карту
5 Customer with this phone number not found Пользователь с таким телефоном не найден.
12 This transaction is marked as fraud Операция отклонена системой фрод-мониторинга.
15 Merchant with such a name and password not found Обязательное поле Merchant не передано в запросе или мерчант с таким названием не найден.
16 Session for the card not found and it is not recurrent Передана не существующая сессия или срок действия сессии истек.
17 Amount <= 0 Значение параметра Amount должно быть строго больше 0
19 Wrong params Обязательный параметр Amount не передан в запросе, пустое поле или содержит что-либо кроме цифр.
44 API_NOT_ALLOWED Сертификат не найден или истек срок действия сертификата или ошибка подписи.
Пример неуспешного ответа 
{
"status":"failed",
"error":"Masterpass error response",
"error_code":16
}

Получение карты из Masterpass по токену eComCharge

Прежде чем начать

Перед получением информации о карте из Masterpass должна быть открыта сессия пользователя.

Метод используется для каждой транзакции с участием пользователя, чтобы получить актуальные сведения по карте, которая была ранее токенизирована в eComCharge.

Для рекуррентных платежей по токену метод вызывается автоматически eComCharge.

Запрос

Отправьте POST запрос на https://processing.ecomcharge.com/masterpass/get_saved_card со следующими параметрами:

Параметр Тип Описание
session * условно опциональный
 string Идентификатор сессии пользователя в Masterpass. Обязательный для нерекуррентных карт.
credit_card_token * обязательный
 string Токен eComCharge (из ответа на запрос токенизации карты)
amount * обязательный
 integer Cумма в минимальных денежных единицах. Например, $32.45 должна быть отправлена как 3245.
currency * обязательный
 string Валюта в ISO-4217 формате, например USD.
test boolean Операция будет тестовой, если значение true. Иначе, false.
Пример запроса 
{
  "session": "5cb1ed91-8755-4a9c-89a0-c69899b36f6f",
  "credit_card_token": "639c0b58-118e-44f6-ad8c-623592710ba",
  "amount": 100,
  "currency": "USD",
  "test": true
}
Ответ
Параметр Тип Описание
credit_card object Информация о карте.
stamp * обязательный
 string Хеш карты.
brand * обязательный
 string Название бренда карты.
last_4 * обязательный
 integer Последние 4 цифры номера карты.
first_1 * обязательный
 integer Первая цифра номера карты.
bin * обязательный
 integer BIN-номер карты.
issuer_country * обязательный
 string Страна выпуска карты.
issuer_name * обязательный
 string Название эмитента карты.
product * обязательный
 string Название карточного продукта.
exp_month * обязательный
 integer Месяц окончания срока действия карты. 2 цифры.
exp_year * обязательный
 integer Год окончания срока действия карты. Последние 2 цифры.
token_provider * обязательный
 string Провайдер токена.
token * обязательный
 string Токен карты в системе eComCharge.
holder * обязательный
 string Имя владельца карты: только латинские буквы, цифры, пробелы, тире.
recommendation * обязательный
 integer Рекомендация Masterpass (выполнение не обязательно). Возможные значения:
0 - Рекомендации отсутствуют;
1 - Выполнить проверку CVC2;
2 - Выполнить проверку 3DS;
3 - Выполнить проверку 3DS и CVC2 или CVC2;
4 - Выполнить проверку 3DS и CVC2.
required * обязательный
 integer Требования Masterpass (выполнение обязательно). Возможные значения:
0 - Требования отсутствуют;
1 - Выполнить проверку CVC2;
2 - Выполнить проверку 3DS;
3 - Выполнить проверку 3DS и CVC2 или CVC2;
4 - Выполнить проверку 3DS и CVC2.
Пример успешного ответа 
{
  "credit_card": {
    "holder": "John Doe",
    "stamp": "b3839d334ba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
    "brand": "visa",
    "last_4": "0000",
    "first_1": "4",
    "bin": "420000",
    "issuer_country": null,
    "issuer_name": null,
    "product": null,
    "exp_month": 5,
    "exp_year": 2026,
    "token_provider": null,
    "token": "639c0b58-118e-44f6-ad8c-623592710ba5"
  },
  "recommendation": 0,
  "required": 0
}
Пример неуспешного ответа 
{
  "status": "failed",
  "error": "Params validation error",
  "message": "No credit card found"
}

Совершение платежа картой из Masterpass

Прежде чем начать

Чтобы совершить платеж по карте, привязанной к Masterpass, необходимо предварительно запросить данные карты из Masterpass и с полученным токеном eComCharge провести оплату.

Если платеж рекуррентный, то открывать пользовательскую сессию не надо.

В текущий запрос на оплату добавляется секция Masterpass с указанием значения session.

Запрос

Для совершения платежа картой из Masterpass отправьте POST запрос на https://processing.ecomcharge.com/transactions/payments со следующими дополнительными параметрами в секции request.additional_data:

Параметр Тип Описание
additional_data object Секция, содержащая дополнительную информацию о платеже.
masterpass object Секция для работы с сервисом Masterpass.
params object Секция для параметров Masterpass.
session * обязательный
 string ID пользовательской сессии.
Пример запроса 
{
  "request": {
    "amount": 100,
    "currency": "USD",
    "description": "www",
    "tracking_id": "masterpass_test_by_token",
    "billing_address": {
      "first_name": "John",
      "last_name": "Doe",
      "country": "US",
      "city": "Denver",
      "state": "CO",
      "zip": "96002",
      "address": "1st Street"
    },
    "credit_card": {
      "token": "03d65020-07c4-4987-b96a-72ec9727ac1f",
      "verification_value": 123
    },
    "additional_data": {
      "masterpass": {
        "params": {
          "session": "037ead94-b11c-4dff-ad73-9e8a414ceb80"
        }
      }
    },
    "customer": {
      "ip": "127.0.0.1",
      "email": "email@example.com",
      "birth_date": "1998-01-31"
    },
    "test": true
  }
}
Ответ
Пример ответа 
{
  "transaction": {
    "uid": "9707-af6046bd28",
    "status": "failed",
    "amount": 100,
    "currency": "USD",
    "description": "www",
    "type": "payment",
    "payment_method_type": "credit_card",
    "tracking_id": "masterpass_test_by_token",
    "message": "Payment was declined",
    "test": true,
    "created_at": "2021-02-12T12:19:15.314Z",
    "updated_at": "2021-02-12T12:19:20.541Z",
    "paid_at": "2021-02-12T12:19:20.520Z",
    "expired_at": null,
    "closed_at": null,
    "settled_at": null,
    "manually_corrected_at": null,
    "language": "en",
    "redirect_url": "https://processing.ecomcharge.com/process/9707-af6046bd28",
    "credit_card": {
      "holder": "JOHN DOE",
      "stamp": "80b274398e413d7bddd4d7df8c9b8aa1f9b0a9233bfb7b9cb6de16d06ea31144",
      "brand": "visa",
      "last_4": "0019",
      "first_1": "4",
      "bin": "400555",
      "issuer_country": null,
      "issuer_name": null,
      "product": null,
      "exp_month": 10,
      "exp_year": 2026,
      "token_provider": null,
      "token": "03d65020-07c4-4987-b96a-72ec9727ac1f"
    },
    "receipt_url": "https://gateway.ecomcharge.com/customer/transactions/9707-af6046bd28/86e2642265417ab4f4d9102f3092b29dd7ace5a0a925727f9920f0b165e40111",
    "id": "9707-af6046bd28",
    "additional_data": {
      "masterpass": {
        "params": {
          "session": "037ead94-b11c-4dff-ad73-9e8a414ceb80"
        },
        "result": {
          "status": "successful",
          "message": "Postback successfully finished."
        }
      }
    },       
    "payment": {
      "auth_code": "654321",
      "bank_code": "10",
      "rrn": "999",
      "ref_id": "777888",
      "message": "Payment was declined",
      "amount": 100,
      "currency": "USD",
      "billing_descriptor": "test descriptor",
      "gateway_id": 288,
      "status": "failed"
    },
    "avs_cvc_verification": {
      "avs_verification": {
        "result_code": null
      },
      "cvc_verification": {
        "result_code": null
      }
    },
    "customer": {
      "ip": "127.0.0.1",
      "email": "email@example.com",
      "device_id": null,
      "birth_date": "1998-01-31"
    },
    "billing_address": {
      "first_name": "John",
      "last_name": "Doe",
      "address": "1st Street",
      "country": "US",
      "city": "Denver",
      "zip": "96002",
      "state": "CO",
      "phone": null
    }
  }
}
Коды ошибок

В случае возникновения ошибки при совершении платежа картой из Masterpass, чтобы понять причину ошибки, воспользуйтесь пояснением кодов для параметра error_code.

Код ошибки Описание Пояснение описания
0 Успешное завершение вызова.
1 The service is not available for this card/user Карта находится в черном списке. Рекомендуется обновить список карт вызовом GetCards или позволить пользователю сохранить новую карту.
2 Card is not activated Реквизиты карты в этом статусе не могут быть получены в GetCard. Рекомендуется обновить список карт вызовом GetCards или позволить пользователю сохранить новую карту
3 The card was not found by the token Карта с таким токеном не найдена. Рекомендуется обновить список карт вызовом GetCards или позволить пользователю сохранить новую карту
5 Customer with this phone number not found Пользователь с таким телефоном не найден.
12 This transaction is marked as fraud Операция отклонена системой фрод-мониторинга.
15 Merchant with such a name and password not found Обязательное поле Merchant не передано в запросе или мерчант с таким названием не найден.
16 Session for the card not found and it is not recurrent Передана не существующая сессия или срок действия сессии истек.
17 Amount <= 0 Значение параметра Amount должно быть строго больше 0
19 Wrong params Обязательный параметр Amount не передан в запросе, пустое поле или содержит что-либо кроме цифр. Запрос был отправлен с неверным или неполным набором параметров. Не переданы обязательные параметры или Amount= 0
44 API_NOT_ALLOWED Сертификат не найден или истек срок действия сертификата или ошибка подписи.

Удаление карты из Masterpass

Info

Перед удалением карты из Masterpass должен быть получен список карт из Masterpass.

Запрос

Для удаления карты из Masterpass отправьте POST запрос на https://processing.ecomcharge.com/masterpass/delete_card со следующими параметрами:

Параметр Тип Описание
token * обязательный
 string Токен Masterpass (из запроса на получение списка карт)
session * обязательный
 string Идентификатор сессии пользователя в Masterpass
test boolean true или false. Операция будет тестовой, если значение true
Пример запроса 
  {
      "session": "d1d88fb8-1bf1-4c82-9c8b-00c9d887d821",
      "token": "07be2846-aa35-480c-b1f8-a01d8674fadb",
      "test": true
  }
Ответ
Параметр Тип Описание
status string Результат удаления карты в Masterpass. Возможные значения:successful, failed
error_code integer Код ошибки.
error string Текст ошибки из Masterpass.
Коды ошибок

В случае возникновения ошибки при удалении карты из системы Masterpass, чтобы понять причину ошибки, воспользуйтесь пояснением кодов для параметра error_code.

Код ошибки Описание Пояснение описания
0 Успешное завершение вызова.
1 Access denied У мерчанта нет права вызова этого метода.
5 Card not found Карта с таким токеном не найдена. Например, она была удалена из Masterpass. Рекомендуется обновить список карт вызовом GetCards или позволить пользователю сохранить новую карту
8 No user was found by the passed session Передана не существующая сессия или срок действия сессии истек. Необходимо заново активировать сессию
20 Internal error Внутренняя системная ошибка, требуется дополнительная проверка командой Masterpass
30 Invalid Token card for this request Обязательный параметр Token не передан, передано пустое поле или состоящее из пробелов.
35 Wrong params Запрос был отправлен с неверным или неполным набором параметров.
Пример успешного ответа 
{
  "status": "successful"
}
Пример неуспешного ответа 
{
  "status": "failed",
  "error": "Masterpass error response",
  "error_code": 8
}