Manage webhooks

Description

Webhooks enable you to be notified of an event such as a payment status change in real-time.
They are configured in the Console in your application and take 4 parameters:

urlThe URL where you will listen to Fintecture webhooks and process the resulting message
content-typeEither application/x-www-form-urlencoded (default) or application/json
offsetThe delay in minutes when you post the webhook to be called after an event happened
eventThe list of events to which you want the webhook to be called

A webhook is an application/x-www-form-urlencoded or application/json POST request which is signed using your application privately-kept public key (private asymmetric keys).

🚧 Important

Verify the signature using your private key, and only then process the order based on the result of the payment.

POST /webhook HTTP/1.1
Host: mywebsite.com
Signature: keyId="2dfdcf57-5b2f-4309-846f-913d0b2802cf",algorithm="rsa-sha256",headers="date digest x-request-id",signature="h0V0SUbjRhLEP/MiYo0Mgs1N17EuCEmKyQrDjxysc7iSiFXTjvY6qVEoaiRkzB8ZI0J39gGwOtTXN9CJPVRbhEHhi9Z9rQvM33FkygXvvx8BwM76fSTQ2/BSZWx04CjbPv/XUVusnkKVr3W6p+Vn073hAuJn1nKCvDOyl+QnDtstkzT+UacVzDA9L9nyPbbaPQHJobaZuG8TjhnI+Y0PZxneke6OU6fcdPT0uwkEamDOOExcMryHIX1iH5iiPMvLoVA8acqvvMSDYar0rlEQ2J1M4dcowWT8FxLo6C8uqvJIaBYm7Ze0RNJOwY0UBImCVDIuQLJuBjPwjQT5GjTQlg==
Digest: SHA-256=wOtTXN9CJPVRbhEHhi9Z9rQvM33FkygXvvx8BwM76fS
Date: Mon, 08 Jun 2020 23:11:23 GMT
X-Request-ID: 88c414df-6895-48db-8ef3-1fd1ce4272c6
Content-Type: application/x-www-form-urlencoded
session_id=b2bca2bcd3b64a32a7da0766df59a7d2&status=payment_created&customer_id=1ef74051a77673de120820fb370dc382&provider=bnpafr&state=mystate&event=payment_session.status.payment_created

🚧 Important

Webhook will retry 10x with an exponential time increment if your sever doesn't respond with a HTTP code in the 2XX range.

🚧 Important

Webhooks have a timeout time of 20 seconds. If your server doesn't answer in less than 20 seconds we timeout and retry later.

πŸ’‘ Note

Payment Sessions of type IncomingTransfer will not necessarily contain a reference which maps to an order thus consider whether you should filter out these payment sessions during your integration by returning a dedicated HTTP response status code such as 202.

Attributes

The following attributes are included in the application/x-www-form-urlencoded webhooks. These attributes are only sent if they are populated with a value.

attributeeventdescription
session_idallThe unique identifier of the payment session
customer_idallThe unique customer ID which did the payment
providerallThe financial provider which was used to process the payment
stateallThe state which was sent on the redirection request
eventallThe event which was just triggered
statuspayment_session.statusThe status of the payment session
refund_statuspayment_session.refund_statusThe status of the refund from the original payment
refunded_session_idpayment_session.refund_statusThe session ID of the original payment session which is being refunded
transfer_statepayment_session.status, payment_session.transfer_states, payment_session.received_amountThe payment session transfer state
transfer_reasonpayment_session.status, payment_session.transfer_states, payment_session.received_amountDetails about the payment session transfer_state
typepayment_session.status, payment_session.received_amount
The payment session type
PayByBank,RequestToPay,Refund,
RequestForPayout,Payout,BuyNowPayLater,
ManualTransfer,IncomingTransfer
amountpayment_session.status, payment_session.received_amountThe payment session amount
received_amountpayment_session.status, payment_session.received_amountThe total amount received on this payment session
transaction_amountpayment_session.status, payment_session.received_amountThe amount of the latest transaction related to the payment session

πŸ’‘ Note

The order of attributes will not change. More attributes can be appended at the end.