Поддержка 3ds второй версии была включена в январе 2021 года. Изменился протокол взаимодействия с клиентами, не пользующимися нашей платежной страницей.

purchase

Появился новый параметр в запросе tds.notificationUrl (см. пример ниже). Это аналог termUrl в 3dsV1, но теперь он называется иначе. На этот адрес придет cres. Раньше не надо было передавать termUrl, потому что его передавали вместе с Pareq на acsUrl вы сами. Теперь notificationUrl нужен на этапе формирования creq.

Теперь, при запросе purchase клиенту могут вернуться ответы со статусами:

  • SUCCEEDED, если карта не участвует в программе 3ds

  • WAITING_FOR_CONFIRMATION, если карта поддерживает 3dsV1

  • WAITING_TDS_AUTH, если карта поддерживает 3dsV2

Вместе со статусом WAITING_TDS_AUTH приходят 2 параметра: threeDSMethodURL и threeDSServerTransID. threeDSMethodURL - адрес на который нужно обратиться из браузера в скрытом iframe, подробности читайте в официальной документации.

Особенности:

  • threeDSMethodURL может быть пустым, тогда фазу с iframe надо пропустить и переходить к complete3dsAuth

  • если обращение на threeDSMethodURL с помощью iframe закончилось ошибкой, то надо переходить к complete3dsAuth

  • при обращении на threeDSMethodURL передается threeDSMethodNotificationURL (адрес колбека по завершении iframe). На тестовом слое колбек не отсылается, надо переходить к complete3dsAuth

  • Для убыстрения прохождения операций переходить к complete3dsAuth рекомендуется сразу после получения стутуса WAITING_TDS_AUTH, а поход на iframe запустить параллельно, любые race-condition хорошо разруливаются платежными системами.

complete3dsAuth

После получения статуса WAITING_TDS_AUTH нужно по адресу: /card/{siteId}/operations/{operationId}/complete3dsAuth отправить (усеченный) "слепок" браузера (смотри пример ниже)

возможны ответы со статусами:

  • SUCCEEDED, если дальнейшая проверка платежа не требуется

  • WAITING_TDS_VALIDATION, если проверка требуется

Вместе со статусом WAITING_TDS_VALIDATION приходят creq. Дальнейшая процедура аналогична 3dsV1, только вместо paReq используется creq, а вместо paRes - cres. сres придет на адрес указанный в tds.notificationUrl. Если при вызове метода complete3dsAuth в ответ пришел дополнительный параметр threeDSSessionData, то его нужно также отправлять вместе cres.

complete3dsValidate

Полученный cres надо отправить на адрес: /card/{siteId}/operations/{operationId}/complete3dsValidate После этого можно ожидать ответ SUCCEEDED

status

Если любой запрос в этой цепочке вызовов не завершился (timeout / вернулся IN_PROGRESS) , то запросить "утерянный" ответ, можно в методе проверки статуса GET /card/{siteId}/operations/status?externalId=123 Теперь этот метод может возвращать не только финальный статус операции, но и промежуточные. Полный список статусов тут

Последовательность операций

purchase

POST /card/1-1/operations/purchase HTTP/1.1
W1-Signature: QMD3bvcDUZMKT66QVTIOu1TYNQK0k0lYpUT8yj/AZibODKb2YNS6rNK58sw7PSHsfWwtKIelCtYpjz+lxdNVCB2Vya3T+uRr5n2enw6rceYtD81eUi20w9tm6vhiDwS6fmdKFWY0z96mesULIFuEERaomxRblnGoXvNE4u8v5fhfJGnMan033WrURP6z2733fwV9Vtaa8fZbzba+skxmlFkK5XPAfb44hhc0YwKzQM6XwaAfKqHAXGo4dXbUnV9OqzvW5lS93NMoRs4EM5+/v0a1MbVF/AGZ1yOsBxctfJYiSLzUmMv6htlOwUsZurfS18KADSv5GhZkYPnMfJUpsA==
Content-Type: application/json; charset=UTF-8
Host: localhost:8080
Content-Length: 695

{
  "notification" : {
    "url" : "http://localhost:65456/callback",
    "version" : 1
  },
  "externalId" : "ext#20",
  "amount" : {
    "amount" : 10.55,
    "currency" : "USD"
  },
  "payer" : {
    "paymentMethod" : {
      "entity" : {
        "pan" : "2200700010001005",
        "expMonth" : 5,
        "expYear" : 2022,
        "cvv" : "444"
      },
      "type" : "CARD"
    },
    "info" : {
      "ip" : "127.0.0.1",
      "phone" : "9001234567",
      "email" : "no-reply@flexo.systems"
    }
  },
  "merchantParameters" : {
    "param1" : "anything you want for callback"
  },
  "registerRecurring" : false,
  "tds" : {
    "notificationUrl" : "http://tds.notification.url:6789"
  }
}

ответ

HTTP/1.1 200 OK
Date: Fri, 26 Nov 2021 21:14:26 GMT
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 310

{
  "operationId" : "1-1-a-438",
  "status" : "WAITING_TDS_AUTH",
  "type" : "PURCHASE",
  "externalId" : "ext#20",
  "params" : {
    "threeDSMethodURL" : "https://callback.flexo.systems/test/testbank",
    "threeDSServerTransID" : "a3d2fc50-9944-34a6-8356-3185b8f946d5"
  },
  "actions" : {
    "required" : [ ]
  }
}

complete3dsAuth

POST /card/1-1/operations/1-1-a-474/complete3dsAuth HTTP/1.1
W1-Signature: gx1mrlkZjvv+oBlSR989IQCo4H9+nWLtwXrgThJAHBRQHvZ8rEvLrkleTnalgCuWR+CIFYUs/3Nny9OFV2By7w4W3sUBoxCkfC/xkCZaFJzLoYyTeWnc9Z+OdaFjU/9aI6Q3It8kXjrYRjeo12Gqqg5rbzWx2Twf8FoSh8PyBFtP6VSCVhQhqMXUks5GCxlbxxRAivUgeUVqmQh6bioaW4V9hy57GBeTgUaN/LKMq/oJfdud+/lwsoVOQiN0QaDoDoOSPbQv+Zwlig30HwgWpBJvrucHpDjzGPdEND+hsA9Nx6ZBe0v+TxSJFv6K4oGnGiy6gjLZCp3vHM2UjJJUVQ==
Content-Type: application/json; charset=UTF-8
Host: localhost:8080
Content-Length: 395

{
  "threeDSServerTransID" : "a3d2fc50-9944-34a6-8356-3185b8f946d5",
  "info" : {
    "ip" : "46.188.125.87",
    "userAgent" : "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:83.0)",
    "colorDepth" : "24",
    "tz" : "-180",
    "screenWidth" : "1920",
    "screenHeight" : "1080",
    "language" : "ru",
    "javaEnabled" : "false",
    "acceptHeader" : "application/json, text/plain, */*"
  }
}

ответ

HTTP/1.1 200 OK
Date: Fri, 26 Nov 2021 21:14:56 GMT
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 447

{
  "operationId" : "1-1-a-474",
  "status" : "WAITING_TDS_VALIDATION",
  "type" : "AUTH",
  "externalId" : "ext#69",
  "params" : {
    "acsUrl" : "http://localhost:9191/test/acs/3ds2",
    "creq" : "eyJ0ZXJtVXJsIjoiaHR0cDovL3Rkcy5ub3RpZmljYXRpb24udXJsOjY3ODkifQ==",
    "threeDSMethodURL" : "https://callback.flexo.systems/test/testbank",
    "threeDSServerTransID" : "a3d2fc50-9944-34a6-8356-3185b8f946d5"
  },
  "actions" : {
    "required" : [ ]
  }
}

complete3dsValidate

POST /card/1-1/operations/1-1-a-474/complete3dsValidate HTTP/1.1
W1-Signature: FNZdApR0P9g6Z/sARdxClWjzb2kyCW5/2Wd4oouZARSdjSRAh7lL4UtNnmHUNaqlBaoYjjjOCm/KNhvD4S27vva3henLLROdpid70QQCzU8LKTLqJF0hKIKsac0U47+DHwzEbNz/+gkUmJZOxdL6ZlI7EjZTF1hdsmrL0N9LT2IqQXdQrglQ0v1bw7LvsC7P7s8BQxVf+4PPmpy9Pctfp7jlJfIEONZSA4clqyjFmPIYE2cmYd/TxpFPkpI/7IYRE2NciVBmtjB3hMWWmOFnwNe7X/ROytnFtAEiqQiN0s8+0hCS1twZB2+c7Ow3YGZ8hBeubbfqa8abD2a028bKVA==
Content-Type: application/json; charset=UTF-8
Host: localhost:8080
Content-Length: 25

{
  "cres" : "verified"
}

ответ

HTTP/1.1 200 OK
Date: Fri, 26 Nov 2021 21:14:56 GMT
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 165

{
  "operationId" : "1-1-a-474",
  "status" : "SUCCEEDED",
  "type" : "AUTH",
  "externalId" : "ext#69",
  "params" : { },
  "actions" : {
    "required" : [ ]
  }
}