По любому вопросу мы в одном клике

Задать вопрос

Банковский API v.2

BPC Sandbox (далее «Тестовая площадка») — это тестовая среда, позволяющая опробовать API и оценить функциональность платежей.

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

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

Начало работы

Используйте тестовую площадку, чтобы опробовать основные функции управления картами, такие как: регистрация владельцев карт, выпуск карт, установка лимитов карт, перевод средств и т.д.

Прежде чем начать использовать тестовую площадку, вам необходимо создать учетную запись и получить токен безопасности API.

Токен безопасности API предоставляет авторизационный доступ к API тестовой площадки.

Главная страницы тестовой площадки содержит информацию об учетной записи для API песочницы, например:

Добавьте настраиваемое поле HTTP-заголовка "X-API-KEY" с токеном безопасности API в ваши HTTP-запросы, например:

X-API-KEY: YWdyYWRvYm9pbm92Omh6bG1lTTg

Справочник по API

Полный технический справочник по API можно найти здесь.

Пример коллекции Postman

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

Скачать коллекцию Postman

Настройки API коллекции Postman:

Особенности и ограничения тестовой площадки

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

Тестовая площадка возвращает заголовок Request-id в ответе (содержит уникальный идентификатор вашего запроса, может помочь с технической поддержкой).

Ограничения:

Варианты использования Banking API v.2

Используя Sandbox API, вы можете выполнять различные варианты использования: выпуск и работа с виртуальными картами, получение подробной информации о транзакциях и т.д., а также финансовые услуги (выпуск, управление и распространение платежных карт).

Чтобы протестировать функциональность Sandbox API, мы предлагаем следующий вариант использования: 1. Создайте двух держателей карт (данная функция автоматически создает счета для этих держателей карт). 1. Выпустите виртуальные карты для держателей карт; 1. Установите лимиты расходов карты; 1. Пополните одну из выпущенных карт; 1. Проверьте баланс счета карты; 1. Осуществите перевод(ы) между картами разных держателей карт; 1. Получите список переводов, отфильтрованный по карте зачисления, затем по карте списания; 1. Заблокируйте карту.

Создать владельца карты

Владелец карты — это основное лицо (физическое или юридическое лицо), которому могут быть выданы карты. Создайте новый ресурс Cardholder с помощью POST /cardholders.

Держатель карты — это ресурс верхнего уровня, поэтому это должен быть первый шаг в сценарии использования в бизнесе. При создании Владельца карты для этого держателя карты создается соответствующий Основной (по умолчанию) карточный счет. Обязательные параметры для создания Держателя карты: BillingAddress (country, postalCode), firstName, lastName, phoneNumber. Вы можете указать дополнительные необязательные поля для Держателя карты или попытаться обновить ресурс Держателя карты новыми данными позже. Подробную схему ресурсов Держателя карты см. в документации (вам понадобится опция «для обновления»).

Запрос

curl --location --request POST 'https://dev.bpcbt.com/v2/cardholders' \
--header 'X-API-KEY: YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
"billingAddress": {
    "city": "Budapest",
    "country": "HU",
    "line1": "Szabadsag ter",
    "line2": "9",
    "postalCode": "1850",
    "state": "Budapest"
},
  "email": "d@harrxample.com",
  "phoneNumber": "123123123",
  "firstName": "Harry",
  "lastName": "Waters",
  "dateOfBirth": "1998-03-24",
  "verification": {
    "idType": "passport",
    "documentId": "1111111111"
  },
  "status": "active"
}'

Ответ

{
    "id": "3269_1640686122656",
     "billingAddress": {
        "city": "Budapest",
        "country": "HU",
        "line1":"Szabadsag ter",
        "line2":"9",
        "postalCode": "1850",
        "state":"Budapest"
    },
    "email": "harry@example.com",
    "phoneNumber": "123123123",
    "firstName": "Harry",
    "lastName": "Waters",
    "dateOfBirth": "1998-03-24",
    "verification": {
        "idType": "passport",
        "documentId": "1111111111"
    },
    "status": "active"
}

Вы также можете получить созданный ресурс, используя запрос API GET cardholders/{id}. Повторите этот шаг, чтобы зарегистрировать другого владельца карты. При выполнении P2P-переводов будут задействованы оба карточных счета.

Выпуск виртуальных карт

Когда вы закончите работу с держателями карт, вы можете начать выпуск виртуальных карт для держателей карт. Создайте новую виртуальную карту и назначьте ее держателю карты. Виртуальные карты выпускаются в «активном» состоянии, специальной процедуры активации не требуется.

Обязательные параметры для выпуска виртуальных карт:

Поле Описание
productName Название карточного продукта (В запросе должно быть указано: «Visa»). На данный момент Sandbox настроен на выпуск только виртуальных карт Visa Classic. В дальнейшем список карточных продуктов может быть расширен.
cardholder Уникальный идентификатор объекта держателя карты. Возьмите значение с первого шага при создании владельца карты.

Запрос

curl --location --request POST 'https://dev.bpcbt.com/v2/cards' \
--header 'X-API-KEY: YOUR_TOKEN' \
--header 'content-type: application/json' \
  --data productName=Visa \
  --data cardholder=3269_1640686122656

Ответ

{
    "id": "100000007847",
    "status": "active",
    "productName": "Visa Classic",
    "cardholder": "3269_1640686122656",
    "account": {
        "accountNumber": "3556978700000000037", 
        "balance": 0,
        "currency": "EUR"
    },
    "embossedName": "",
    "expiryDate": "202512",
    "numberMask": "414364******8601",
    "creationDate": "2022-02-02T12:32:07",
    "blockingDate": "",
    "pinDenialCounter": "0",
    "spendingLimits": [
        {
            "amount": 1234,
            "interval": "daily"
        },{
            "amount": 123450,
            "interval": "monthly"
        }
    ]
}

Sandbox возвращает новый ресурс virtualCard в теле ответа.

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

Лимиты на покупки

Виртуальные карты выпускаются с лимитами (дневной лимит: 1000,00 EUR и месячный лимит: 10 000,00 евро). Вы можете изменить лимит по картам. Лимиты определяют возможные суммы расходов за определенный промежуток времени. Установка лимитов – это запрос на обновление ресурсов карты.

Следующие параметры карты могут быть обновлены:

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

Обратите внимание, что pin и reissueCard не являются полями ресурса карты. Они доступны только в запросе на обновление и вы никогда не увидите их в самом ресурсе карты.

Также есть некоторая специфика при смене статуса карты. Она описана в сценарии использования «Блокировка карты». Чтобы установить лимиты расходов по карте, укажите параметр spendingLimits в запросе на обновление. Вы можете установить или изменить столько разных лимитов в одном запросе, сколько захотите. Некоторые ограничения могут быть уже установлены при создании карты — это зависит от настроек тестовой площадки.

Запрос

curl --location --request POST 'https://dev.bpcbt.com/v2/cards' \
--header 'X-API-KEY: YOUR_TOKEN' \
--header 'content-type: application/json' \
--data-raw '{
  "spendingLimits": [
    {
      "amount": 123035,
      "interval": "monthly"
    },{
      "amount": 12130,
      "interval": "daily"
    }
  ]
}'

Ответ

{
    "id": "100000007847",
    "status": "active",
    "productName": " Classic",
    "cardholder": "3269_1640686122656",
    "account": {
        "accountNumber": "3556978700000000037", 
        "balance": 0,
        "currency": "EUR"
    },
    "embossedName": "",
    "expiryDate": "202512",
    "numberMask": "414364******8601",
    "creationDate": "2022-02-02T12:32:07",
    "blockingDate": "",
    "pinDenialCounter": "0",
    "spendingLimits": [
        {
            "amount": 12130,
            "interval": "daily"
        },{
            "amount": 123035,
            "interval": "monthly"
        }
    ]
}

Пополнение карты

Для осуществления переводов с карты на карту необходимо пополнить карточный счет. Пополнение карты — это операция, , которая позволяет добавлять средства, доступная только в тестовой площадке. Вам нужно будет указать номер карты назначения destinationCard, сумму amount(в наименьших денежных единицах) и валюту currency. Помните, что полный номер карты доступен только с помощью метода GET /cards/{id}, а единственной валютой, доступной в тестовой площадке, является евро.

Следующий запрос пополнит карточный счет на 125 EUR:

Запрос

curl --location --request POST 'https://dev.bpcbt.com/v2/topups' \
--header 'X-API-KEY: YOUR_TOKEN' \
--header 'content-type: application/json' \
  --data amount=12500 \
  --data currency=EUR \
  --data destinationCard=array \
  --data cardNumber=4143640071118601

Ответ

{
    "id": "662691",
    "amount": 12500,
    "currency": "EUR",
    "destinationCard": {
        "cardNumber": "4143640071118601"
    },
    "creationDate": "2022-02-04T13:14:27",
    "status": "approved",
    "statusMessage": "",
    "rrn": "000000348182"
}

Ответ содержит вновь созданное пополнение, которое представляет информацию о финансовой транзакции.

Проверить баланс карточного счета

После успешного запроса на пополнение вы можете проверить, что баланс карточного счета изменился. Используйте запрос GET /cards/{id} для получения баланса карточного счета.

Запрос

curl --location --request GET 'https://dev.bpcbt.com/v2/cards/100000000012' \
--header 'X-API-KEY: YOUR_TOKEN'

Ответ

{
  "id": "100000007847",
  "status": "blocked",
  "productName": " Classic",
  "cardholder": "3269_1640686122656",
  "account": {
    "accountNumber": "3556978700000000037",
    "balance": 143800,
    "currency": "EUR"
  },
  "embossedName": "",
  "expiryDate": "202512",
  "numberMask": "414364******8601",
  "number": "4143640071118601",
  "cvc": "245",
  "creationDate": "2022-02-02T12:32:07",
  "blockingDate": "2019-08-24T14:15:22",
  "pinDenialCounter": "2",
  "spendingLimits": [
    {
      "amount": 1234,
      "interval": "daily"
    },
    {
      "amount": 123450,
      "interval": "monthly"
    }
  ]
}

Осуществление транзакций (перевод между картами)

Вы можете попробовать перевести средства с карты на карту (P2P). По сути, все, что вам нужно, это указать карту источника, карту назначения и сумму. Для осуществления P2P-перевода вам понадобится номер виртуальной карты (PAN). Эту информацию о ранее выпущенных виртуальных картах можно получить с помощью запроса GET cards/{id}.

В следующем примере 12 евро будут переведены другому владельцу карты (мы предполагаем, что исходной картой является та, которую вы пополнили на предыдущем шаге, а картой назначения является карта второго владельца карты).

Запрос

curl --location --request POST 'https://dev.bpcbt.com/v2/transfers' \
--header 'X-API-KEY: YOUR_TOKEN' \
--header 'content-type: application/json' \
--data-raw '{
  "amount": 1200,
  "currency": "EUR",
  "sourceCard": {
    "cardNumber": "4143640071118601",
    "expiryDate": "202502"
  },
  "destinationCard": {
    "cardNumber": "4143640037674631"
  }
}'

Ответ

{
    "id": "407930",
    "amount": 1200,
    "currency": "EUR",
    "sourceCard": {
        "cardNumber": "4143640071118601",
        "expiryDate": "202502"
    },
    "destinationCard": {
        "cardNumber": "4143640037674631"
    },
    "creationDate": "2022-03-17T12:07:04",
    "status": "approved",
    "statusMessage": "",
    "rrn": "000000407928"
}

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

Получить список переводов

После выполнения некоторых P2P-переводов между учетными записями вы можете запросить список переводов по карте источника или назначения. При запросе сбора ресурсов Transfer необходимо использовать обязательный параметр запроса cardNumberFltr. Также вы можете включить в параметры запроса дополнительные фильтры:

Запрос

curl --location --request GET 'https://dev.bpcbt.com/v2/transfers?periodStartFltr=2022-03-29&cardNumberFltr=4143640071118601' \
--header 'X-API-KEY: YOUR_TOKEN' \

Ответ

{
    "transfers": [
        {
            "id": "407930",
            "amount": 1200,
            "currency": "EUR",
            "sourceCard": {
                "cardNumber": "4143640071118601",
                "expiryDate": "202512"
            },
            "destinationCard": {
                "cardNumber": "4143640037674631"
            },
             "creationDate": "2022-03-17T12:07:04",
            "status": "approved",
            "statusMessage": "",
            "rrn": "000000407928"
        }, {
            "id": "407975",
            "amount": 15600,
            "currency": "EUR",
             "sourceCard": {
                "cardNumber": "4143640071118601",
                "expiryDate": "202512"
            },
            "destinationCard": {
                "cardNumber": "4143640037674631"
            },
            "creationDate": "2022-02-17T13:32:41",
            "status": "declined",
            "statusMessage": "Insufficient Funds ...",
            "rrn": "000000403548"
         }
    ]
}

При получении списка передач каждый объект ресурса равен тому, который вы видели при выполнении переводов.

Заблокировать карту

Блокировка карты — это запрос на обновление ресурса Карты.

Следует изменять только один параметр карты за запрос.

Что касается обновления статуса карты, то здесь есть некоторые ограничения. При смене статуса карты возможны не все комбинации текущего статуса и нового статуса:

Запрос

curl --location --request POST 'https://dev.bpcbt.com/v2/cards/100000007847' \
--header 'X-API-KEY: YOUR_TOKEN' \
--header 'content-type: application/json' \
--data-raw '{
  "status": "blocked"
}'

Ответ

{
    "id": "100000007847",
    "status": "blocked",
    "productName": " Classic",
    "cardholder": "3269_1640686122656",
    "account": {
        "accountNumber": "3556978700000000037", 
        "balance": 12100,
        "currency": " EUR"
    },
    "embossedName": "",
    "expiryDate": "202512",
    "numberMask": "414364******8601",
    "creationDate": "2022-02-02T12:32:07",
    "blockingDate": "2022-03-08T15:04:22",
    "pinDenialCounter": "0",
    "spendingLimits": [
        {
            "amount": 12130,
            "interval": "daily"
        },{
            "amount": 123035,
            "interval": "monthly"
        }
    ]
}

После обновления ресурса Card вы получаете в ответ измененный ресурс. Теперь, когда карта заблокирована, попробуйте сделать несколько переводов с ее помощью и проверьте статус операции.

Категории:
Банкинг API V2