Вебхуки

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

к сведению

Если функция вебхуков отключена, вам придется самостоятельно отправлять запрос transaction/state для каждой операции, чтобы отслеживать статус и узнавать следующий этап.

Настройка получения вебхуков

Создайте на своей стороне публичный URL-адрес для приема уведомлений.
Передайте его вашему менеджеру Zetplat.

Чтобы перестать получать вебхуки, напишите вашему менеджеру в Zetplat.

Требования к ответу

На любой полученный вебхук ваш сервис должен возвращать HTTP-код 200. Если в ответе будет передан код из диапазонов 4** или 5**, Zetplat будет повторять отправку, пока не получит ответ. Отправка будет проходить с увеличивающимися интервалами по следующим правилам:

время между повторными попытками постепенно растет, но не превышает 15 минут;
если на протяжении 30 минут ни одна из попыток не завершилась успешно (HTTP-код 200), отправка вебхука окончательно прекращается.

ВАЖНО!

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

Вебхуки Zetplat

`action_pending`

Zetplat отправляет этот вебхук, если для продолжения операции нужны дополнительные действия. Например, пользователю нужно пройти 3D Secure.

Параметры

Название	Обязательность	Тип	Описание
`type`	+	string	Тип вебхука: `action_pending`
`session_info`	+	object	Платежная сессия

Пример

curl -X POST \
  https://partner.ru \
  -H 'Content-Type: application/json' \
  -H 'X-Signature: signature' \
  -d '{
    "type": "action_pending",
    "session_info": {
      "id": "ps_3230",
      "transaction_status": "active",
      "created_date": "2024-05-27T02:03:00.000000Z",
      "updated_at": "2024-05-27T02:03:00.000000Z",
      "payments": [{
        "id": "pm_1313",
        "transaction_status": "pending",
        "created_date": "2024-05-27T02:03:00.000000Z",
        "user_info": {
          "user_id":"user@test.ru"
        },
        "payment_info": {
          "type": "card_info",
          "card_info": {
            "card_network": "visa",
            "card_last4": "8801",
            "card_bin":"444600"
          }
        },
        "sum_info": {
          "sum": 15000,
          "currency_code": "rub"
        },
        "fee_info": {
          "fee": {
            "merchant_fee": {
              "sum": 10,
              "currency_code": "RUB"
            }
          }
        },
        "transaction_info": {
          "retrieval_ref_number": "425307614918",
          "authorization_code": "057441"
        },
        "user_action": {
          "type": "destination_info",
          "destination_info": {
            "url_address": "https://zetplat.com?foo=bar",
            "domain": "https://zetplat.com",
            "http_method": "POST",
            "additional_params": {
              "foo": "bar"
            },
            "extra_params": {
              "PaReq": "sdfew^//asdhbv",
              "MD": "abc75daefnn"
            }
          }
        }
      }]
    }
  }'

`checkout_results`

Zetplat отправляет этот вебхук, когда завершает операцию. Результат приходит в поле transaction_status массива payments. Статус successful означает успешную операцию.

Параметры

Название	Обязательность	Тип	Описание
`type`	+	string	Тип вебхука: `checkout_results`
`session_info`	+	object	Платежная сессия

Примеры

Выплата
Платеж

curl -X POST \
  https://partner.ru \
  -H 'Content-Type: application/json' \
  -H 'X-Signature: signature' \
  -d '{
    "type": "checkout_results",
    "session_info": {
      "id": "ps_3230",
      "transaction_status": "completed",
      "created_date": "2024-05-27T02:03:00.000000Z",
      "updated_at": "2024-05-27T02:03:00.000000Z",
      "payouts": [{
        "id": "po_1234",
        "transaction_status": "successful",
        "created_date": "2024-05-27T02:03:00.000000Z",
        "user_info": {
          "user_id": "user123",
          "contact_info": [{
            "email_address": "user@gmail.com"
          }]
        },
        "payout_info": {
          "type": "account_info",
          "account_info": {
            "payment_system": "fps_info_verification",
            "fps_info_verification": {
              "phone_number": "79261234567",
              "bank_identifier": "100000000069"
            }   
          }
        },
        "sum_info": {
          "sum": 10000,
          "currency_code": "rub"
        },
        "fee_info": {
          "fee": {
            "merchant_fee": {
              "sum": 10,
              "currency_code": "RUB"
            }
          }
        },
        "transaction_info": {
          "retrieval_ref_number": "425307614918",
          "authorization_code": "057441"
        }
      }]
    }
  }'

curl -X POST \
  https://partner.ru \
  -H 'Content-Type: application/json' \
  -H 'X-Signature: signature' \
  -d '{
    "type": "checkout_results",
    "session_info": {
      "id": "ps_3230",
      "transaction_status": "completed",
      "created_date": "2024-05-27T02:03:00.000000Z",
      "updated_at": "2024-05-27T02:03:00.000000Z",
      "payments": [{
        "id": "po_1234",
        "transaction_status": "successful",
        "created_date": "2024-05-27T02:03:00.000000Z",
        "user_info": {
          "user_id": "user123",
          "contact_info": [{
            "email_address": "user@gmail.com"
          }]
        },
        "payment_info": {
          "type": "account_info",
          "account_info": {
            "payment_system": "fps_info_verification",
            "fps_info_verification": {
              "phone_number": "79261234567",
              "bank_identifier": "100000000069"
            }    
          }
        },
        "sum_info": {
          "sum": 10000,
          "currency_code": "rub"
        },
        "fee_info": {
          "fee": {
            "merchant_fee": {
              "sum": 10,
              "currency_code": "RUB"
            }
          }
        },
        "transaction_info": {
          "retrieval_ref_number": "425307614918",
          "authorization_code": "057441"
        }
      }]
    }
  }'

`checkout_refunded`

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

Вебхук отправляется в следующих случаях:

если вы сделали возврат с помощью метода transaction/refund,
в рамках процедуры chargeback.

Если возврат сделан в рамках процедуры chargeback, в объекте moneyback вы увидите дополнительную строку: "chargeback": true.

Параметры

Название	Обязательность	Тип	Описание
`type`	+	string	Тип вебхука: `checkout_refunded`
`session_info`	+	object	Платежная сессия

Примеры

Выплата
Платеж

curl - X POST \
  https: //partner.ru \
  -H 'Content-Type: application/json' \ -
  -H 'X-Signature: signature' \ -
  -d '{
    "type": "checkout_refunded",
    "session_info": {
      "id": "ps_3230",
      "transaction_status": "completed",
      "created_date": "2024-05-27T02:03:00.000000Z",
      "updated_at": "2024-05-27T02:03:00.000000Z",
      "payouts": [{
        "id": "pm_2705",
        "transaction_status": "successful",
        "created_date": "2024-05-27T02:03:00.000000Z",
        "completed_date": "2024-05-27T02:03:00.000000Z",
        "user_info": {
          "user_id": "lucky"
        },
        "payout_info": {
          "type": "card_info",
          "card_info": {
            "card_network": "visa",
            "card_last4": "4242",
            "card_bin":"444600"
          }
        },
        "sum_info": {
          "sum": 1000,
          "currency_code": "rub"
        },
        "fee_info": {
          "fee": {
            "merchant_fee": {
              "sum": 10,
              "currency_code": "RUB"
            }
          }
        },
        "transaction_info": {
          "retrieval_ref_number": "425307614918",
          "authorization_code": "057441"
        },
        "extra_info": "good",
        "moneyback": [{
          "id": "rf_203",
          "transaction_status": "repaid",
          "created_date": "2024-05-27T02:03:00.000000Z",
          "completed_date": "2024-05-27T02:03:00.000000Z",
          "chargeback": true,
          "sum_info": {
            "sum": 1000,
            "currency_code": "rub"
          },
          "transaction_info": {
            "retrieval_ref_number": "425307614918",
            "authorization_code": "057441"
          }
        }]
      }]
    }
  }'

curl - X POST \
  https: //partner.ru \
  -H 'Content-Type: application/json' \ -
  -H 'X-Signature: signature' \ -
  -d '{
    "type": "checkout_refunded",
    "session_info": {
      "id": "ps_3230",
      "transaction_status": "completed",
      "created_date": "2024-05-27T02:03:00.000000Z",
      "updated_at": "2024-05-27T02:03:00.000000Z",
      "payments": [{
        "id": "pm_2705",
        "transaction_status": "successful",
        "created_date": "2024-05-27T02:03:00.000000Z",
        "completed_date": "2024-05-27T02:03:00.000000Z",
        "user_info": {
          "user_id": "lucky"
        },
        "payment_info": {
          "type": "card_info",
          "card_info": {
            "card_network": "visa",
            "card_last4": "4242",
            "card_bin":"444600"
          }
        },
        "sum_info": {
          "sum": 1000,
          "currency_code": "rub"
        },
        "fee_info": {
          "fee": {
            "merchant_fee": {
              "sum": 10,
              "currency_code": "RUB"
            }
          }
        },
        "transaction_info": {
          "retrieval_ref_number": "425307614918",
          "authorization_code": "057441"
        },
        "extra_info": "good",
        "moneyback": [{
          "id": "rf_203",
          "transaction_status": "completed",
          "created_date": "2024-05-27T02:03:00.000000Z",
          "completed_date": "2024-05-27T02:03:00.000000Z",
          "chargeback": true,
          "sum_info": {
            "sum": 1000,
            "currency_code": "rub"
          },
          "transaction_info": {
            "retrieval_ref_number": "425307614918",
            "authorization_code": "057441"
          }
        }]
      }]
    }
  }'

`finalization_pending`

Zetplat отправляет этот вебхук при холдировании. Это значит, что деньги для оплаты заморожены на банковской карте пользователя. Их можно списать сразу или через некоторое время.

Подтвердить — с помощью запроса transaction/finalize.
Отменить — с помощью запроса transaction/cancel.

Параметры

Название	Обязательность	Тип	Описание
`type`	+	string	Тип вебхука: `finalization_pending`
`session_info`	+	object	Платежная сессия

Пример

curl -X POST \
  https://partner.ru \
  -H 'Content-Type: application/json' \
  -H 'X-Signature: signature' \
  -d '{
    "type": "finalization_pending",
    "session_info": {
      "id": "ps_3230",
      "transaction_status": "active",
      "created_date": "2024-05-27T02:03:00.000000Z",
      "updated_at": "2024-05-27T02:03:00.000000Z",
      "next_step": "finalize",
      "payments": [{
        "id": "pm_1313",
        "transaction_status": "pending",
        "created_date": "2024-05-27T02:03:00.000000Z",
        "user_info": {
          "user_id": "user123",
          "contact_info": [{
            "email_address": "user@gmail.com"
          }]
        },
        "payment_info": {
          "type": "card_info",
          "card_info": {
            "card_last4": "4242",
            "card_network": "visa"
          }
        },
        "sum_info": {
          "sum": 10000,
          "currency_code": "rub"
        },
        "fee_info": {
          "fee": {
            "merchant_fee": {
              "sum": 10,
              "currency_code": "RUB"
            }
          }
        },
        "extra_info": "good"
      }]
    }
  }'

`approve_pending`

Zetplat отправляет этот вебхук, когда готов провести операцию — выплату или платеж. Проверьте данные операции, а затем подтвердите или отмените ее:

Подтвердить — с помощью запроса transaction/approve.
Отменить — с помощью запроса transaction/cancel.

к сведению

Для вашего удобства можно настроить автоподтверждение платежной сессии и обойтись без получения вебхука approve_pending с последующим его подтверждением. Для настройки автоподтверждения обратитесь к вашему менеджеру в Zetplat.

Параметры

Название	Обязательность	Тип	Описание
`type`	+	string	Тип вебхука: `approve_pending`
`session_info`	+	object	Платежная сессия

Примеры

Выплата
Платеж

curl -X POST \
  https://partner.ru \
  -H 'Content-Type: application/json' \
  -H 'X-Signature: signature' \
  -d '{
    "type": "approve_pending",
    "session_info": {
      "id": "ps_3230",
      "transaction_status": "active",
      "created_date": "2024-05-27T02:03:00.000000Z",
      "updated_at": "2024-05-27T02:03:00.000000Z",
      "next_step": "approve",
      "payouts": [{
        "id": "po_1234",
        "transaction_status": "pending",
        "created_date": "2024-05-27T02:03:00.000000Z",
        "user_info": {
          "user_id": "user123",
          "contact_info": [{
            "email_address": "user@gmail.com"
          }]
        },
        "payout_info": {
          "type": "card_info",
          "card_info": {
            "card_last4": "4242",
            "card_network": "visa"
          }
        },
        "sum_info": {
          "sum": 10000,
          "currency_code": "rub"
        },
        "fee_info": {
          "fee": {
            "merchant_fee": {
              "sum": 10,
              "currency_code": "RUB"
            }
          }
        },
        "extra_info": "good"
      }]
    }
  }'

curl -X POST \
  https://partner.ru \
  -H 'Content-Type: application/json' \
  -H 'X-Signature: signature' \
  -d '{
    "type": "approve_pending",
    "session_info": {
      "id": "ps_3230",
      "transaction_status": "active",
      "created_date": "2024-05-27T02:03:00.000000Z",
      "updated_at": "2024-05-27T02:03:00.000000Z",
      "next_step": "approve",
      "payments": [{
        "id": "pm_1313",
        "transaction_status": "pending",
        "created_date": "2024-05-27T02:03:00.000000Z",
        "user_info": {
          "user_id": "user123",
          "contact_info": [{
            "email_address": "user@gmail.com"
          }]
        },
        "payment_info": {
          "type": "card_info",
          "card_info": {
            "card_last4": "4242",
            "card_network": "visa"
          }
        },
        "sum_info": {
          "sum": 10000,
          "currency_code": "rub"
        },
        "fee_info": {
          "fee": {
            "merchant_fee": {
              "sum": 10,
              "currency_code": "RUB"
            }
          }
        },
        "extra_info": "good"
      }]
    }
  }'

Настройка получения вебхуков​

Требования к ответу​

Вебхуки Zetplat​

action_pending​

Параметры​

checkout_results​

Параметры​

checkout_refunded​

Параметры​

finalization_pending​

Параметры​

approve_pending​

Параметры​

Настройка получения вебхуков

Требования к ответу

Вебхуки Zetplat

`action_pending`

Параметры

`checkout_results`

Параметры

`checkout_refunded`

Параметры

`finalization_pending`

Параметры

`approve_pending`

Параметры