Webhooks
Webhooks are notifications about events happening on Bank 131's side. The Bank sends webhooks to inform you of the results of your operations, ask for confirmation, or alert you about actions you need to take.
How to obtain webhooks
- In your system, create an address to receive webhooks at.
- Inform your Bank 131 manager of this address.
- Let your manager know which webhooks you will need (this depends on how you'll be using the API). By default, you will only receive mandatory webhooks.
What to send in response
Bank 131 waits for you to send the 200 HTTP code in response to any webhook.
If the Bank receives a 4** or 5** code, the request will be resent repeatedly at intervals of increasing length until it gets a response.
ready_to_confirm
The bank is waiting for your confirmation to perform the operation (mandatory)
Bank 131 sends this webhook when it is ready to perform an operation (a payment or a payout). You need to check the operation parameters and make a decision. If everything looks good, confirm the operation by sending a confirm_request to Bank 131. If something is not right, cancel the operation by sending a cancel_request to Bank 131.
Notification parameters
| Name | Mandatory | Type | Description |
|---|---|---|---|
| type | + | string | Webhook type: ready_to_confirm |
| session | + | PaymentSession | The payment session |
| confirm_information | - (mandatory only for the trasactions with a nominal account) | ConfirmInformation | Transaction confirmation information |
Webhook example: using ready_to_confirm to confirm a payout
curl -X POST \
https://partner.ru \
-H 'content-type: application/json' \
-H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
-d '{
"type": "ready_to_confirm",
"session": {
"id": "3230",
"status": "in_progress",
"created_at": "2018-05-27T02:03:00.000000Z",
"updated_at": "2018-05-27T02:03:00.000000Z",
"next_action": "confirm",
"payments": [
{
"id": "2018",
"status": "pending",
"created_at": "2018-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"
},
"metadata": "good"
}
]
}
}'
Webhook example: using ready_to_confirm to perform a payment
curl -X POST \
https://partner.ru \
-H 'content-type: application/json' \
-H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
-d '{
"type": "ready_to_confirm",
"session": {
"id": "3230",
"status": "in_progress",
"created_at": "2018-05-27T02:03:00.000000Z",
"updated_at": "2018-05-27T02:03:00.000000Z",
"acquiring_payments": [
{
"id": "2018",
"status": "pending",
"created_at": "2018-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"
},
"metadata": "good"
}
]
}
}'
payment_finished
The Bank informs you of the result of an operation (mandatory)
The Bank sends this webhook to you when it has completed an operation (a payment or a payout). The webhook body contains all the details of the operation, including its status (in the status field). For example, if you are sending a payout and have received the succeeded status in this webhook, it means that the payout has been completed successfully.
Notification parameters
| Name | Mandatory | Type | Description |
|---|---|---|---|
| type | + | string | Webhook type: payment_finished |
| session | + | PaymentSession | The payment session |
Webhook example: payment_finished
curl -X POST \
https://partner.ru \
-H 'content-type: application/json' \
-H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
-d '{
"type": "payment_finished",
"session": {
"id": "3230",
"status": "accepted",
"created_at": "2018-05-27T02:03:00.000000Z",
"updated_at": "2018-05-27T02:03:00.000000Z",
"payments": [
{
"id": "2018",
"status": "succeeded",
"created_at": "2018-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"
},
"metadata": "good"
}
]
}
}'
action_required
The Bank is waiting for you or your users to take the necessary action (optional)
The Bank sends this webhook to you when you or your users need carry out certain actions to proceed with the operation. For example, a user might need to go through 3-D Secure authentication when paying via bank card.
Webhook parameters
| Name | Mandatory | Type | Description |
|---|---|---|---|
| type | + | string | Webhook type: action_required |
| session | + | PaymentSession | The payment session |
Webhook example: action_required
curl -X POST \
https://partner.ru \
-H 'content-type: application/json' \
-H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
-d '{
"type": "action_required",
"session": {
"id": "3230",
"status": "in_progress",
"created_at": "2018-05-27T02:03:00.000000Z",
"updated_at": "2018-05-27T02:03:00.000000Z",
"acquiring_payments": [{
"id": "131",
"status": "pending",
"created_at": "2018-05-27T02:03:00.000000Z",
"customer": {
"reference":"user@131.ru"
},
"payment_details": {
"type": "card",
"card": {
"brand": "visa",
"last4": "8801"
}
},
"amount_details": {
"amount": 15000,
"currency": "rub"
},
"customer_interaction": {
"type": "redirect",
"redirect": {
"url": "https://bank131.ru?foo=bar",
"base_url": "https://bank131.ru"
"method": "POST",
"qs": {
"foo": "bar"
},
"params": {
"paReq": "sdfew^//asdhbv",
"MD": "abc75daefnn"
}
}
}
}]
}
}
}'
ready_to_capture
The bank informs you that the money has been put on hold (optional)
Bank 131 sends this webhook to you when putting money on hold, after the first step of a payment performed in two stages. This means that the amount has been put on hold successfully, and the Bank is waiting for your next command. To debit the money, send the session/capture request. To cancel the payment, send the session/cancel request.
Webhook parameters
| Name | Mandatory | Type | Description |
|---|---|---|---|
| type | + | string | Webhook type: ready_to_capture |
| session | + | PaymentSession | The payment session |
Webhook example: ready_to_capture
curl -X POST \
https://partner.ru \
-H 'content-type: application/json' \
-H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
-d '{
"type": "ready_to_capture",
"session": {
"id": "3230",
"status": "in_progress",
"created_at": "2018-05-27T02:03:00.000000Z",
"updated_at": "2018-05-27T02:03:00.000000Z",
"acquiring_payments": [
{
"id": "2018",
"status": "pending",
"created_at": "2018-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"
},
"metadata": "good"
}
]
}
}'
payment_refunded
Bank 131 informs you of the result of a refund
Bank 131 sends this webhook to you after performing a refund. The notification parameters contain information about the payment session, including all the information about the refunds.
The webhook is sent in the following cases:
- you made a refund using the method
session/refund - the recipient's bank returned a payment sent to a Russian bank account.
Webhook parameters
| Name | Mandatory | Type | Description |
|---|---|---|---|
| type | + | string | The hook's name. payment_refunded |
| session | + | PaymentSession | The payment session |
Webhook example: payment_refunded
curl - X POST\
https: //partner.ru \
-H 'Content-Type: application/json'\ -
H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc'\ -
d '{
"type": "payment_refunded",
"session": {
"id": "ps_3230",
"status": "accepted",
"created_at": "2018-05-27T02:03:00.000000Z",
"updated_at": "2018-05-27T02:03:00.000000Z",
"acquiring_payments": [{
"id": "pm_2705",
"status": "succeeded",
"created_at": "2018-05-27T02:03:00.000000Z",
"finished_at": "2018-05-27T02:03:00.000000Z",
"customer": {
"reference": "lucky"
},
"payment_details": {
"type": "card",
"card": {
"brand": "visa",
"last4": "4242"
}
},
"amount_details": {
"amount": 1000,
"currency": "rub"
},
"metadata": "good",
"refunds": [{
"id": "rf_203",
"status": "accepted",
"created_at": "2018-05-27T02:03:00.000000Z",
"finished_at": "2018-05-27T02:03:00.000000Z",
"amount_details": {
"amount": 1000,
"currency": "rub"
}
}]
}]
}
}'