Привязка карт

Все API, описанные в документации, требуют авторизацию/аутентификацию. Информация по базовой структуре запросов/ответов, структуре ответа при ошибке валидации и таблице кодов ошибок доступна по этой ссылке .

Описание логики

Для привязки карты в систему клиент отправляет базовые данные по карте, после чего система передаёт запрос в процессинговый сервис (Uzcard, Humo). Процессинговый сервис отправляет SMS-код на номер телефона клиента. После ввода кода и отправки клиентом, запрос идёт на верификацию карты в процессинговый сервис. В случае успеха сервис возвращает данные карты вместе с токеном, которые сохраняются в базе данных.

1. API: Привязка карты

POST /cards/attach

Данный метод привязывает карту и отправляет SMS-код на указанный номер телефона.

Перейти к подробному описанию эндпоинта

Запрос:

№	Поле	Тип	Обяз.	Описание
1	id	UUID	+
2	params	Object	+
2.1	pan	String	+	Только цифры. Допустимая длина 16 символов
2.2	expiry	Date	+	Только валидные даты ("yyMM")
2.3	processingType	Enum	+	Принимает только константы ("UZCARD", "HUMO")
2.4	phoneNumber	String	+	Только цифры. Допустимая длина 12 символов. Номер должен начинаться с "998"

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

{
  "id": "e20ba72f-bc54-449f-ae13-7458afef64c6",
  "params": {
    "pan": "8600010132441332",
    "expiry": "2601",
    "processingType": "UZCARD",
    "phoneNumber": "9989996542222"
  }
}

Пример успешного ответа:

{
  "id": "e20ba72f-bc54-449f-ae13-7458afef64c6",
  "result": {
    "cardId": "87a490f5-831e-4751-86c0-008fc3dfe695"
  },
  "error": null
}

Пример ошибки валидации:

{
  "id": "e20ba72f-bc54-449f-ae13-7458afef64c6",
  "result": null,
  "error": {
    "code": 4,
    "message": "Validation Error. Field: params, message: Field must be not null"
  }
}

Пример ошибки: карта уже привязана

{
  "id": "e20ba72f-bc54-449f-ae13-7458afef64c6",
  "result": null,
  "error": {
    "code": 1010,
    "message": "Card is already attached"
  }
}

Пример непредвиденной ошибки:

{
  "id": "e20ba72f-bc54-449f-ae13-7458afef64c6",
  "result": null,
  "error": {
    "code": 1006,
    "message": "Service could not send SMS to attach card"
  }
}

2. API: Подтверждение привязки карты

POST /cards/attach/confirm

Подтверждает привязку карты, отправляя введённый клиентом SMS-код в процессинговый сервис.

Перейти к подробному описанию эндпоинта

Запрос:

№	Поле	Тип	Обяз.	Описание
1	id	UUID	+	Accepts only uuid
2	params	Object	+
2.1	cardId	UUID	+	Accepts only uuid
2.2	otpCode	String	+	Must contain only digits. Allowed length 6 characters

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

{
  "id": "5282afd6-776d-45e9-861f-9afd8e4456fa",
  "params": {
    "cardId": "b17d442d-19ad-4cce-babf-64f7cf6f5548",
    "otpCode": "44512"
  }
}

Пример успешного ответа:

{
  "id": "5282afd6-776d-45e9-861f-9afd8e4456fa",
  "result": {
    "message": "Card is successfully attached"
  },
  "error": null
}

Пример ошибки: карта не найдена

{
  "id": "5282afd6-776d-45e9-861f-9afd8e4456fa",
  "result": null,
  "error": {
    "code": 1007,
    "message": "Card is not found by params: cardId"
  }
}

Пример ошибки: карта уже была привязана

{
  "id": "5282afd6-776d-45e9-861f-9afd8e4456fa",
  "result": null,
  "error": {
    "code": 1010,
    "message": "Card is already attached"
  }
}

Пример непредвиденной ошибки:

{
  "id": "5282afd6-776d-45e9-861f-9afd8e4456fa",
  "result": null,
  "error": {
    "code": 1009,
    "message": "Service could not verify SMS code to attach card"
  }
}

Пример: срок действия SMS-кода истёк

{
  "id": "5282afd6-776d-45e9-861f-9afd8e4456fa",
  "result": null,
  "error": {
    "code": 1008,
    "message": "SMS code is already expired"
  }
}