CARDS-LIFECYCLE API

Последнее обновление: 09-09-2021 |

Интерфейс предназначен для управления жизненным циклом карты с помощью сервиса Cards-lifecycle.

Взаимодействие между сервером Cards-lifecycle и сервером партнера происходит по защищенному сетевому протоколу (HTTPS).

Данные при запросах на сервер Cards-lifecycle передаются в формате параметров HTTP-запроса в кодировке UTF-8. В ответ данные возвращаются в формате JSON.

Авторизация

Поддерживаются только HTTPS-запросы. HTTP-запросы по нешифрованному каналу не поддерживаются.

Схема аутентификации - Bearer.

В HTTP-заголовке запроса Authorization передаётся bearer-токен.

--header "Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******"

Bearer-токен выдается партнеру при интеграции.

URL для вызовов API

https://api-test.qiwi.com - testing окружение
https://api.qiwi.com - production окружение

Взаимодействие через API

Создать заказ на выпуск карты

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

Запрос → PUT

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/orders/{orderId}

Параметры запроса на выпуск виртуальной карты

Пример запроса на выпуск виртуальной карты

curl https://api-test.qiwi.com/partner/openapi-cards-lifecycle/v1/products/best-partner/orders/1ab
-X PUT
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
-d '{
"clientId": "1",
"accountId": "Account1"
"cardType": "VIRTUAL",
"personPhone": "9515485777"
}'

Параметр	Описание	Тип	REGEX	Пример	Обяз.
productId	Идентификатор продукта, в рамках которого происходит выпуск карты: выдается партнеру при интеграции	String	`^[A-Za-z0-9-]{1,100}$`	Prd-123-DEF-456	+
orderId	Уникальный идентификатор заказа карты в системе партнера	String	`^[A-Za-z0-9-]{1,100}$`	Abc-123-DEF-456	+
clientId	Уникальный идентификатор клиента в системе партнера: партнер передает id клиента, созданного по API Clients, для которого выпускается карта	String	`^[A-Za-z0-9-]{1,100}$`	Cnt-123-DEF-456	+
accountId	Идентификатор счета в системе партнера: партнер передает id конкретного счета клиента, созданного по API Clients, к которому привязывается карта	String	`^[A-Za-z0-9-]{1,100}$`	Acc-123-DEF-456	+
cardType	Тип карты	String		`VIRTUAL`	+
personPhone	Телефон пользователя, привязывается к карте. Используется для 3DS авторизации. Только цифры (от 11 до 16) с указанием кода страны.	String	`^\d{11,16}$`	`79261234567`	+

Ответ ←

Пример ответа

{
    "orderId": "1ab",
    "productId": "best-partner",
    "clientId": "1",
    "orderStatus": "DELIVERED",
    "cardType": "VIRTUAL",
    "cardInsensitiveInfo": {
        "cardTokenId": "100000000001",
        "cardType": "VIRTUAL",
        "maskedPan": "4153****4697",
        "expiryDate": "04/2024",
        "status": "ACTIVE"
    },
    "personPhone": "9515485777",
    "accountId": "Account1"
}

Параметр	Тип	Описание
orderId	String	Уникальный идентификатор заказа карты в системе партнера
productId	String	Идентификатор продукта
clientId	String	Уникальный идентификатор клиента в системе партнера
orderStatus	String	Cтатус заказа
cardType	String	Тип карты
cardInsensitiveInfo		Нечувствительные данные карты
cardTokenId	String	Уникальный идентификатор (токен) карты
maskedPan	String	Маскированный PAN. Пример: `4153****4697`
expiryDate	String	Дата окончания действия карты. Пример: `04/2024`
status	String	Статус карты. Для виртуальной карты возвращается `ACTIVE`.
personPhone	String	Телефон пользователя, используется для 3DS авторизации
accountId	String	Идентификатор счета карты

Параметры запроса на выпуск физической карты

Пример запроса на выпуск физической карты

curl https://api-test.qiwi.com/partner/openapi-cards-lifecycle/v1/products/best-partner/orders/1ab
-X PUT
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
-d '{
  "clientId": "1",
  "accountId": "Account1",
  "personPhone": "9515485777",
  "cardType": "PHYSICAL",
  "design": {
    "code": "D1"
  },
  "cardHolder": {
      "embossedName" : "IVAN LOMONOSOV",
      "firstName" : "Иван",
      "lastName" : "Ломоносов",
      "middleName" : "Васильевич"
    },
  "delivery": {
    "methodId": "33",
    "address": {
      "postCode": "117525",
      "countryCode": "RU",
      "regionName": "Moscow",
      "cityName": "Moscow",
      "address": "Yuzhnoe Chertanovo",
      "address2": "ul.Bolshaya Dvoryanskaya 140A 43",
      "countryPhoneCode": "+7",
      "phone": "9515485777"
    }
  }
}'

Параметр	Описание	Тип	REGEX	Пример	Обяз.
productId	Идентификатор продукта, в рамках которого происходит выпуск карты: выдается партнеру при интеграции	String	`^[A-Za-z0-9-]{1,100}$`	Prd-123-DEF-456	+
orderId	Уникальный идентификатор заказа карты в системе партнера	String	`^[A-Za-z0-9-]{1,100}$`	Abc-123-DEF-456	+
clientId	Уникальный идентификатор клиента в системе партнера: партнер передает id клиента, созданного по API Clients, для которого выпускается карта	String	`^[A-Za-z0-9-]{1,100}$`	Cnt-123-DEF-456	+
accountId	Идентификатор счета в системе партнера: партнер передает id конкретного счета клиента, созданного по API Clients, к которому привязывается карта	String	`^[A-Za-z0-9-]{1,100}$`	Acc-123-DEF-456	+
cardType	Тип карты	String		`PHYSICAL`	+
personPhone	Телефон пользователя, используется для 3DS авторизации. Только цифры (от 11 до 16) с указанием кода страны.	String	`^\d{11,16}$`	`79261234567`	+
design	Информация о дизайне карты	String			+
code	Код дизайна карты	String			+
cardHolder	Информация о владельце карты. Обязательно для персонифицированных карт. Необязательно - для анонимных.				-
embossedName	Имя владельца карты: отображается на карте. Обязательно, если заполняется cardHolder	String			+
firstName	Имя владельца карты. Используется для доставки карты. Обязательно, если заполняется cardHolder	String			+
lastName	Фамилия владельца карты. Используется для доставки карты. Обязательно, если заполняется cardHolder	String			+
middleName	Отчество владельца карты или доп. имя. Используется для доставки карты. Обязательно, если заполняется cardHolder	String			+
delivery	Информация о доставке				+
methodId	Способ доставки	String			+
address	Информация об адресе				+
postCode	Почтовый индекс	String			+
countryCode	Код страны в соответствии со стандартом ISO 3166-1 (alpha-2). Строго 2 символа.	String			+
regionName	Регион. Не допускается использование символа `#`.	String			-
cityName	Город. Не допускается использование символа `#`.	String			+
address	Адрес получателя. Не допускается использование символа `#`.	String			+
address2	Дополнительный адрес получателя или вторая строка адреса. Не допускается использование символа `#`. Важно! Поле `address2` сейчас не передается в службу доставки. Необходимо использовать поле `address`.	String			-
countryPhoneCode	Телефонный код страны. Может состоять не более чем из 10 цифр. Примеры: `+7`, `44`.	String			-
phone	Номер телефона получателя. Используется для связи курьера с получателем.	String			+

Ответ ←

Пример ответа

{
    "orderId": "1ab",
    "productId": "best-partner",
    "clientId": "1",
    "accountId": "Account1",
    "orderStatus": "ORDERED",
    "cardHolder": {
        "embossedName": "IVAN LOMONOSOV",
        "firstName": "Иван",
        "lastName": "Ломоносов",
        "middleName": "Васильевич"
    },
    "design": {
        "code": "D1"
    },
    "delivery": {
        "methodId": "33",
        "address": {
            "postCode": "117525",
            "countryCode": "RU",
            "regionName": "Moscow",
            "cityName": "Moscow",
            "address": "Yuzhnoe Chertanovo",
            "address2": "ul.Bolshaya Dvoryanskaya 140A 43",
            "countryPhoneCode": "+7",
            "phone": "9515485777"
        }
    },
    "cardType": "PHYSICAL",
    "cardInsensitiveInfo": {
        "cardTokenId": "",
        "cardType": "PHYSICAL",
        "maskedPan": "",
        "expiryDate": "08/2019",
        "embossedName": "M.LOMONOSOV",
        "status": "IN_PROGRESS_OF_CREATION"
    }
}

Параметр	Тип	Описание
orderId	String	Уникальный идентификатор заказа карты в системе партнера
productId	String	Идентификатор продукта
clientId	String	Уникальный идентификатор клиента в системе партнера
accountId	String	Идентификатор счета
orderStatus	String	Cтатус заказа
cardType	String	Тип карты
cardHolder	String	Информация о владельце карты
embossedName	String	Имя владельца карты (отображается на карте)
firstName	String	Имя владельца карты
lastName	String	Фамилия владельца карты
middleName	String	Отчество владельца карты (или доп. имя)
design		Информация о дизайне карты
code	String	Код дизайна карты
delivery		Информация о доставке
methodId	String	Способ доставки
address		Информация об адресе доставки
postCode	String	Почтовый индекс
countryCode	String	Код страны
regionName	String	Регион
cityName	String	Город
address	String	Адрес получателя
address2	String	Дополнительный адрес получателя
countryPhoneCode	String	Tелефонный код страны
phone	String	Номер телефона получателя
cardType	String	Тип карты

Сменить номер телефона

В запросе на выпуск карты передается номер телефона клиента, который используется для 3DS авторизации при покупке с карты. Чтобы клиент мог успешно сделать покупку, в сервисе Cards-lifecycle должен находиться актуальный номер телефона клиента, привязанный к его карте. Метод позволяет сменить номер телефона на актуальный.

Запрос → PUT

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/cards/{cardTokenId}/phone

Параметры запроса

Пример запроса

curl https://api-test.qiwi.com/partner/openapi-cards-lifecycle/v1/products/best-partner/cards/100074269512/phone
-X PUT
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
-d '{
  "personPhone" : "9515485777"
}'

Описание параметров запроса см. в разделе "Получить информацию по карте".

Ответ ←

Пример ответа

{
  "personPhone" : "9515485777"
}

Параметр	Тип	Описание
personPhone	String	Номер телефона получателя, привязанный к карте. Используется для 3DS авторизации при покупке с использованием карты.

Получить номер телефона, привязанного к карте

В запросе на выпуск карты передается номер телефона клиента, который используется для 3DS авторизации при покупке с карты. Чтобы клиент мог успешно сделать покупку, в сервисе Cards-lifecycle должен находиться актуальный номер телефона клиента, привязанный к его карте. Метод позволяет получить номер телефона, привязанный к карте на момент запроса.

Запрос → GET

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/cards/{cardTokenId}/phone

Параметры запроса

Пример запроса

curl https://api-test.qiwi.com/partner/openapi-cards-lifecycle/v1/products/best-partner/cards/100074269512/phone
-X GET
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'

Описание параметров запроса см. в разделе "Получение информации по карте".

Ответ ←

Пример ответа

{
  "personPhone" : "9515485777"
}

Описание параметров ответа см. в данном разделе.

Получить информацию о всех заказах клиента на выпуск карты

Запрос → GET

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/orders?clientId={clientId}

Параметры запроса

Пример запроса

curl https://api-test.qiwi.com/partner/openapi-cards-lifecycle/v1/products/best-partner/orders?clientId=1
-X GET
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'

Параметр	Описание	Тип	REGEX	Пример	Обяз.
productId	Идентификатор продукта: выдается партнеру при интеграции	String	`^[A-Za-z0-9-]{1,100}$`	Prd-123-DEF-456	+
clientId	Уникальный идентификатор клиента в системе партнера: партнер передает id клиента, для которого были выпущены карты согласно данному разделу	String	`^[A-Za-z0-9-]{1,100}$`	Cnt-123-DEF-456	+

Ответ ←

Пример ответа

[
    {
        "orderId": "1ab",
        "productId": "best-partner",
        "clientId": "1",
        "orderStatus": "DELIVERED",
        "cardType": "VIRTUAL",
        "cardInsensitiveInfo": {
            "cardTokenId": "100000000001",
            "cardType": "VIRTUAL",
            "maskedPan": "4153****4697",
            "expiryDate": "04/2024",
            "status": "ACTIVE"
        },
        "personPhone": "9515485777",
        "accountId": "Account1"
    }, 
    {
        "orderId": "1ab",
        "productId": "best-partner",
        "clientId": "1",
        "accountId": "Account1",
        "orderStatus": "ORDERED",
        "cardHolder": {
            "embossedName": "IVAN LOMONOSOV",
            "firstName": "Иван",
            "lastName": "Ломоносов",
            "middleName": "Васильевич"
        },
        "design": {
            "code": "D1"
        },
        "delivery": {
            "methodId": "33",
            "address": {
                "postCode": "117525",
                "countryCode": "RU",
                "regionName": "Moscow",
                "cityName": "Moscow",
                "address": "Yuzhnoe Chertanovo",
                "address2": "ul.Bolshaya Dvoryanskaya 140A 43",
                "countryPhoneCode": "+7",
                "phone": "9515485777"
            }
        },
        "cardType": "PHYSICAL",
        "cardInsensitiveInfo": {
            "cardTokenId": "",
            "cardType": "PHYSICAL",
            "maskedPan": "",
            "expiryDate": "08/2019",
            "embossedName": "M.LOMONOSOV",
            "status": "IN_PROGRESS_OF_CREATION"
        }
    }   
]

В ответе возвращается массив объектов. Описание формата объекта см. в ответе на запрос выпуска виртуальной карты и ответе на запрос выпуска физической карты.

Получить информацию о заказе на выпуск карты

Запрос → GET

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/orders/{orderId}

Параметры запроса

Пример запроса

curl https://api-test.qiwi.com/partner/openapi-cards-lifecycle/v1/products/best-partner/orders/1ab
-X GET
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'

Параметр	Описание	Тип	REGEX	Пример	Обяз.
productId	Идентификатор продукта: выдается партнеру при интеграции	String	`^[A-Za-z0-9-]{1,100}$`	Prd-123-DEF-456	+
orderId	Уникальный идентификатор заказа карты в системе партнера: партнер передает id заказа, в рамках которого была выпущена карта согласно данному разделу	String	`^[A-Za-z0-9-]{1,100}$`	Abc-123-DEF-456	+

Ответ ←

Пример ответа для виртуальной карты

    {
        "orderId": "1ab",
        "productId": "best-partner",
        "clientId": "1",
        "orderStatus": "DELIVERED",
        "cardType": "VIRTUAL",
        "cardInsensitiveInfo": {
            "cardTokenId": "100000000001",
            "cardType": "VIRTUAL",
            "maskedPan": "4153****8641",
            "expiryDate": "04/2024",
            "status": "ACTIVE"
        },
        "personPhone": "9515485777",
        "accountId": "Account1"
    }

Пример ответа для физической карты

{
    "orderId": "1ab",
    "productId": "best-partner",
    "clientId": "1",
    "accountId": "Account1",
    "orderStatus": "ORDERED",
    "cardHolder": {
        "embossedName": "IVAN LOMONOSOV",
        "firstName": "Иван",
        "lastName": "Ломоносов",
        "middleName": "Васильевич"
    },
    "design": {
        "code": "D42"
    },
    "delivery": {
        "methodId": "33",
        "address": {
            "postCode": "117525",
            "countryCode": "RU",
            "regionName": "Moscow",
            "cityName": "Moscow",
            "address": "Yuzhnoe Chertanovo",
            "address2": "ul.Bolshaya Dvoryanskaya 140A 43",
            "countryPhoneCode": "+7",
            "phone": "9515485777"
        }
    },
    "cardType": "PHYSICAL",
    "cardInsensitiveInfo": {
        "cardTokenId": "",
        "cardType": "PHYSICAL",
        "maskedPan": "",
        "expiryDate": "08/2019",
        "embossedName": "IVAN LOMONOSOV",
        "status": "IN_PROGRESS_OF_CREATION"
    }
}

Описание параметров ответа см. в ответе на запрос выпуска виртуальной карты и ответе на запрос выпуска физической карты.

Получить информацию по всем картам клиента

Запрос → GET

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/client/{clientId}/cards

Параметры запроса

Пример запроса

curl https://api-test.qiwi.com/partner/openapi-cards-lifecycle/v1/products/best-partner/client/1/cards
-X GET
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'

Описание параметров запроса см. в данном разделе.

Ответ ←

Пример ответа

[
    {
        "cardTokenId": "100000000001",
        "cardType": "VIRTUAL",
        "maskedPan": "4153****6977",
        "expiryDate": "04/2024",
        "status": "ACTIVE"
    },
    {
        "cardTokenId": "",
        "cardType": "PHYSICAL",
        "maskedPan": "",
        "expiryDate": "08/2019",
        "embossedName": "IVAN LOMONOSOV",
        "status": "ACTIVE"
    }
]

Поля ответа соответствуют объекту cardInsensitiveInfo, описанному в данном разделе.

Получить информацию по карте

Запрос → GET

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/cards/{cardTokenId}

Параметры запроса

Пример запроса

curl https://api-test.qiwi.com/partner/openapi-cards-lifecycle/v1/products/best-partner/cards/100000000001
-X GET
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'

Параметр	Описание	Тип	REGEX	Пример	Обяз.
productId	Идентификатор продукта: выдается партнеру при интеграции	String	`^[A-Za-z0-9-]{1,100}$`	Prd-123-DEF-456	+
cardTokenId	Уникальный идентификатор (токен) карты: партнер передает id карты, который получил в ответе на запрос выпуска карты	String	`^[A-Za-z0-9-]{1,100}$`	100000000001	+

Ответ ←

Пример ответа для виртуальной карты

{
    "cardTokenId": "100000000001",
    "cardType": "VIRTUAL",
    "maskedPan": "4153****8641",
    "expiryDate": "04/2024",
    "status": "ACTIVE"
}

Поля ответа соответствуют объекту cardInsensitiveInfo, описанному в данном разделе.

Получить PAN и CVV карты

Метод возвращает данные только для виртуальной карты.

Запрос → GET

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/cards/{cardTokenId}/sensitive?encryptionSpec={encryptionSpec}&publicKey={publicKey}

Параметры запроса

Пример запроса

curl https://api-test.qiwi.com/partner/openapi-cards-lifecycle/v1/products/best-partner/cards/100000000001/sensitive?encryptionSpec=RSA_4096_X509&publicKey=MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAhq7i9suuLXC%2Bww1YKT44NehX1TMcrYkYTSXDkGCV%2BDEKtmU686alatDsCtF0OAeyB9xLsCmAIs8UxEZz0ok5hYCG4%2BiJJ3ateOPPiroMasIcbvxCO%2B7VdWLOs5d2J%2Bhms4h507V0e7xl/iscIHPHQDHCqRNMrJ2ER0L0TOK8WOhRofc6op9ABqySp57GEW6YLm/lqnhSyslejtciFu1qmIC1weo%2BY2UrDofRAIrIxPGeH9wRfNjgp02FnXuhuxupajUKHzZmqqDTFCKlZcpwDKrqIhC4XUjudmy7tuJnAATLgiksd1tTdlZP0sJPhbeHfST8wddqGfyDqmTyaQT8Hqio3zLe63PhFZ8siHyT1AwcvYsCIuFOGuY29Nu3XowKTjnNcTOym4odrot5PRHKOgIVVjV/CDHHsgFlIRxAEaNAjCv7T2c98OgI7ZVHt3mfe8S0iQFRUpesl0bmSM8KKJnfvfVljVnzv8juDVnKNWuAIKpg7%2BNNDAqhuofozeTg/SBpltPAq5lXW52CqWjS7W0kkCq1lDMGzIShOPptnJ9bnhuggWaKb%2B/Mh07cxmZebuwFclWbd%2BjLJMMLDDf0G3tl8pPr33O4Y/YwyJ54YBTjzl%2BB0O4OF1o03T1w%2BaKkvteftArFTLvgKZQo8DO93d6VKhcpMYvRhYuo3nwy0ssCAwEAAQ%3D%3D
-X GET
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'

Параметр	Описание	Тип	REGEX	Пример	Обяз.
productId	Идентификатор продукта: выдается партнеру при интеграции	String	`^[A-Za-z0-9-]{1,100}$`	Prd-123-DEF-456	+
cardTokenId	Уникальный идентификатор (токен) карты: партнер передает id карты, который получил в ответе на запрос выпуска карты	String	`^[A-Za-z0-9-]{1,100}$`	100000000001	+
encryptionSpec	Алгоритм шифрования. Возможное значение:`RSA_4096_X509`.	String		См. пример запроса	+
publicKey	RSA X509 public key длиной 4096 бит, закодированный в base64 формате. Достаточно один раз выпустить приватный и публичный ключи и передавать один и тот же публичный ключ в каждом новом запросе. Свой публичный ключ выпускается и передается для каждого отдельного клиента: для мобильного приложения, для web и т.д.	String		См. пример запроса	+

Ответ ←

Пример ответа

{
    "encryptedPan": "A5NKL6tKtx+/xjbuQMgHpWhWLqHZjDLO80BsSv5I8apcKKpSr2n8X9X3EiznpPUtM9f1SmcjEMYMqouqQ/i7P1PTw/a+3nAFyQFDGh8B0mqdlwg9K/FiRgqPb31o7CRou5BK36VwToyZ936y1XKjHcD8dHoNYvsKtU2e2HJMfhaZBac6Lr/bkPsXNgOBhboMgsert1Z+3RUuJVIqMn8XwyxiymCnIwmGOXqzjjmVBhGgwqf+rYdVFhCFG8OfdktwxSssKMak7BuFfKjdWJdxeO6svhh/opgJ2ag70T1kEn7ryppjC+/fGYrBzR1g24qU2oJ5Nh2djjRB1W3rYWCzywNFv72yhQOpb5wMNzICg4OXvyJgoBHe1wONmYCgwG9mcn44gnOXIWoeF0uhx4y9qCh28re5J5rmBjEWG37A7eEOZpxQww1j2cH9ZBOLt36+wsUjMoCLzZV0YFi9m8wVMoW54WRM0SCKJ/UsX28uS5A5GXAhGYf/bbq+ysio65FIw7qGL3lmOrZPruUXgS0S6jfO0kla2iqprz5En/FucmeAxHDHi8KRtoos4ZdGDCCFqzCTvpPa/yjg1PrtrO2GEOlH1H6JmI85xUNWdoWQKCJW+ep8OpftVLEt8ozlqx9GREMlxa6+cuWTnYXg0OF4DOAji1FxPhkuJwuak9iRNd4=",
    "encryptedCvv": "f5mhzunv8C71s96oAbjpXZwvvPaGkK3hskDogxFbK8gDd2hpgvBTjqPlUgGQqe6EJCWzDAAM3nXrDUfFFA44Vtcg+sGN05yn/nufkDjt0bxryBrFy5Y4pnbLyG0XtQX5YdWtzBaVvH5+rcHTv8EyrBi00Rs8qaIHrCIo1YGr3IWPJ6Mr/PKu1xfpeKtBOuAJEX/nBL94fK8Rx+ZtFZGN7bu22IFdHLQT0D7H8FkGhN9ejTLlb8pFWoos5+Hze3ipp8y1jjgAK5hM6NzWMPYzHBcAJXXd/w8TfT21EHnQDZCPJJ1jEzMLjz53s19lrv5tCXylCEnWaS6KvqJgmTNgZfF1E0Bx2XdlOK3H1GJwumTB7r8kYApamy1sObIBwqvLSKK8SWeUh8Zsg/PiJqkgcd+ixrazTob2wQ7mP+ylwggkc4t5HRoj7owIve8m38WY3uTZjPwSI+1jX+Ju6xukgtiY9VJ9R+5Xr6YxYu+F2MIYOKHGRPb4kHwrT08l/eYRS4mNtCXa+B9ddk3P6JRe6z7geMClmkxPq1rY32b6k0TJP7BIb/+fiFUfWXAbOl9tDTOzkMWYAS/OLnJYit599rLO79FLmxeuJyVyfrIH35mRwTnxr3zGla1UrIK4HDeJgVgcGXg+/iCeO3XCKyyXSBDJRJtuHzLkML7m7pJK7Y4="
}

Параметр	Тип	Описание
encryptedPan	String	шифрованный PAN карты (RSA)
encryptedCvv	String	шифрованный CVV-код (RSA)

Получить шифрованные данные при токенизации карты в ApplePay

Запрос → POST

Пример запроса

curl https://api-test.qiwi.com/partner/openapi-cards-lifecycle/v1/products/best-partner/cards/112345678910/bind-apple-pay \
	-X POST \
	-H 'Content-Type: application/json;charset=UTF-8' \
	-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******' \
	-H 'User-Agent-Origin: ios' \
	-d '{ \
	"nonce": "9c023092", \
	"nonceSignature" : \ "4082f883ae62d0700c283e225ee9d286713ef74456ba1f07376cf17d71bf0be013f926d486619394060ced56030f41f84df916eaab5504e456a8530dc9c821f6ed3e3af62b5d8f3e4a22ca2018670fee4e", \
	"publicCerts" : ["base64appleCertString"] \
	}'

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/cards/{cardTokenId}/bind-apple-pay

Параметры запроса

productId — Идентификатор продукта, в рамках которого создан клиент.
cardTokenId — Токен карты клиента.

Поля, получаемые в iOS приложении от Apple Wallet в процессе токенизации:

nonce — строка hex;
nonceSignature — строка hex;
publicCerts — список строк в формате base64.

См. шаг 4 главы "V. In-App Provisioning Flow" документации "Getting Started with Apple Pay In-App Provisioning".

Ответ

Пример ответа

	{
		"activationDataBase64" : "base64string",
		"encryptedDataBase64" : "base64string",
		"ephemeralPublicKeyBase64" : "base64string"
	}

Поля ответа соответствуют спецификации Apple (7 шаг главы "V. In-App Provisioning Flow" документации "Getting Started with Apple Pay In-App Provisioning") для дальнейшей передачи в Apple Wallet.

activationDataBase64 — зашифрованное значение OTP в формате base64;
encryptedDataBase64 — зашифрованное полезная нагрузка формате base64;
ephemeralPublicKeyBase64 — публичная часть эфемерного ключа шифрования в формате base64.

Активировать карту

Запрос → PUT

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/cards/{cardTokenId}/activationstatus

Параметры запроса

Пример запроса

curl https://api-test.qiwi.com/partner/openapi-cards-lifecycle/v1/products/best-partner/cards/asd/activationstatus
-X PUT
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
-d '
ACTIVATED_BY_AGENT
'

Описание параметров запроса см. в данном разделе.

Ответ ←

Пример ответа

ACTIVATED_BY_AGENT

Возможные значения:

ACTIVATED_BY_AGENT - карта активирована
NOT_ACTIVATED - карта не активирована

Получить статус активации карты

Запрос → GET

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/cards/{cardTokenId}/activationstatus

Параметры запроса

Пример запроса

curl https://api-test.qiwi.com/partner/openapi-cards-lifecycle/v1/products/best-partner/cards/asd/activationstatus
-X GET
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'

Описание параметров запроса см. в данном разделе.

Ответ ←

Пример ответа

ACTIVATED_BY_AGENT

Возможные значения:

ACTIVATED_BY_AGENT - карта активирована
NOT_ACTIVATED - карта не активирована

Сменить PIN карты

Запрос → PUT

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/cards/{cardTokenId}/pin

Параметры запроса

Пример запроса

curl https://api-test.qiwi.com/partner/openapi-cards-lifecycle/v1/products/best-partner/cards/100000000001/pin
-X PUT
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
-d '{
  "encryptedPin" : "hQIMA6gqMockrlJ2ARAAjFevJDZFIeOITUENZtGGimV/aPc/CH5Ezul96rlom0vadqVlhOq09LV4hW8ek3Z9LnRU6xFEAJ6O/NozuMNSIGnTEA4rxsmp6gMTVEeaLeeoX4zqBvKdUwvKN/AgQUysH8pSd2rN63Ou/Fj9CLN3Xeu/PRiYICUflXeKZYbzOKZkY7KIrLVlmx2HypzY/SPQLeLzE9sN1IQz+JhWfre10LLS9GEwgk56dWbHhUws1BO05OS+orRJd3Pcmb+6KLCQO+6sFzGoua2PuZhSu6tgtAhE6nbv0DRG3f4aUKl9t6NUDFfID28mOcTKWFYVwnih5IYRVB7KOK5SOB5TxWTWXR8d3l6RJ476jnIE3e3+iWp25Ki46qt4NYi2NHYIpslHc5kBs2oa4DvE6NG66dL0Vw1hFznX0vH9Bn0O+SCWtsPOqu+0FHLiumPUvpBwgozOVs7IcuI3Q5jfYq6fDxVl2R4Sq22WmvZbcj227WUHxYqp1BT7aIm5mM6VPIFRDV/LarVghYGG8O0gfnuC8Z+V8owkUMZWwK0/uf9wj7I1OYHrpYAVHyOOLXS0kRGsxt5Tz6aXkyMLoaFomHH+ihHsgysYwFFAO5f0HABochP6Mg70EMVxsRs2JuMNMMj5THOPOYPtH4X0fk10YvfgoWwku+AekqV2vLaPN01y/U491+HSPwENiBVPyvTnD+fXsuvZawVwECPLCMuJULjH1Nd0rqdDKxFQvyukubZ4Q4o2fNDOwGQsuJU7BGrN/PyMDx5JWw==",
  "publicKeyVersion" : "20200614"
}'

Параметр	Описание	Тип	REGEX	Пример	Обяз.
productId	Идентификатор продукта: выдается партнеру при интеграции	String	`^[A-Za-z0-9-]{1,100}$`	Prd-123-DEF-456	+
cardTokenId	Уникальный идентификатор (токен) карты: партнер передает id карты, который получил в ответе на запрос выпуска карты	String	`^[A-Za-z0-9-]{1,100}$`	100000000001	+
encryptedPin	PIN-код карты, который задал пользователь: `^\\d{4}\|$`. Передается в шифрованном виде. Шифруется ключом при помощи алгоритма OpenPGP	String		См. пример запроса	+
publicKeyVersion	Версия публичного ключа, полученная данным запросом.	String		См. пример запроса	+

Ответ ←

Пример ответа

При успешном выполнении запроса в ответе необходимо ожидать HTTP Status: 204 No Content.

Получить публичный ключ

Публичный ключ необходим для шифрования PIN-кода карты.

Запрос → GET

URL /partner/openapi-cards-lifecycle/v1/products/best-partner/encryption/publickey

Параметры запроса

Пример запроса

curl https://api-test.qiwi.com/partner/openapi-cards-lifecycle/v1/products/best-partner/encryption/publickey
-X GET
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'

Параметр	Описание	Тип	REGEX	Пример	Обяз.
productId	Идентификатор продукта: выдается партнеру при интеграции	String	`^[A-Za-z0-9-]{1,100}$`	Prd-123-DEF-456	+

Ответ ←

Пример ответа

{
    "publicKey": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\nmQINBF2l91YBEADY7stigMDgCFaOSEHo4eXbX73wWB3vGhBNC0yGGlrv7ip1IAn+\nGomTBS2aKU1/hzoSyUfHQdgcMzY5VsU6wqeTpYGh1dDluX3+9bG9fn/spYUzChHu\nRz8Jb4QgYwyj4BDX9VNYE92ZKyQ7oYx5cnp9xYxXqTw/rLL7RblTnccB8AyWjfZe\nbqyNbJZsgWPGqNl955XwTz5SXsLpMrzJAbGUslz+tLdRMJhCeGaPsajS5WuWPuxQ\nGUwbzZEkyNKYlHWca6KD2zCEROi0G0sZXSaY8VCgKOVLFUoteUNGIbBKZBCENbcB\n9myI54W9ATUOi23xELsDchGSOWFqqLanRpVa4OIYRHZtIcDYbUoSSoU1ynanZvFP\nF+ycZa2xgwyKpwc5YL1BkxmUl1mn6Wm6fbMWf7PpmOXpFkoFnZu35WkGBtWkuLX2\nd3LtPFtW7MOby7+fgMc2WawVsLpaLXpwstQhurGNTYmsod1wuvhDrmM5oK806VtX\nprTXaklD2A/EOe/ZyUvlTNewOTbBMcuOPO3K5mSIdntLACClpUSFSaUlzHl1b4sc\nJzLh5KshghImfw9tIRDQavPriF5chbp048P7ismd2t24k1ef5ynCq34GWeD1LIEc\n16UzB8YE5UhSaFCNrCg7AvTyp4xtIQqp+pqR0pMdWhHgIDmj31/1T1lMIQARAQAB\n=AVgg\n-----END PGP PUBLIC KEY BLOCK-----\n",
    "version": "20200614"
}

Параметр	Тип	Описание
publicKey	String	Ключ, с помощью которого шифруется PIN
version	String	Версия ключа, которую необходимо передавать в параметре `publicKeyVersion` запроса "Смена PIN"

Версия ключа будет меняться с определенной периодичностью: например, 1 раз в год. Также версия может измениться в случае экстренной замены ключа по требованию службы безопасности.

Блокировать карту

Запрос → PUT

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/cards/{cardTokenId}/blockedstatus

Параметры запроса

Пример запроса

curl https://api-test.qiwi.com/partner/openapi-cards-lifecycle/v1/products/best-partner/cards/100000000001/blockedstatus 
-X PUT
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
-d '
{
  "comment" : "Потерял карту",
  "blockSource" : "PARTNER_API"
}
'

Параметр	Описание	Тип	REGEX	Пример	Обяз.
productId	Идентификатор продукта: выдается партнеру при интеграции	String	`^[A-Za-z0-9-]{1,100}$`	Prd-123-DEF-456	+
comment	Комментарий к блокировке: например, причина.	String			-
blockSource	Источник блокировки: необходимо передавать `PARTNER_API`	String		PARTNER_API	+

Ответ ←

Пример ответа

{
  "comment" : "Потерял карту",
  "blockSource" : "PARTNER_API"
}

Параметр	Тип	Описание
comment	String	Комментарий
blockSource	String	Источник блокировки

Получить статус блокировки карты

Запрос → GET

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/cards/{cardTokenId}/blockedstatus

Параметры запроса

Пример запроса

curl https://api-test.qiwi.com/partner/openapi-cards-lifecycle/v1/products/best-partner/cards/100000000001/blockedstatus 
-X GET
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'

Описание параметров запроса см. в данном разделе.

Ответ ←

Пример ответа

{
  "comment" : "Потерял карту",
  "blockSource" : "PARTNER_API"
}

Описание параметров ответа см. в данном разделе.

Источник блокировки

Код	Описание
PARTNER_API	Блокировка со стороны партнера
QIWI	Блокировка со стороны QIWI

Статусы заказа на выпуск карты

Код	Описание
ORDERED	Заказ на выпуск карты оформлен
DELIVERED	Карта выпущена (для виртуальных) или доставлена (для физических)
FAILED	Ошибка, заказ не создан

Статусы карты

Код	Описание
ACTIVE	Активна
IN_PROGRESS_OF_CREATION	В процессе создания: актуально для физических
BLOCKED	Заблокирована

Типы карт

Код	Описание
VIRTUAL	Виртуальная
PHYSICAL	Физическая

Ошибки

Ниже — описание ответа на неуспешный запрос.

Ответ ←

Пример ответа

{
    "serviceName": "openapi-cards-lifecycle",
    "errorCode": "openapi.clients.client.not.found",
    "dateTime": "2020-07-23T20:13:22.290416+03:00",
    "traceId": "67477569e8bc6838"
}

Название	Описание
serviceName	Имя сервиса, который вернул ошибку
errorCode	Код ошибки. См. справочник кодов ошибок
dateTime	Дата и время формирование ответа
traceId	Параметр, необходимый для анализа логов. Его значение также всегда присутствует в заголовке ответа `X-B3-TraceId`

Справочник кодов ошибок

Код	Описание
order.bad.request.data	Параметры запроса некорректны: относится к заказу на выпуск карты
order.not.found	Заказ на выпуск карты не найден
delivery.method.not.found	Метод доставки не найден: актуально для физических карт
card.not.found	Карта не найдена
product.not.found	Продукт не найден
card.type.unsupported	Выполнение этого действия невозможно для данной карты
card.blocked	Карта заблокирована
auth.permission.denied	Ошибка авторизации
client.not.found	Клиент не найден
account.not.found	Счет не найден
card.is.not.active	Карта неактивна
identification.level.not.enough	Текущий уровень идентификации клиента является недостаточным для совершения этого действия
client.blocked	Клиент заблокирован
card.design.code.not.found	Код дизайна карты не найден: актуально для физических карт
card.pin.incorrect	Некорректный PIN
pin.decryption.error	Ошибка шифрования PIN
public.key.invalid	Невалидный публичный ключ
active.virtual.cards.count.exceeded	Превышено допустимое количество виртуальных карт
apple.pay.encryption.error	Ошибка шифрования данных для токенизации в Apple Pay: некорректный публичный сертификат

Справочник кодов внутренних ошибок

Описание всех перечисленных ошибок одинаковое: "В сервисе cards-lifecycle произошла внутренняя ошибка".

Код
openapi.cardlifecycle.internal.error
card.pin.change.internal.error
pan.is.null
card.phone.updating.error
bank.informing.internal.error
bank.card.info.internal.error
expiry.date.expected
card.token.id.expected
block.info.not.found
prc.operation.for.test.client.prohibited
card.offer.not.found
operation.for.card.not.supported
pan.length.invalid
card.status.not.activated

CARDS-LIFECYCLE API

Последнее обновление: 09-09-2021 |

Авторизация

URL для вызовов API

Взаимодействие через API

Создать заказ на выпуск карты

Запрос → PUT

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/orders/{orderId}

HEADERS

Параметры запроса на выпуск виртуальной карты

Ответ ←

Параметры запроса на выпуск физической карты

Ответ ←

Сменить номер телефона

Запрос → PUT

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/cards/{cardTokenId}/phone

HEADERS

Параметры запроса

Ответ ←

Получить номер телефона, привязанного к карте

Запрос → GET

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/cards/{cardTokenId}/phone

HEADERS

Параметры запроса

Ответ ←

Получить информацию о всех заказах клиента на выпуск карты

Запрос → GET

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/orders?clientId={clientId}

HEADERS

Параметры запроса

Ответ ←

Получить информацию о заказе на выпуск карты

Запрос → GET

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/orders/{orderId}

HEADERS

Параметры запроса

Ответ ←

Получить информацию по всем картам клиента

Запрос → GET

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/client/{clientId}/cards

HEADERS

Параметры запроса

Ответ ←

Получить информацию по карте

Запрос → GET

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/cards/{cardTokenId}

HEADERS

Параметры запроса

Ответ ←

Получить PAN и CVV карты

Запрос → GET

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/cards/{cardTokenId}/sensitive?encryptionSpec={encryptionSpec}&publicKey={publicKey}

HEADERS

Параметры запроса

Ответ ←

Получить шифрованные данные при токенизации карты в ApplePay

Запрос → POST

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/cards/{cardTokenId}/bind-apple-pay

HEADERS

Параметры запроса

Ответ

Активировать карту

Запрос → PUT

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/cards/{cardTokenId}/activationstatus

HEADERS

Параметры запроса

Ответ ←

Получить статус активации карты

Запрос → GET

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/cards/{cardTokenId}/activationstatus

HEADERS

Параметры запроса

Ответ ←

Сменить PIN карты

Запрос → PUT

URL /partner/openapi-cards-lifecycle/v1/products/{productId}/cards/{cardTokenId}/pin

HEADERS

Параметры запроса

Ответ ←

Получить публичный ключ