Перейти к основному содержимому

Вебхуки

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

Как получать вебхуки​

Чтобы начать получать вебхуки:

  1. Создайте адрес в вашей системе, на который хотите получать вебхуки.
  2. Передайте его менеджеру Pike.

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

к сведению

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

Что отправлять в ответ​

Pike ожидает, что в ответ на любой вебхук вы отправите HTTP-код 200.

Если в ответ Pike получит код 4** или 5**, то будет пытаться снова отправить вебхук следующим образом:

  • вебхуки отправляются с увеличивающимся интервалом (до 15 минут);
  • примерно через 30 минут Pike прекратит отправку вебхука.
к сведению

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

action_required​

Pike отправляет вам этот вебхук в случае, когда для продолжения операции вам или вашим пользователям нужно совершить какие-то действия. Например, пользователю необходимо пройти аутентификацию по 3-D Secure при платеже банковской картой.

Максимальное время ожидания действия — 60 минут. Если за это время действие не произошло, операция автоматически завершится в статусе canceled.

Параметры​

НазваниеОбязательностьТипОписание
type+stringТип вебхука: action_required
session+objectПлатежная сессия
Примеры
curl -X POST \
  https://partner.ru \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "type": "action_required",
    "session": {
      "id": "ps_3230",
      "status": "in_progress",
      "created_at": "2024-05-27T02:03:00.000000Z",
      "updated_at": "2024-05-27T02:03:00.000000Z",
      "acquiring_payments": [{
        "id": "pm_1313",
        "status": "pending",
        "created_at": "2024-05-27T02:03:00.000000Z",
        "customer": {
          "reference":"user@test.ru"
        },
        "payment_details": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "8801",
            "bin":"444600"
          }
        },
        "amount_details": {
          "amount": 15000,
          "currency": "rub"
        },
        "amounts": {
          "fee": {
            "merchant_fee": {
              "amount": 10,
              "currency": "RUB"
            }
          }
        },
        "transaction_info": {
          "rrn": "425307614918",
          "auth_code": "057441"
        },
        "customer_interaction": {
          "type": "redirect",
          "redirect": {
            "url": "https://pikepayments.com?foo=bar",
            "base_url": "https://pikepayments.com",
            "method": "POST",
            "qs": {
              "foo": "bar"
            },
            "params": {
              "PaReq": "sdfew^//asdhbv",
              "MD": "abc75daefnn"
            }
          }
        }
      }]
    }
  }'

payment_finished​

Pike отправляет этот вебхук, когда завершает операцию — оплату или выплату. В теле вебхука приходят все параметры операции, в том числе ее статус (в поле status). Например, если вы отправляете выплату и получили статус succeeded в этом вебхуке, значит, выплата прошла успешно.

Параметры​

НазваниеОбязательностьТипОписание
type+stringТип вебхука: payment_finished
session+objectПлатежная сессия
Примеры
curl -X POST \
  https://partner.ru \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "type": "payment_finished",
    "session": {
      "id": "ps_3230",
      "status": "accepted",
      "created_at": "2024-05-27T02:03:00.000000Z",
      "updated_at": "2024-05-27T02:03:00.000000Z",
      "payments": [{
        "id": "po_1234",
        "status": "succeeded",
        "created_at": "2024-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [{
            "email": "user@gmail.com"
          }]
        },
        "payment_method": {
          "type": "bank_account",
          "bank_account": {
            "system_type": "ru",
            "ru": {
              "bic": "*******02",
              "account": "****************5734",
              "full_name": "***",
              "description": "*****",
              "is_fast": false
            }    
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "amounts": {
          "fee": {
            "merchant_fee": {
              "amount": 10,
              "currency": "RUB"
            }
          }
        },
        "transaction_info": {
          "rrn": "425307614918",
          "auth_code": "057441"
        }
      }]
    }
  }'

payment_refunded​

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

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

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

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

Параметры​

НазваниеОбязательностьТипОписание
type+stringТип вебхука: payment_refunded
session+objectПлатежная сессия
Примеры
curl - X POST \
  https: //partner.ru \
  -H 'Content-Type: application/json' \ -
  -H 'X-PARTNER-SIGN: signature' \ -
  -d '{
    "type": "payment_refunded",
    "session": {
      "id": "ps_3230",
      "status": "accepted",
      "created_at": "2024-05-27T02:03:00.000000Z",
      "updated_at": "2024-05-27T02:03:00.000000Z",
      "payments": [{
        "id": "pm_2705",
        "status": "succeeded",
        "created_at": "2024-05-27T02:03:00.000000Z",
        "finished_at": "2024-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_method": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "4242",
            "bin":"444600"
          }
        },
        "amount_details": {
          "amount": 1000,
          "currency": "rub"
        },
        "amounts": {
          "fee": {
            "merchant_fee": {
              "amount": 10,
              "currency": "RUB"
            }
          }
        },
        "transaction_info": {
          "rrn": "425307614918",
          "auth_code": "057441"
        },
        "metadata": "good",
        "refunds": [{
          "id": "rf_203",
          "status": "accepted",
          "created_at": "2024-05-27T02:03:00.000000Z",
          "finished_at": "2024-05-27T02:03:00.000000Z",
          "is_chargeback": true,
          "amount_details": {
            "amount": 1000,
            "currency": "rub"
          },
          "transaction_info": {
            "rrn": "425307614918",
            "auth_code": "057441"
          }
        }]
      }]
    }
  }'

ready_to_capture​

Pike отправляет этот вебхук при холдировании — после первого этапа платежа, который проходит в две стадии. Это значит, что сумма успешно заморожена, а Pike ждет от вас команды. Чтобы списать деньги, отправьте запрос session/capture. Чтобы отменить оплату, отправьте session/cancel.

Параметры​

НазваниеОбязательностьТипОписание
type+stringТип вебхука: ready_to_capture
session+objectПлатежная сессия
Примеры
curl -X POST \
  https://partner.ru \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "type": "ready_to_capture",
    "session": {
      "id": "ps_3230",
      "status": "in_progress",
      "created_at": "2024-05-27T02:03:00.000000Z",
      "updated_at": "2024-05-27T02:03:00.000000Z",
      "next_action": "capture",
      "acquiring_payments": [{
        "id": "pm_1313",
        "status": "pending",
        "created_at": "2024-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [{
            "email": "user@gmail.com"
          }]
        },
        "payment_details": {
          "type": "card",
          "card": {
            "last4": "4242",
            "brand": "visa"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "amounts": {
          "fee": {
            "merchant_fee": {
              "amount": 10,
              "currency": "RUB"
            }
          }
        },
        "metadata": "good"
      }]
    }
  }'

ready_to_confirm​

Pike отправляет этот вебхук, когда готов провести операцию — выплату или платеж. Вам нужно проверить параметры операции и принять решение. Если всё в порядке, подтвердите операцию: отправьте session/confirm. Если что-то не так, отмените операцию: отправьте запрос session/cancel.

Максимальное время ожидания подтверждения — 240 минут. Если за это время подтверждение не получено, операция автоматически завершится в статусе canceled.

к сведению

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

Параметры​

НазваниеОбязательностьТипОписание
type+stringТип вебхука: ready_to_confirm
session+objectПлатежная сессия
Примеры
curl -X POST \
  https://partner.ru \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "type": "ready_to_confirm",
    "session": {
      "id": "ps_3230",
      "status": "in_progress",
      "created_at": "2024-05-27T02:03:00.000000Z",
      "updated_at": "2024-05-27T02:03:00.000000Z",
      "next_action": "confirm",
      "payments": [{
        "id": "po_1234",
        "status": "pending",
        "created_at": "2024-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [{
            "email": "user@gmail.com"
          }]
        },
        "payment_method": {
          "type": "card",
          "card": {
            "last4": "4242",
            "brand": "visa"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "amounts": {
          "fee": {
            "merchant_fee": {
              "amount": 10,
              "currency": "RUB"
            }
          }
        },
        "metadata": "good"
      }]
    }
  }'