### Общая информация:
#### Payment Page - платежная форма, программный модуль с пользовательским интерфейсом, который позволяет проводить оплаты. Payment Page может использоваться на сайтах и позволяет работать с платежными картами даже при отсутствии у мерчанта сертификата PCI DSS.
Работа с Payment Page строится следующим образом:
1) Мерчант формирует запрос Create Payment.
2) На стороне Платежной организации выполняется проверка и формирование ответа, при успешном прохождении и заполнении всех полей.
3) В ответ приходит ссылка на платежную форму.
4) Пользователь выполняет необходимые действия в платежной форме: указывает реквизиты и другую информацию и подтверждает готовность провести оплату.
5) Платежная форма перенаправляет на 3дс и высвечивается статус оплаты.
6) Плательщик нажимает на вернуться в магаз переходит на адрес в ретурн урл.
7) Мерчант запрашивает статус по запросу Get Transaction Status (не рекомендуется запрашивать чаще чем каждые 3 сек), либо дожидается callback с IP 176.123.177.29.
#### Gate(host to host) - является одной из «точек входа» для работы с платежной платформой и предоставляет наиболее полные возможности для взаимодействия на программном уровне. Через Gate можно проводить разовые оплаты и возвраты, а также получать дополнительную информацию, например, о статусе платежа. Также этот метод походит мерчантам с сертификата PCI DSS.
Работа с Gate строится следующим образом:
1) Мерчант формирует запрос Create Payment.
2) На стороне Платежной организации выполняется проверка и формирование ответа, при успешном прохождении и заполнении всех полей.
3) Мерчант высылает данные по карте при помощи запроса Add Payment Data to Transaction
4) Мерчант перенаправляет плательщика на урл в п1 для прохождения 3дс.
5) В платежной среде платежной организации и банка эквайера, на стороне требуемых систем, выполняется обработка платежа, по итогам которой мерчант запрашивает статус по запросу Get Transaction Status(не рекомендуется запрашивать чаще чем каждые 3 сек).
# Create Payment
#### создание страницы платежа на сайте мерчанта для плательщика.
Пример запроса на CURL
```shell
curl --request POST \
--url https://api.test.ecom.emoney.tools/core/v1/payment \
--header 'Authorization: Basic Base64(Merchan_id:secret)' \
--header 'Content-Type: application/json' \
--data
'{
"amount": 1000,
"return_url": "https://example.com/return",
"callback_url": "https://example.com/callback",
"description": "Your payment description",
"payment_method": 2,
"currency":"USD"
}'
```
## Данные
| Параметр | Значение| Обязательное|Тип |Описание|
|:-------------|:---------------|:---------------|:---------------:|:-------------|
| amount | 1000 | Да |int |Сумма|
| return_url | https://example.com/return | Да |string |URL который отобразится у физического лица после 3ds|
| callback_url | https://example.com/callback| Нет |string |URL на который отправим статус транзакции по ее завершению (успех или отказ) см табл статусов |
| description | Your payment description | Нет |string |Описание платежа мерчанта |
| order_id | 2611541 | Нет|int |Номер платежа в системе мерчанта |
|payment_method | 2 | Да |int |Метод платежа |
| currency | USD|Да|string |Валюта платежа|
Успешный ответ:
```json
{
"id": 37102,
"url": "https://pay.test.emoney.tools?id=37081"
}
```
id - платежа,
url - ссылка на платежную страницу
Возможные ошибки:
1) Нет одного из обязательных полей:
```json
{
"error": "JsonSyntaxException"
}
```
2) Неправильный формат:
```json
{
"error": "JsonSyntaxException"
}
```
3) Мерчант заблокирован:
```json
{
"message": "Unauthorized"
}
```
Коды ответов:
- 0 SUCCESS
- 1000 NO_TERMINAL_FOUND No terminal configured to process this transaction
- 1001 NO_TERMINAL_COMISSION_FOUND Can not found terminal commission for available terminals
# Add Payment Data to Transaction
#### Для Gate интеграции. Добавление данных по карте к существующей транзакции.
Пример запроса на CURL
```shell
curl --request POST \ - url https://api.test.ecom.emoney.tools/core/v1/public/payment_data \
--header 'Content-Type: application/json' \
--data '{
"id": 37102,
"payment_details": {
"pan": "4111111111111111",
"month": "01",
"year": "2023",
"cvv": "123"
}
}'
```
## Данные
| Параметр | Значение| Обязательное|Тип |Описание|
|:-------------|:---------------|:---------------|:---------------:|:-------------|
| id | 37102 | Да |int |id -транзакции платежа|
|pan | 4111111111111110| Да |string |номер банковской карты|
|month|01| Да |string |месяц истечения карты|
|year|2023|Да|string |год истечения карты|
| order_id | 2611541 | Нет|int |Номер платежа в системе мерчанта |
|cvv| 123 | Да |string |трехзначный защитный код, который находится на обратной стороне банковской карты|
Успешный ответ:
```json
{
"code": 1011,
"msg": "Payment data stored to secure cash"
}
```
Возможные ошибки:
1) Неправильный формат или нет одного из обязательных полей:
```json
{
"error": "JsonSyntaxException"
}
```
2) Повторный запрос по одной транзакции:
```json
{
"code": 1015,
"msg": "This transaction is not await payment data or not exist"
}
```
# Get Transaction Status
#### запрос получает статус конкретной платежной транзакции
Пример запроса на CURL
```curl --request GET \ --url 'https://api.test.ecom.emoney.tools/core/v1/public/payment?id=37102' \```
Успешный ответ:
```json
{
- "id": 37102,
- "created_at": "2023-10-23T08:41:58.255273Z",
"order_id": null,
"merchant": {
"name": "Филлиал нурлытау",
"company": {
"bin": "980504301209",
"name": "ТОО Прожектор перестройки",
"description": "Надежный партнер"
}
},
"description": "Your payment description",
"amount": 1000,
"customer_commission_amount": 0,
"merchant_commission_amount": null,
"completed_at": null,
"status": 400,
"transaction_type": 0,
"payment_method": 2
}
```
Возможные ошибки:
Не найдена транзакция
```json
{
"message": "Transaction not found"
}
```
# Refund
#### Возврат денежных средств, можно сделать частичным.
Пример запроса на CURL
```shell
curl --request POST \
--url https://api.test.ecom.emoney.tools/core/v1/refund \
--header 'Authorization: Basic MTA6MTIzNDU2' \
--header 'Content-Type: application/json' \
--data '{
"id": 37102,
"amount": 5
}'
```
id - айди транзакции оплаты,
amount - сумма транзакции для возврата, можно сделать частичный возврат
Успешный ответ:
```json
{
"id": 420838,
"status": 50
}
```
id - айди транзакции возврата,
status - статус транзакции
# ConfirmationRefund
#### Подтверждение возврата. Срок действия между созданием и подтверждением не более 20 минут.
Пример запроса на CURL
```shell
curl --request PATCH \
--url https://api.test.ecom.emoney.tools/core/v1/refund \
--header 'Authorization: Basic MTA6MTIzNDU2' \
--header 'Content-Type: application/json' \
--data '{
"id": 420838,
"approved": true
}'
```
Успешный ответ:
```json
{
"message": "Refund sent to processing"
}
```
Возможная ошибка. Неверная транзакция или срок действия транзакции возврата истек:
```json
{
"message": "No transaction found"
}
```
Коды и статусы транзакции:
| Параметр | Значение| Описание|Категория статуса|
|:-------------|:---------------|:-------------|:-------------|
| 0 | WAITING_PAYMENT_DATA|Транзакция создана, ожидание информации по платежным реквизитам|Информационный|
| 10 |PAYMENT_DATA_TAKEN|Данные по платежным реквизитам получены|Информационный|
| 50 | WAITING_APPROVE|Ожидание подтверждения, в том случае если тип платежа DMS|Информационный|
| 51 |APPROVED|Подтверждена, для типа платежа DMS|Информационный|
| 100| READY_TO_PROCESSING|Готово к процессу|Информационный|
| 110| IN_PROGRESS|В процессе|Информационный|
| 111| SENT_TO_TERMINAL|Отправка на терминал БВУ|Информационный|
|150 |WAITING_3DS|Мерчанту необходимо Redirect на URL:|Информационный|
|200 |3DS_ACCEPTED|Пользователь перешел на страницу ввода 3дс|Информационный|
|400 | FAIL|Не успех/Отказ|Финальный|
|500 |SUCCESS|Успешное завершение операции|Финальный|
Коды ошибок:
| Параметр | Значение| Description|Описание|
|:-------------|:---------------|:-------------|:-------------|
| 0 | NO_ERRORS| ||
| 10 | PAYMANT_METHOD_ERROR| No payment method aialable for this merchant|Для этого мерчанта способ оплаты не доступен |
| 20 | PAYMENT_DETAILS_ERROR| Wrong card number, or other presented data|Неправильный номер карты или другие предоставленные данные|
| 30 | INTERNAL_ERROR| Merchant not configured correctly|Мерчант настроен неправильно|
| 40 | TRANSACTION_EXPIRED|Transaction finalized by timeout|Транзакция завершена по таймауту|
| 50 | PROCESSING_ERROR|No terminal configured to process this transaction|Ни один терминал не настроен для обработки этой транзакции.|
| 60 | INSUFFICIENT_FUNDS|Insufficient balane on card|Недостаточный баланс на карте|
| 70 | DECLINED_BY_ACQUIRING|Bank aqiring was decline this transaction|Банковский эквайринг отклонен по данной транзакции|
| 80 | DECLINED_BY_ISSUER|Transaction was declined by card issuer|Транзакция отклонена эмитентом карты|
| 90 | DECLINED_AS_FRAUD|Transaction was declined as fraud|Транзакция отклонена как мошенничество|
