API docs by Redocly

Wealth Reader (8.1.12)

Download OpenAPI specification:

E-mail: info@wealthreader.com

Регуляторные API на основе PSD2 предоставляют доступ к определенной финансовой информации, такой как остатки банковских счетов и транзакции. Однако существуют другие источники информации о благосостоянии, которые недоступны через эти API. API Wealth Reader расширяет информацию, предлагаемую регуляторными API, предоставляя доступ в реальном времени к дополнительным источникам благосостояния в любой организации по всему миру. Существует два других связанных документа, которые помогут вам интегрировать API Wealth Reader. Один - это руководство по интеграции виджета Javascript: https://docs-en.wealthreader.com/ а другой - коллекция Postman на основе этой документации. Очень важно: Это определение API адаптировано для клиентов, интегрирующих через Widget, поэтому некоторые параметры, которые не нужны для этого типа интеграции, были опущены, такие как параметры банковской аутентификации, поскольку будет использоваться токен.

Core

Основной API, необходимый для стандартных интеграций

Получает финансовые активы и детали их состава

Получает финансовые активы и детали их состава, включая инвестиционные портфели, состоящие из акций или фондов, кредитные карты, страховки и кредиты. Включает информацию о собственности для каждого актива, а также уникальные идентификаторы, которые облегчают обработку данных. Возможно получение Mock-данных. Проверьте у технической команды, как это сделать.

Request Body schema: application/x-www-form-urlencoded
api_key
string

Идентифицирует клиента в сервисе

code
string

Название организации. Полный список доступен через GET

Пример: caixabank

token
string

Идентифицирует сохраненные учетные данные. Процесс получения токена описан в документе 'Руководство по интеграции виджета'. Доступны следующие Mock-пользователи: MOCKDATA, ответ OK; MOCKOTP, ответ с OTP-вызовом; MOCKLOGINKO, ответ с ошибкой входа

Пример: MOCKDATA

product_types
string
Enum: "accounts" "portfolios" "cards" "receipts" "loans" "factoring" "confirming" "properties" "invoices" "files" "deposits" "leases" "insurances"

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

Пример: accounts,portfolios

only_balances
boolean
Default: false

Указывает, следует ли получать только остатки по продуктам вместо всей доступной информации. Значение по умолчанию: false.

Пример: false

fetch_transaction_details
boolean
Default: false

Указывает, следует ли получать расширенные сведения о транзакциях, когда коннектор организации это поддерживает. ВАЖНО: Включение этой опции подразумевает выполнение одной или нескольких дополнительных навигаций для каждой транзакции с целью обогащения возвращаемой информации. Это неизбежно и значительно увеличит время выполнения. Количество дополнительных навигаций растёт с объёмом транзакций. Рекомендуется включать её только тогда, когда есть уверенность, что требуется уровень детализации выше возвращаемого по умолчанию. Полученные сведения добавляются в ключ additional_info на уровне каждой транзакции. Использование этого параметра требует выделенного окружения.

Пример: false

date_from
string <date>

Дата, с которой запрашиваются транзакции, в формате ГГГГ-ММ-ДД. Должна быть датой до сегодняшнего дня.

Пример: 2024-01-01

date_to
string <date>

Это применяется только для ограничения по будущим датам для продуктов loan и confirming, в формате ГГГГ-ММ-ДД. Дата должна быть позже сегодняшнего дня

Пример: 2025-12-31

required_products_schema
string

Схема требуемых продуктов. Указывает счета или карты, данные которых требуются, с дополнительными настройками.

Пример: 

{
  "ACCOUNTS": {
    "0ae4d722b1c82feeafb4b36b2893230444071335": {
      "only_balances": false,
      "add_pdf_from_uuids": [
        "90763109952d4f2ebece8dceca8254078c5384a0"
      ],
      "date_from": "2024-04-03"
    }
  },
  "CARDS": {
    "957e6f63546f3fecacce80192b6f7436496dc057": {}
  }
}
add_pdf_from_uuids
string

Принимает uuid транзакций, разделенные запятыми. Параметр учитывается только если product_types равен ALL или включает accounts. Добавляет PDF-документ, связанный с каждой запрошенной банковской транзакцией.

Пример: 

20966426721d0885ef9d4b95535e1d3198936f16,8772d6c978d37d7af83094abf380b8b703e94105,e59296b79e7f80cec26679d2c65883025fd59295
otp_method
string

Выбирает канал доставки второго фактора, когда API вернул код 2017 или 20171 (несколько методов OTP). Повторите вызов с тем же идентификатором сессии из этого ответа и задайте otp_method точной строкой из поля otp_method одного объекта в statistics.otpMethods — не индекс массива. Пропустите при первом запросе с учётными данными; передайте после выбора пользователя. Пример ниже ориентировочный; всегда копируйте строку из statistics.otpMethods для вашей организации.

Пример: OTP_SMS ****1234

Responses

Request samples

Content type
application/x-www-form-urlencoded
api_key=a1b2c3d4e5f6g7h8i9j0&code=caixabank&token=1234Asdf&product_types=accounts%2Cportfolios&only_balances=false&date_from=2024-01-01&date_to=2025-12-31&required_products_schema=%7B%22ACCOUNTS%22%3A%7B%220ae4d722b1c82feeafb4b36b2893230444071335%22%3A%7B%22only_balances%22%3Afalse%2C%22add_pdf_from_uuids%22%3A%5B%2290763109952d4f2ebece8dceca8254078c5384a0%22%5D%2C%22date_from%22%3A%222024-04-03%22%7D%7D%2C%22CARDS%22%3A%7B%22957e6f63546f3fecacce80192b6f7436496dc057%22%3A%7B%7D%7D%7D&add_pdf_from_uuids=20966426721d0885ef9d4b95535e1d3198936f16%2C8772d6c978d37d7af83094abf380b8b703e94105

Response samples

Content type
application/json
[
  • {
    }
]

Список типов транзакций

query Parameters
lang
string
Default: "es"
Enum: "es" "en"

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Запрос токенов, связанных с api_key

Используйте этот метод для запроса токенов, связанных с определённым api_key. Результаты разбиты на страницы: limit задаёт количество токенов на странице (не более 500), а page выбирает возвращаемую страницу. Параметры api_key, method и limit обязательны; если какой-либо из них отсутствует или недействителен, API возвращает HTTP 400 и код ошибки 2.

Request Body schema: application/x-www-form-urlencoded
required
api_key
required
string^[a-z0-9]{8}$

api_key для идентификации клиента в сервисе

method
required
string
Value: "get"

Выполняемая операция. Единственное поддерживаемое значение — get.

Пример: get

limit
required
integer [ 1 .. 500 ]

Количество токенов на странице. Минимум 1, максимум 500.

Пример: 100

page
integer >= 1
Default: 1

Укажите номер страницы, которую хотите получить. Каждая страница содержит до limit токенов. Если не указано, значение по умолчанию 1.

Пример: 1

code
string

Код сущности для фильтрации токенов. Если не указан, возвращаются токены всех сущностей.

Пример: bbva

sort_by
string
Default: "created_at"
Enum: "created_at" "accesed_at"

Поле для сортировки результатов: created_at (дата создания) или accesed_at (дата последнего доступа). По умолчанию created_at.

Пример: created_at

sort_order
string
Default: "DESC"
Enum: "ASC" "DESC"

Направление сортировки: ASC (по возрастанию) или DESC (по убыванию). По умолчанию DESC.

Пример: DESC

Responses

Request samples

Content type
application/x-www-form-urlencoded
api_key=a1b2c3d4&method=get&limit=100&page=1

Response samples

Content type
application/json
{
  • "success": true,
  • "payload": {
    },
  • "pagination": {
    },
  • "statistics": {
    }
}

Отозвать токен

Этот метод позволяет отозвать существующий токен для деавторизации будущих запросов на доступ к API.

Request Body schema: application/x-www-form-urlencoded
required
api_key
string

Идентифицирует клиента в сервисе

token
string

Токен для отзыва.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Token successfully revoked."
}

Переназначить токен на другой api_key

Этот метод позволяет переназначить токен с одного api_key на другой. Оба api_key должны быть активны и принадлежать одной компании, а токен должен принадлежать api_key_source.

Request Body schema: application/x-www-form-urlencoded
required
api_key_source
string

api_key, с которого переназначается токен.

api_key_target
string

api_key, на который переназначается токен.

token
string

Токен для переназначения.

Пример: FRJ0mHlaqZwLzu

Responses

Request samples

Content type
application/x-www-form-urlencoded
api_key_source=a1b2c3d4e5f6g7h8i9j0&api_key_target=b2c3d4e5f6g7h8i9j0k1&token=FRJ0mHlaqZwLzu

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Token successfully reassigned."
}

Добавить новый домен

Добавляет связь между доменом, который будет размещать виджет, и целевым webhook. Для редактирования или тестирования ваших доменов используйте https://www.wealthreader.com/clients/

Request Body schema: application/x-www-form-urlencoded
required
method
required
string

Method to execute.

Пример: add

api_key
required
string

User's API key.

domain
required
string

Domain to add.

Пример: http://desarrollo.cliente.es

url_callback
required
string

URL for callback.

Пример: https://desarrollo.cliente.es/hooks/wealthreader

tokenize
required
string
Enum: "1" "0"

Определяет, запускает ли виджет процесс токенизации:

  • 1 - Пользователь проходит аутентификацию в финансовом учреждении (логин, согласие, 2FA при необходимости) и возвращается многоразовый токен
  • 0 - Токенизация не выполняется. В запрос необходимо включить значение ранее полученного токена

Пример: 1

Responses

Request samples

Content type
application/x-www-form-urlencoded
method=add&api_key=a1b2c3d4e5f6g7h8i9j0&domain=https%3A%2F%2Fwww.cliente.com&url_callback=https%3A%2F%2Fwww.cliente.com%2Fwebhooks%2Fwealthreader&tokenize=1

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Список кодов ошибок

Список кодов ошибок. Обратите особое внимание на то, что не все коды ошибок должны обрабатываться вашим приложением одинаково. При ошибке неправильного пароля не следует повторять вызов с теми же параметрами, но при ошибке, указывающей на то, что сущность находится на обслуживании, можно повторить попытку. Запросите техническую сессию с нашей командой для решения любых вопросов по управлению ошибками.

query Parameters
lang
string
Default: "es"
Enum: "es" "en"

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Список кодов предупреждений

Список кодов предупреждений.

query Parameters
lang
string
Default: "es"
Enum: "es" "en"

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Advanced

Дополнительные конечные точки, не требуемые для стандартных интеграций. Использовать только при явном указании Wealth Reader.

Получает список поддерживаемых организаций

Получает список поддерживаемых организаций и информацию, необходимую для рисования формы входа в систему организации.

query Parameters
show_only_tested
integer
Default: 0
Enum: 0 1

Indicates whether to show only tested entities. Default value is 0. In production environments, always use 1.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Зарегистрировать нового пользователя

Эта конечная точка является необязательной и не требуется для стандартных интеграций. Использовать только при явном указании Wealth Reader. Эта конечная точка позволяет зарегистрировать пользователя либо на платформе передачи портфеля Easytransfer, либо в инструменте отчётности Acumulas, на основе уникального идентификатора.

Request Body schema: application/x-www-form-urlencoded
required
api_key
required
string

Authentication key (8 alphanumeric characters)

user_id
required
string

User identification document.

Пример: 12345678A

service
required
string
Enum: "integra" "easy-transfer"

Service associated with the user. Determines the data flow.

Пример: easy-transfer

email
required
string <email>

User email, used according to service type.

Пример: sai_banker@singularbank.com

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "User registered successfully"
}

Проверить статус регистрации пользователя

Эта конечная точка является необязательной и не требуется для стандартных интеграций. Использовать только при явном указании Wealth Reader. Проверяет, зарегистрирован ли пользователь в системе Easytransfer или Acumulas, и возвращает уникальную ссылку доступа для пользователя.

Request Body schema: application/x-www-form-urlencoded
required
api_key
required
string

Authentication key

user_id
required
string

User identification document.

Пример: 12345678A

Responses

Response samples

Content type
application/json
{}

Отозвать ранее зарегистрированного пользователя

Эта конечная точка является необязательной и не требуется для стандартных интеграций. Использовать только при явном указании Wealth Reader. Эта конечная точка позволяет отменить регистрацию пользователя в сервисе платформы Easytransfer или Acumulas.

Request Body schema: application/x-www-form-urlencoded
required
api_key
required
string

Authentication key (8 alphanumeric characters)

user_id
required
string

User identification document.

Пример: 12345678A

service
required
string
Enum: "integra" "easy-transfer" "all"

Service from which to unregister the user. 'all' for all services.

Пример: easy-transfer

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "User unregistered successfully"
}

Пакетная загрузка соединений

Эта конечная точка является необязательной и не требуется для стандартных интеграций. Использовать только при явном указании Wealth Reader. Важно: Для использования управления пакетными процессами на стороне Wealthreader требуется выделенная среда. Эта конечная точка недоступна на api.wealthreader.com. Конечные точки, сгруппированные под тегом "batch", позволяют обрабатывать несколько банковских соединений асинхронно, в отличие от синхронного метода /entities/. Идеально для обработки больших объёмов соединений и избежания таймаутов.

Request Body schema: application/json
required
api_key
required
string

Identifies the client in the service

notification_url
required
string <uri>

Webhook URL. A notification is sent to this URL for each individual credential as soon as it completes processing, not only once all connections in the batch are done.

Пример: https://example.com/webhook/batch-complete

required
Array of objects (batch-connection) non-empty

List of connections to process

Responses

Callbacks

Request samples

Content type
application/json
{
  • "api_key": "a1b2c3d4e5f6g7h8i9j0",
  • "notification_url": "https://example.com/webhook/batch-complete",
  • "connections": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "batch_id": "batch_20250120_a1b2c3d4",
  • "total_connections": 5,
  • "estimated_completion_time": "2025-01-20T10:45:00Z"
}

Callback payload samples

Callback
POST: Webhook fired when a credential finishes processing
Content type
application/json
{
  • "batch_id": 10863151,
  • "credential_id": "cred_demo_002",
  • "status": "completed",
  • "timestamp": "2026-05-13T08:02:47+00:00"
}

Получить общую статистику по batch-соединениям

Эта конечная точка является необязательной. Получает общую статистику о результате обработки всех соединений в пакете.

Request Body schema: application/json
required
api_key
required
string

Identifies the client in the service

batch_id
required
string

Batch ID

Responses

Request samples

Content type
application/json
{
  • "api_key": "string",
  • "batch_id": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "batch_id": "batch_20250120_a1b2c3d4",
  • "status": "completed",
  • "statistics": {
    }
}

Получить индивидуальный результат конкретного соединения в пакете

Эта конечная точка является необязательной. Получает результат конкретного соединения из пакета.

Request Body schema: application/json
required
api_key
required
string

Identifies the client in the service

batch_id
required
string

Batch ID

credential_id
required
string

Filter by specific credential_id

Responses

Request samples

Content type
application/json
{
  • "api_key": "string",
  • "batch_id": "string",
  • "credential_id": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "payload": {
    },
  • "statistics": {
    }
}

MyBankMatch

Проверка владельца счёта: проверьте, принадлежит ли IBAN определённому владельцу, с помощью SEPA-проверки получателя платежа (VoP) банка, привязанного к вашей лицензии. Пошаговое руководство: MyBankMatch.

Проверяет, принадлежит ли IBAN владельцу (MyBankMatch)

Проверяет, принадлежит ли IBAN указанному владельцу, с помощью SEPA-проверки получателя платежа (VoP) вашего собственного банка, привязанного к вашей лицензии WealthReader. Возвращает вердикт банка: не заменяет его локальным расчётом сходства имён и не создаёт, не авторизует и не исполняет никаких платёжных поручений.

Перед первым вызовом

  1. Обеспечьте наличие активной лицензии с продуктом MY_BANK_MATCH и доступной квотой.
  2. Откройте Клиенты · MyBankMatch, нажмите Подключить банк и пройдите аутентификацию в размещённом окне WealthReader. Токенизированное подключение привязывается к вашему api_key; банковский токен не передаётся в браузер и не является параметром запроса.

Запрос: тело в формате формы (application/x-www-form-urlencoded) с api_key, iban и name, как и в /entities/. JSON не отправляется, заголовок X-API-Key не используется. Храните api_key на своём бэкенде.

Ответ: HTTP 200 означает, что получен результат продукта, а не то, что имя совпадает. Проверьте success, а затем payload.result:

payload.result Значение Дополнительные поля Тарифицируется
MATCH Банк считает, что имя совпадает с владельцем. Нет. Да, 0,10 EUR.
PARTIAL_MATCH Банк возвращает частичное совпадение (CLOSE_MATCH). suggested_name. Да, 0,10 EUR.
NO_MATCH Банк сообщает, что имя не совпадает. Нет. Да, 0,10 EUR.
NOT_CONFIGURED К лицензии ещё не привязан банк. setup_url. Нет.
REAUTH_REQUIRED Подключение к банку требует повторной аутентификации. setup_url, reason_code. Нет.
NOT_POSSIBLE Не удалось получить пригодный вердикт. Не равнозначно NO_MATCH. reason. Нет.

Квоту расходуют только MATCH, PARTIAL_MATCH и NO_MATCH. Ошибки входных данных и неокончательные результаты не тарифицируются.

Ключ идемпотентности и бесплатный повтор не предусмотрены. Если ответ утерян (тайм-аут, сбой сети или тело, которое невозможно интерпретировать), результат и расход квоты могут остаться неизвестными для вашего приложения. Не отправляйте тот же запрос повторно автоматически: проверьте историю в разделе «Клиенты» и обратитесь в службу поддержки, указав statistics.SESSION.

Полное руководство: MyBankMatch.

Request Body schema: application/x-www-form-urlencoded
required
api_key
required
string

Ключ из 8 шестнадцатеричных символов активной лицензии с продуктом MY_BANK_MATCH и доступной квотой. Храните его на своём бэкенде.

iban
required
string

IBAN страны SEPA. Пробелы удаляются, буквы переводятся в верхний регистр, проверяются длина, установленная для страны, и контрольные цифры mod-97.

Пример: ES9321005707250200257112

name
required
string <= 140 characters

Имя владельца. Непустое, корректный UTF-8, без управляющих символов, не более 140 символов. Обрезаются крайние пробелы, внутренние пробелы схлопываются.

Пример: Wealthreader S.L.

Responses

Request samples

Content type
application/x-www-form-urlencoded
api_key=a1b2c3d4&iban=ES9321005707250200257112&name=Wealthreader%20S.L.

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "payload": {
    },
  • "statistics": {
    }
}

Payments

Платежи SEPA со счёта на счёт, инициируемые из банка плательщика. Существует два способа их интеграции:

  • Fast Track: единственный запрос POST /payments/?action=fast-track возвращает URL оплаты, а Wealth Reader уведомляет ваш notification_url результатом OK или KO. См. Платежи Fast Track.
  • Виджет: ваш бэкенд создаёт неизменяемое платёжное намерение с помощью POST /payments/?action=create, открывает виджет с полученным токеном и подтверждает результат с помощью POST /payments/?action=status. См. Введение в платежи и Статусы, опрос и сверка.

Общие правила для всех вызовов /payments/?action=...

  • Метод POST с заголовком Content-Type: application/json и JSON-объектом в теле запроса (не более 32768 байт).
  • Аутентификация только через заголовок X-API-Key (wr_live_, за которым следуют 72 буквы или цифры) активной лицензии с продуктом PAYMENTS. Ключ никогда не передаётся в теле запроса. Каждый аутентифицированный вызов учитывается в лимите вызовов лицензии.
  • Тело запроса проверяется по белому списку: отсутствие обязательного поля или наличие непредусмотренного поля приводит к ответу 422 invalid_request.
  • Единственным положительным финансовым подтверждением является payment_status: settled. Событие виджета, возврат после SCA или interaction_status: completed никогда не означают, что платёж проведён.

Формат ошибки: application/json (не problem+json) со стабильным error.code; error.message носит информационный характер и может изменяться.

{"success": false, "error": {"code": "invalid_request", "message": "The request body has an invalid schema."}}
HTTP error.code Причина
400 invalid_json Тело запроса пустое, недопустимое или не является JSON-объектом.
401 invalid_api_key X-API-Key отсутствует, имеет неверный формат, неизвестен или неактивен.
403 payments_not_allowed Лицензия не включает продукт PAYMENTS.
404 action_not_found Неизвестное значение action.
405 method_not_allowed Метод, отличный от POST.
413 request_too_large Тело запроса превышает 32768 байт.
415 json_required Content-Type, отличный от application/json.
422 invalid_request Отсутствующие или непредусмотренные поля.
429 api_limit_reached Достигнут лимит вызовов лицензии.
500 internal_error Непредвиденная ошибка.
503 payments_disabled, payments_accept_new_disabled, payment_storage_unavailable, payment_state_unavailable Сервис временно недоступен или приём новых платежей приостановлен.

Уведомление OK или KO о платеже Fast Track Webhook

Wealth Reader отправляет этот POST на notification_url платежа Fast Track, когда проверяет статус платежа и обнаруживает, что он находится в конечном статусе. reconciliation_required не является конечным статусом, и уведомление о нём не отправляется: подтвердите его с помощью status.

  • outcome имеет значение ok, только если банк провёл платёж (settled); при rejected, cancelled, expired и failed отправляется ko.
  • Статус проверяется, пока плательщик остаётся на странице оплаты (она опрашивает его до получения окончательного результата или до истечения платёжной сессии), а также при каждом вашем вызове status. Отдельной запланированной отправки нет: если плательщик уходит до того, как банк завершит обработку, или ваш сервер не отвечает 2xx, уведомление отправляется при следующей проверке. Если оно не пришло через несколько минут после перенаправления плательщика, вызовите status с payment_intent_id; этот вызов также инициирует отправку ожидающего уведомления.
  • Ответьте любым кодом 2xx, чтобы уведомление считалось доставленным. Wealth Reader не следует перенаправлениям и ожидает не более 3 секунд.
  • Одно и то же уведомление может прийти более одного раза: рассматривайте сочетание customer_reference и outcome как идемпотентное.
  • Запрос не подписан. Прежде чем передавать ценный товар, подтвердите результат с помощью status, используя свой X-API-Key и payment_intent_id из уведомления.
header Parameters
User-Agent
required
string
Value: "WealthReader-Payments"
Request Body schema: application/json
required
outcome
required
string
Enum: "ok" "ko"

ok только для settled.

payment_status
required
string
Enum: "settled" "rejected" "cancelled" "expired" "failed"

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

customer_reference
required
string

Idempotency-Key, который вы отправили при создании платежа.

payment_intent_id
required
string <uuid>

Идентификатор, возвращённый fast-track. Используйте его для подтверждения результата с помощью status.

Responses

Request samples

Content type
application/json
Example
{
  • "outcome": "ok",
  • "payment_status": "settled",
  • "customer_reference": "11111111-1111-4111-8111-111111111111",
  • "payment_intent_id": "3f2b8c1e-5d4a-4b6f-9e21-7c0d4a1b2e3f"
}

Создаёт платёж и получает его URL (Fast Track)

Один вызов, возвращающий URL оплаты. Плательщик открывает его и авторизует платёж в своём банке; когда платёж достигает конечного статуса, Wealth Reader уведомляет ваш notification_url результатом OK или KO (см. вебхук notification_url). На внутреннем уровне создаётся то же неизменяемое намерение, что и при create: сумма, получатель и назначение платежа фиксируются до того, как попадают в браузер.

Заголовок Idempotency-Key одновременно служит вашим референсом продавца (customer_reference в уведомлении): он не передаётся в теле запроса. Если вы повторите тот же ключ с тем же телом, вы получите тот же URL; если вы используете его повторно с другими данными (в том числе с другим logo), ответом будет 409 idempotency_conflict.

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

header Parameters
X-API-Key
required
string

API-ключ лицензии с продуктом PAYMENTS. Храните его на своём бэкенде.

Idempotency-Key
required
string [ 16 .. 128 ] characters

От 16 до 128 символов; должен начинаться с буквы или цифры и содержать только буквы, цифры и . _ : -. Допускается UUID v4. Также является референсом продавца, возвращаемым в уведомлении.

Request Body schema: application/json
required
amount
required
string

Сумма в основных денежных единицах в виде строки JSON. "15.50" — это 15,50 EUR; допускается также целое число без десятичных знаков ("15"). Не более двух десятичных знаков, поэтому "15.5" и "15.50" — одна и та же сумма. Минимум 0.01. Максимум ограничен лимитом, который каждый клиент установил в своём банке.

Пример: 15.50

currency
required
string
Value: "EUR"

Валюта по ISO 4217. В этой версии только EUR.

Пример: EUR

required
object (payments-beneficiary)

Получатель перевода. Не может быть изменён после создания платежа.

reference
required
string [ 1 .. 140 ] characters

Назначение платежа в выписке, не более 140 символов.

Пример: Pedido 78901

priority
required
string
Enum: "normal" "instant"

normal (перевод SEPA) или instant (мгновенный перевод SEPA).

Пример: normal

notification_url
required
string <= 2000 characters

Публичный URL https, на который приходит уведомление OK или KO. Без учётных данных, с портом 443, если порт указан, и без частных, локальных адресов и адресов метаданных.

Пример: https://tienda.example.com/pagos/aviso

logo
string <= 2048 characters

Необязательно. Публичный URL https логотипа вашего магазина в формате SVG (путь должен заканчиваться на .svg; параметры запроса допускаются), без учётных данных, фрагмента и частных адресов, не более 2048 символов ASCII. Страница оплаты отображает его над сводкой; Wealth Reader его не скачивает, его загружает браузер плательщика. Любое другое значение приводит к ответу 422 invalid_logo.

Пример: https://tienda.example.com/marca/logo.svg

Responses

Request samples

Content type
application/json
{}

Response samples

Создаёт платёжное намерение (виджет)

Создаёт неизменяемое платёжное намерение и возвращает краткосрочный токен для открытия виджета в браузере плательщика. Сумма, получатель и назначение платежа фиксируются на бэкенде и не могут быть изменены из браузера. После закрытия виджета подтвердите результат со своего бэкенда с помощью status.

Существует два варианта тела запроса:

  • Стандартный: вы задаёте amount_minor, currency, beneficiary, reference, customer_reference и allowed_origin.
  • Управляемый профиль (например, cruz_roja_demo): Wealth Reader задаёт получателя, назначение платежа и лимиты; вы отправляете profile, institution_code, amount_minor, customer_reference и allowed_origin. Список банков можно получить с помощью profile-institutions.

Если вы повторите тот же Idempotency-Key с тем же телом, вы получите то же намерение (200, idempotent_replay: true); если вы используете его повторно с другими данными, ответом будет 409 idempotency_conflict. Ключ действует в рамках вашей компании.

Руководство: Намерения и идемпотентность и Интеграция с виджетом.

header Parameters
X-API-Key
required
string

API-ключ лицензии с продуктом PAYMENTS. Храните его на своём бэкенде.

Idempotency-Key
required
string [ 16 .. 128 ] characters

От 16 до 128 видимых символов ASCII. Генерируйте отдельный ключ для каждого платежа (допускается UUID v4) и используйте его повторно при повторной попытке вызова.

Request Body schema: application/json
required
One of
amount_minor
required
integer >= 1

Сумма в минимальных денежных единицах (центах) в виде целого числа JSON. 1500 — это 15,00 EUR. Максимум ограничен лимитом, который каждый клиент установил в своём банке.

Пример: 1500

currency
required
string
Value: "EUR"
required
object (payments-beneficiary)

Получатель перевода. Не может быть изменён после создания платежа.

reference
required
string [ 1 .. 140 ] characters

Назначение платежа в выписке, не более 140 символов.

Пример: Pedido 78901

customer_reference
required
string <= 128 characters

Ваш внутренний референс платежа. От 1 до 128 символов; начинается с буквы или цифры и содержит только буквы, цифры и . _ : -.

Пример: order-78901

allowed_origin
required
string

Источник (https://host[:puerto], без пути, строки запроса и фрагмента) страницы, открывающей виджет. Виджет работает только из этого источника.

Пример: https://tienda.example.com

locale
string
Value: "es"

Необязательно. Язык виджета; в этой версии только es.

expected_mode
string
Enum: "mock" "live"

Необязательно. Если значение не совпадает со средой, вызов возвращает 409 payment_mode_mismatch вместо создания платежа.

allowed_institution_codes
Array of strings <= 2500 items

Необязательно. Непустой список уникальных кодов банков (см. /payments/entities/), из которых может выбирать плательщик.

Пример: 

[
  "bbva-es",
  "santander-es"
]
logo
string or null

Необязательно. Публичный URL https вашего логотипа в формате SVG (путь заканчивается на .svg), без учётных данных, фрагмента и частных адресов, не более 2048 символов.

Responses

Request samples

Content type
application/json
Example
{
  • "amount_minor": 1500,
  • "currency": "EUR",
  • "beneficiary": {
    },
  • "reference": "Pedido 78901",
  • "customer_reference": "order-78901",
  • "allowed_origin": "https://tienda.example.com"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "payment": {
    }
}

Запрашивает статус платежа

Запрос статуса платежа между серверами до получения окончательного ответа банка. Обратный вызов, возврат после SCA или закрытие виджета не являются финансовым подтверждением: таковым является только payment_status: settled.

Wealth Reader ограничивает число внешних запросов на одно намерение; применяйте backoff и на своём бэкенде и не создавайте новое намерение, пока результат остаётся неоднозначным.

Неоднозначный результат: сбой сети, тайм-аут или нераспознанный ответ после отправки инициации переводит намерение в reconciliation_required с payment_status: unknown, а ответ содержит reconciliation. Инициация никогда не повторяется автоматически. Сохраните идентификатор и ключ идемпотентности, не создавайте новое намерение и не авторизуйте платёж повторно, а когда automatic_recovery имеет значение false, прекратите опрос и передайте вопрос в службу поддержки, указав reconciliation.reference.

Для платежей Fast Track этот запрос также отправляет на notification_url ожидающее уведомление OK/KO, если платёж достиг конечного статуса.

Руководство: Статусы, опрос и сверка.

header Parameters
X-API-Key
required
string

API-ключ лицензии, создавшей платёж.

Request Body schema: application/json
required
payment_intent_id
required
string <uuid>

payment.id, возвращённый create (для Fast Track — payment_intent_id, возвращённый fast-track).

Пример: 3f2b8c1e-5d4a-4b6f-9e21-7c0d4a1b2e3f

refresh
boolean
Default: true

Необязательно. true запрашивает у банка последний статус, когда это уместно; false возвращает сохранённый статус.

Responses

Request samples

Content type
application/json
{
  • "payment_intent_id": "3f2b8c1e-5d4a-4b6f-9e21-7c0d4a1b2e3f",
  • "refresh": true
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "payment": {
    }
}

Возвращает список банков и условия управляемого профиля

Возвращает условия управляемого профиля, включённого для вашей компании (получатель, назначение платежа, лимиты суммы), и банки, из которых может выбирать плательщик. Используйте выбранный code в качестве institution_code в create.

header Parameters
X-API-Key
required
string

API-ключ лицензии с продуктом PAYMENTS.

Request Body schema: application/json
required
profile
required
string

Код управляемого профиля.

Пример: cruz_roja_demo

Responses

Request samples

Content type
application/json
{
  • "profile": "cruz_roja_demo"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "profile": {
    }
}

Возвращает список банков, доступных для платежей

Каталог банков, через которые можно инициировать платежи, с их логотипами и поддерживаемыми способами оплаты. X-API-Key необязателен; если вы его передаёте, он проверяется и учитывается как вызов. Также поддерживается POST с теми же фильтрами в теле JSON и POST /payments/?action=entities с обязательным X-API-Key.

Неизвестные фильтры игнорируются и никогда не вызывают ошибку валидации.

query Parameters
country
string
Example: country=ES

Код страны по ISO 3166-1 alpha-2. ALL или пустое значение означает отсутствие фильтра.

Пример: ES

search
string

Текст, содержащийся в названии или коде, без учёта регистра (псевдоним q).

code
string
Example: code=santander-es

Точный код банка без учёта регистра.

Пример: santander-es

payment_method
string
Enum: "sepa_credit_transfer" "instant_sepa_credit_transfer"

Только банки, поддерживающие этот способ оплаты.

limit
integer [ 1 .. 2000 ]

Размер страницы (от 1 до 2000).

offset
integer >= 0

Количество пропускаемых результатов.

header Parameters
X-API-Key
string

Необязательно. Если передан, проверяется и учитывается как вызов.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "total": 1,
  • "entities": [
    ]
}

Cards (real time)

Real-time card expense synchronization from the Open Sync mobile app: per-customer employee pre-registration, signed webhooks (card_transaction.created / card_enrollment.confirmed), and REST query / backfill.

Register or rotate the real-time cards webhook

Creates or updates the webhook URL of the customer for the card_transaction.created and card_enrollment.confirmed events (see the cards-webhook-delivery schema for the delivery format and signature). On first setup, or when rotate_secret is true, a new webhook_secret (64 hex characters) is generated and returned once; in any other case webhook_secret comes back as null in the response and cannot be retrieved again. webhook_url must always be https:// and must resolve to a publicly routable host: localhost, private, loopback, link-local (including the cloud metadata address), CGNAT, multicast and reserved addresses are rejected, in any notation (hexadecimal, decimal, octal, short dotted or IPv4-mapped IPv6), and so is a hostname that does not resolve at all. The same check runs again right before every delivery, not only at registration: if the host is repointed at an internal address afterwards (DNS rebinding) the delivery is closed as failed with response_excerpt "blocked_host". Sending null in webhook_url disables webhooks for that customer; omitting the field leaves the stored URL untouched, which is how the secret is rotated without changing the URL.

Request Body schema: application/json
required
api_key
required
string

API key of the customer.

webhook_url
string or null

https:// URL that will receive the events, on a publicly routable host that resolves in DNS. null disables webhooks; omitting the field leaves the stored URL unchanged.

Пример: https://cliente.example.com/webhooks/wealthreader-cards

rotate_secret
boolean
Default: false

When true, generates and returns a new webhook_secret.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Pre-register the email of an employee

Creates an enrollment request in pending status with a short expiry (ttl_minutes, 20 by default, between 1 and 60) for the employee to confirm by opening the mobile app and entering that email (POST /user-sync-validation/, no contract change for the app). It is idempotent: repeating the call for the same (api_key, email) while it is still pending and not expired returns the same request. If the email is already linked to the calling customer, it returns status "active" directly. If it is already linked to a different customer, it returns 409. Rate limit: at most 60 calls to this endpoint per api_key every 60 seconds, counting every attempt and not only the ones that create a row, checked before anything else so the answers that create nothing (200 already active, 409 linked to another customer, 400) cannot be walked as an enumeration oracle. Exceeding it returns 429 with code rate_limited.

Request Body schema: application/json
required
api_key
required
string

API key of the customer.

email
required
string <email>

Email of the employee to pre-register.

Пример: empleado@cliente.com

ttl_minutes
integer [ 1 .. 60 ]
Default: 20

Minutes the request stays valid before expiring.

Responses

Request samples

Content type
application/json
{
  • "api_key": "a1b2c3d4",
  • "email": "empleado@cliente.com",
  • "ttl_minutes": 20
}

Response samples

Content type
application/json
{
  • "success": true,
  • "payload": {
    }
}

Check the status of an enrollment

Read-only status of an enrollment request. It has no side effects on card users, unlike POST /user-sync-validation/, which does confirm. The only write allowed is lazily marking a pending enrollment whose expiry date has already passed as expired.

query Parameters
api_key
required
string
Example: api_key=a1b2c3d4

API key of the customer. Note it travels in the query string, so it ends up in access logs and intermediary proxies.

Пример: a1b2c3d4

enrollment_id
required
string
Example: enrollment_id=0f3a9c7b1d2e4f5a6b7c8d9e0f1a2b3c

Identifier returned by POST /cards/enrollments/.

Пример: 0f3a9c7b1d2e4f5a6b7c8d9e0f1a2b3c

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "payload": {
    }
}

Query / backfill real-time card transactions

Returns the real-time card transactions received for the employees linked to this api_key, ordered by ascending id. Meant both for periodic backfill (poll with date_from/date_to and paginate with since_id) and for one-off queries. This is the same transaction object carried by the card_transaction.created webhook.

query Parameters
api_key
required
string
Example: api_key=a1b2c3d4

API key of the customer. Note it travels in the query string, so it ends up in access logs and intermediary proxies.

Пример: a1b2c3d4

date_from
string <date>
Example: date_from=2026-07-01

YYYY-MM-DD, on the operation date. Default: today minus 3 days.

Пример: 2026-07-01

date_to
string <date>
Example: date_to=2026-07-11

YYYY-MM-DD, on the operation date. Default: today.

Пример: 2026-07-11

email
string <email>
Example: email=empleado@cliente.com

Filters by the email of the employee.

Пример: empleado@cliente.com

since_id
integer
Example: since_id=216

Exclusive cursor on the transaction id, for pagination.

Пример: 216

limit
integer <= 1000
Default: 500
Example: limit=500

Maximum number of transactions to return (500 by default, 1000 max).

Пример: 500

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "payload": {
    }
}