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}
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8/json
Параметры запроса на выпуск виртуальной карты
Пример запроса на выпуск виртуальной карты
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
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8/json
Параметры запроса
Пример запроса
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
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8/json
Параметры запроса
Пример запроса
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}
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8/json
Параметры запроса
Пример запроса
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}
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8/json
Параметры запроса
Пример запроса
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"
}
}
Описание параметров ответа см. в ответе на запрос выпуска виртуальной карты и ответе на запрос выпуска физической карты.
Получить информацию по всем картам клиента
Метод возвращает следующую информацию по всем картам клиента с указанным идентификатором:
- Уникальный идентификатор (токен) карты
- Маскированный PAN карты
- Дата окончания действия карты
- Статус карты
Запрос → GET
URL /partner/openapi-cards-lifecycle/v1/products/{productId}/client/{clientId}/cards
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8/json
Параметры запроса
Пример запроса
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, описанному в данном разделе.
Получить информацию по карте
Метод возвращает следующую информацию по карте с указанным идентификатором:
- Уникальный идентификатор (токен) карты
- Маскированный PAN карты
- Дата окончания действия карты
- Статус карты
Запрос → GET
URL /partner/openapi-cards-lifecycle/v1/products/{productId}/cards/{cardTokenId}
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8/json
Параметры запроса
Пример запроса
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 карты
Метод возвращает PAN и CVV только для виртуальной карты.
Запрос → GET
URL /partner/openapi-cards-lifecycle/v1/products/{productId}/cards/{cardTokenId}/sensitive?encryptionSpec={encryptionSpec}&publicKey={publicKey}
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8/json
Параметры запроса
Пример запроса
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
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8/json
- User-Agent-Origin: должен содержать
ios
Параметры запроса
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
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8/json
Параметры запроса
Пример запроса
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
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8/json
Параметры запроса
Пример запроса
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
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8/json
Параметры запроса
Пример запроса
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
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8/json
Параметры запроса
Пример запроса
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
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8/json
Параметры запроса
Пример запроса
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
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8/json
Параметры запроса
Пример запроса
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 |