Завершение платежа по номеру

Метод Complete payment by document ID используется для завершения платежа по его номеру document_id для текущего реселлера или любого из его нижестоящих реселлеров, например, при получении оплаты во внешних системах. В зависимости от суммы оплаты относительно суммы платежа и его статуса возможны следующие ситуации, представленные в таблице.

Сумма оплаты	Статус платежа
Сумма оплаты	Ожидает оплаты, Просрочен	Завершен, Оплачен с баланса, Отменен
Равна сумме платежа в платформе (полная оплата)	Платеж переходит в статус Завершен. Сохраняется указанный ID внешней транзакции.	Статус платежа не меняется. Сохраняется указанный ID внешней транзакции. От имени менеджера, чей токен использовался при вызове метода, создается корректировка на всю указанную сумму оплаты с комментарием "Учет денежных средств, поступивших на основании {document_id} из внешней системы.". Срабатывает событие уведомлений Оплата платежа получена из внешней системы (Paid amount has been received from external system) (см. Создание события уведомлений).
Больше суммы платежа в платформе (переплата)	Платеж переходит в статус Завершен. Сохраняется указанный ID внешней транзакции. Срабатывает событие уведомлений Оплата платежа получена из внешней системы (Paid amount has been received from external system) (см. Создание события уведомлений). От имени менеджера, чей токен использовался при вызове метода, создается корректировка на вычисленную сумму переплаты с комментарием "Учет денежных средств, поступивших на основании {document_id} из внешней системы.".
Меньше суммы платежа в платформе (частичная оплата)	Статус платежа не меняется. Сохраняется указанный ID внешней транзакции. Срабатывает событие уведомлений Оплата платежа получена из внешней системы (Paid amount has been received from external system) (см. Создание события уведомлений). От имени менеджера, чей токен использовался при вызове метода, создается корректировка на всю указанную сумму оплаты с комментарием "Учет денежных средств, поступивших на основании {document_id} из внешней системы.".

Платеж также можно завершить по его ID (см. Завершение платежа по ID).

Для авторизации требуется API-токен менеджера (сотрудника). API-токен можно получить через Панель управления Оператора (см. Просмотр и обновление информации о сотруднике).

По указанному в запросе API-токену определяются:

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

POST {base_url}/api/v3/resellers/{reseller_id}/payments/{document_id}

{
  "data": {
    "attributes": {
        "payment_method_id": "{payment_method_id}",
        "amount": {amount},
        "currency_code": "{currency_code}",
        "external_transaction_id": "{external_transaction_id}"
        }
    }
}

Аргументы

Название	Тип параметра	Тип данных	Обязательный/ Опциональный	Описание
X-Api-Token	header	string	Обязательный	API-токен сотрудника, выполняющего операцию (см. Просмотр и обновление информации о сотруднике)
Content-Type	header	string	Обязательный	Тип данных, передаваемых в запросе. Необходимо указать: application/vnd.api+json
Accept	header	string	Обязательный	Поддерживаемые типы данных в ответе. Необходимо указать: application/vnd.api+json
base_url	path	string	Обязательный	URL ActivePlatform
reseller_id	path	integer	Обязательный	ID реселлера. Возможно указать ID текущего реселлера или ID любого из его нижестоящих реселлеров (см. Просмотр информации о реселлере)
document_id	path	integer	Обязательный	Номер платежа (см. Получение информации о платеже)
payment_method_id	form	string	Обязательный	ID способа оплаты для завершения платежа (см. Просмотр списка способов оплаты)
amount	form	number	Опциональный	Сумма оплаты. Может быть не равна сумме платежа в платформе
currency_code	form	string	Опциональный	Код валюты оплаты. Должен совпадать с кодом валюты платежа (см. Получение информации о платеже)
external_transaction_id	form	string	Опциональный	ID внешней транзакции для оплаты: Если указан, сумма и код валюты оплаты являются обязательными. Если не указан, сумма оплаты игнорируется, и платеж завершается полностью. Формат данных: от 2 до 255 знаков, буквы латинского алфавита Aa-Zz, кириллицы Аа-Яя, цифры 0-9 и спецсимволы ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _` { \| } ~ (кроме пробела)

Модель ответа

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

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

POST /api/v3/resellers/1/payments/2005258
Host: test.activeplatform.com
Content-Type: application/vnd.api+json
X-Api-Token: vY5fwetestK3gJXZH5uHCw
Accept: application/vnd.api+json

{
    "data": {
        "attributes": {
            "payment_method_id": "2",
            "amount": 123.45,
            "currency_code": "USD",
            "external_transaction_id": "d2a7e121-8636-42a2-a3cf-d8a5d0131a96"
        }
    }
}

Пример ответа

{
    "data": {
        "id": "3212",
        "type": "payments",
        "attributes": {
            "created_at": "2023-10-26T16:37:31.534421+0300",
            "updated_at": "2023-10-26T16:37:43.325470+0300",
            "account_id": 478,
            "discount_amount": "0.0",
            "total": "123.45",
            "currency_code": "USD",
            "comment": "1",
            "status": "completed",
            "document_id": "2005258",
            "expiration_date": null,
            "payment_method_id": 2,
            "requester_ip": "10.11.12.13",
            "manager_id": 6,
            "purpose": "",
            "external_total": null,
            "external_currency": null,
            "due_date": null, 
            "payment_method_name": "Check",
            "closed_at": "2023-10-26T16:37:43.325470+0300"
        },
        "relationships": {
            "orders": {
                "data": []
            },
            "invoices": {
                "data": []
            },
            "charges": {
                "data": []
            },
            "corrections": {
                "data": []
            }, 
            "reseller": {
                "data": {
                    "id": "1",
                    "type": "resellers"
                }
            },
            "account": {
                "data": {
                    "id": "478",
                    "type": "accounts"
                }
            },
            "payment_method": {
                "data": {
                    "id": "2",
                    "type": "payment_methods"
                }
            }
        }
    }
}

Ошибки

Статус	Код ошибки	Текст ошибки	Комментарий
404	PAYMENT-001	We could not find what you are looking for	У реселлера не найден платеж с указанным номером `document_id`. Проверьте ID реселлера и номер платежа (см. Получение информации о платеже)
422	PAYMENT-002	Не найден обязательный параметр payment_method_id (код: PAYMENT-002).	Проверьте ID способа оплаты (см. Просмотр списка способов оплаты)
	PAYMENT-003	Переданный currency_code не совпадает с currency_code платежа (код: PAYMENT-003).	Проверьте код валюты оплаты. Код валюты оплаты должен совпадать с кодом валюты платежа. Для сравнения с платежом см. Получение информации о платеже. Укажите код валюты оплаты, если указан ID внешней транзакции.
	PAYMENT-004	Оплата платежа с таким external_transaction_id не может быть обработана повторно (код: PAYMENT-004).	Запрещена повторная оплата с тем же ID внешней транзакции
	PAYMENT-005	Параметр amount должно быть в денежном формате и больше 0. Пример: 123.45 (код: PAYMENT-005).	Проверьте сумму оплаты
	PAYMENT-007	Некорректный формат external_transaction_id (код: PAYMENT-007).	Проверьте ID внешней транзакции (требования см. выше в разделе Аргументы)

Пример ответа с ошибкой

{
    "errors": [
        {
            "status": "422",
            "title": "Unprocessable entity",
            "detail": "External_transaction_id has invalid format (code: PAYMENT-007).",
            "source": {
                "pointer": "/data/attributes/external_transaction_id"
            }
        }
    ]
}