paypal.php¶

Модуль интеграции с PayPal для обработки платежей, управления подписками через Vault и автоматического биллинга

Методы API¶

Метод	Действие	Описание
`charge_vault`	списание средств через Vault	Выполняет списание средств с сохраненного метода оплаты (Vault) для указанного инвойса.
`check_order`	проверка заказа	Проверяет статус захвата (capture) PayPal заказа и автоматически привязывает Vault к клиенту, если платеж завершен.
`check_payment`	проверка платежа	Создает подписку или выполняет списание для проверки доступности метода оплаты.
`check_subscription`	проверка подписки	Проверяет наличие недавних транзакций по подписке через API PayPal.
`create_order`	создание заказа	Создает заказ PayPal (обычный или с использованием Vault).
`create_payment_token`	создание токена платежа	Создает токен для привязки метода оплаты (Vault) к клиенту.
`create_setup_token`	создание токена настройки	Инициирует процесс создания Setup Token в PayPal для последующей привязки карты.
`create_subscription`	создание подписки	Инициирует процесс создания PayPal подписки для клиента на основе существующего счета.
`revoke_vault`	отзыв платежного токена	Удаляет сохраненный платежный метод (Vault) из системы PayPal.

paypal/charge_vault¶

Выполняет списание средств с сохраненного метода оплаты (Vault) для указанного инвойса.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `charge_vault`
token	✅	string	Токен авторизации
invoice_id	✅	integer	Идентификатор инвойса для списания средств
vault_id	✅	string	Идентификатор сохраненного метода оплаты (Vault ID)
billing	❌	string	Идентификатор системы биллинга для обработки платежа.

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

curl -s "https://invapi.hostkey.ru/paypal.php" -X POST \
--data "action=charge_vault" \
--data "token=HOSTKEY_TOKEN" \
--data "invoice_id=12345" \
--data "vault_id=vault_abc123"

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

{
"result": "OK",
"action": "charge_vault",
"data": {
"status": "captured",
"amount": {
"value": "10.00",
"currency_code": "EUR"
},
"id": "PAYID-XXXXXXXXXXXX"
}
}

Примеры ошибок

{
"code": -1,
"message": "A payment for this invoice is already being processed, please try again in a few minutes"
}

paypal/check_order¶

Проверяет статус захвата (capture) PayPal заказа и автоматически привязывает Vault к клиенту, если платеж завершен.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `check_order`
token	✅	string	Токен авторизации
error_description	✅	string	Описание ошибки из ответа PayPal
purchase_units	✅	`array<string>`	Массив данных о покупках в заказе
status	✅	string	Статус заказа PayPal. Допустимые значения: enable.
payment_source	✅	`array<string>`	Источник платежа в заказе
invoice_id	❌	string	Идентификатор счета для отслеживания платежа.
order_id	❌	integer	Уникальный номер заказа в системе PayPal.
billing	❌	string	Название или идентификатор биллинговой системы.

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

curl -s "https://invapi.hostkey.ru/paypal.php" -X POST \
--data "action=check_order" \
--data "token=VALUE" \
--data "error_description=VALUE" \
--data "purchase_units[]=VALUE" \
--data "status=enable" \
--data "payment_source[]=VALUE"

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

{
"result": "OK",
"action": "check_order",
"data": {
"id": "ORD-XXXXX",
"status": "COMPLETED",
"purchase_units": [
{
"payments": {
"captures": [
{
"status": "COMPLETED"
}
]
}
}
],
"payment_source": {
"paypal": {
"attributes": {
"vault": {
"id": "vault_abc123"
}
}
}
}
}
}

Примеры ошибок

{
"code": -1,
"message": "failed to confirm order: error message"
}

paypal/check_payment¶

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

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `check_payment`
token	✅	string	Токен авторизации
invoice_id	✅	integer	ID инвойса для создания подписки/платежа
billing	❌	string	Идентификатор системы биллинга для обработки платежей.

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

curl -s "https://invapi.hostkey.ru/paypal.php" -X POST \
--data "action=check_payment" \
--data "token=HOSTKEY_TOKEN" \
--data "invoice_id=12345"

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

{
"result": "OK",
"action": "check_payment",
"data": {
"subscription_id": 12345,
"status": "active"
}
}

Примеры ошибок

{
"code": -1,
"message": "PayPal is not available for USD customers"
}

paypal/check_subscription¶

Проверяет наличие недавних транзакций по подписке через API PayPal.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `check_subscription`
token	✅	string	Токен авторизации для выполнения запроса к PayPal API
error_description	✅	string	Описание ошибки при инициализации сессии PayPal
subscription_id	✅	string	Идентификатор подписки для проверки транзакций
billing	❌	string	Данные биллинга пользователя
transactions	✅	string	Параметр `transactions`
invoice_id	❌	string	Идентификатор счета для привязки транзакции к платежному документу.

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

curl -s "https://invapi.hostkey.ru/paypal.php" -X POST \
--data "action=check_subscription" \
--data "token=VALUE" \
--data "error_description=VALUE" \
--data "subscription_id=VALUE" \
--data "transactions=VALUE"

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

{
"resource": {
"invoice_id": 100,
"custom_id": "whmcs",
"seller_receivable_breakdown": {
"paypal_fee": {
"value": "0.50"
}
},
"amount": {
"value": "29.99",
"currency_code": "EUR"
},
"id": "TRANS-123",
"status": "COMPLETED",
"origin": "new subscription sub_abc123",
"subscription_id": "sub_abc123"
}
}

Примеры ошибок

{
"code": -1,
"message": "no recent transaction for subscription"
}

paypal/create_order¶

Создает заказ PayPal (обычный или с использованием Vault).

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `create_order`
token	✅	string	Токен авторизации
invoice_id	❌	integer	Уникальный идентификатор счета для создания заказа.
vault	❌	integer	Флаг использования платежного хранилища для автоматического списания средств.
billing	❌	string	Название системы биллинга или метод обработки платежа.

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

curl -s "https://invapi.hostkey.ru/paypal.php" -X POST \
--data "action=create_order" \
--data "token=HOSTKEY_TOKEN" \
--data "invoice_id=12345" \
--data "vault=1" \
--data "billing=stripe"

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

{
"result": "OK",
"action": "create_order",
"data": {
"id": "ORDER-ID-123",
"status": "APPROVED",
"purchase_units": []
}
}

Примеры ошибок

{
"code": -1,
"message": "PayPal is not available for USD customers"
}

paypal/create_payment_token¶

Создает токен для привязки метода оплаты (Vault) к клиенту.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `create_payment_token`
token	✅	string	Токен авторизации
setup_token_id	✅	string	Идентификатор токена настройки для создания платежного токена PayPal.
billing	❌	string	Название биллинговой системы или идентификатор профиля клиента.

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

curl -s "https://invapi.hostkey.ru/paypal.php" -X POST \
--data "action=create_payment_token" \
--data "token=HOSTKEY_TOKEN" \
--data "setup_token_id=VALUE"

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

{
"result": "OK",
"vault_id": "vault_xyz789"
}

Примеры ошибок

{
"code": -1,
"message": "missing setup_token_id"
}

paypal/create_setup_token¶

Инициирует процесс создания Setup Token в PayPal для последующей привязки карты.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `create_setup_token`
token	✅	string	Токен авторизации
billing	❌	string	Метод оплаты или биллинг-система для создания токена настройки PayPal.

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

curl -s "https://invapi.hostkey.ru/paypal.php" -X POST \
--data "action=create_setup_token" \
--data "token=HOSTKEY_TOKEN"

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

{
"result": -1,
"error": "PayPal is not available for USD customers",
"client_id": 123,
"billing": "whmcs"
}

Примеры ошибок

{
"code": -1,
"message": "PayPal is not available for USD customers"
}

paypal/create_subscription¶

Инициирует процесс создания PayPal подписки для клиента на основе существующего счета.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `create_subscription`
token	✅	string	Токен авторизации пользователя.
invoice_id	❌	integer	Идентификатор счета для привязки подписки.
billing	❌	string	Название системы биллинга или метод обработки платежа.

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

curl -s "https://invapi.hostkey.ru/paypal.php" -X POST \
--data "action=create_subscription" \
--data "token=HOSTKEY_TOKEN" \
--data "invoice_id=123" \
--data "billing=whmcs"

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

{
"result": "OK",
"action": "create_subscription",
"data": {
"resource": {
"invoice_id": 123,
"custom_id": "whmcs",
"seller_receivable_breakdown": {
"paypal_fee": {
"value": "0.50"
}
},
"amount": {
"value": "49.99",
"currency_code": "EUR"
},
"id": "sub_123456789",
"status": "active",
"origin": "new subscription sub_123456789",
"subscription_id": "sub_123456789"
}
}
}

Примеры ошибок

{
"code": -1,
"message": "PayPal is not available for USD customers"
}

paypal/revoke_vault¶

Удаляет сохраненный платежный метод (Vault) из системы PayPal.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `revoke_vault`
token	✅	string	Токен авторизации пользователя.
vault_id	✅	integer	Идентификатор платежного метода (Vault ID), который необходимо отозвать.
billing	❌	string	Идентификатор системы биллинга для обработки операции.

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

curl -s "https://invapi.hostkey.ru/paypal.php" -X POST \
--data "action=revoke_vault" \
--data "token=YOUR_TOKEN" \
--data "vault_id=12345"

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

{
"result": "OK"
}

Примеры ошибок

{
"code": -1,
"message": "revoke_vault: vault 12345 is not owned by client 789"
}