Payment Button - Hook

Custom payment buttons offer the ability to send notifications when a successful payment is made, this is achieved by configuring a hook.

Activate a Hook for a Payment Button

Activating a Hook takes only 2 steps:

Define the default API key that will be used for signing each Hook request and will secure the information been shared
Setup a URL to the one we will send out the notifications.

To use the Hook you must first create a Dynamic Payment Button: View tutorial

1. Define the API Key credentials for Hooks

To define the credentials head over to Settings > API Credentials


In the example above we can see a dropdown list of the options from where we will choose the credential that we will use as default for hooks.

2. Setup your systems URL

The second step is to setup the path to which requests will be made each time successful payments are received on a custom payment button. Some considerations to keep in mind:

It must be a public path (accessible from the Internet).
You must have a valid security certificate (path must use HTTPS).

To configure the URL, simply go into the settings of the payment button(s) in which you want to activate the Hook, click on edit and then on "Advanced Options".

Once in the Advanced Options you will find a field called "Hook URL" where you can place the route.

Technical Reference

When a Hook is activated, Fygaro will send a “POST” type request to the configured URL each time a successful payment is processed on the respective payment button. The request will have a JSON content type with the following structure::

{ "reference": (string), "customReference": (string), "createdAt": (int), "jwt": (string)}

"reference" contains the unique reference identifier that is assigned to every transaction in Fygaro.

"customReference" contains the dynamic reference assigned when creating or sharing the payment button by a URL parameter.

"createdAt" contains the timestamp that reflects the moment when the customer initiated the payment.

"jwt" contains a token in “Json Web Token” (JWT) format with the detailed information of the transaction.

*

Deprecated Fields:

Avoid using them, they will be eliminated in a future release.

"transactionReference" contains the "auth code" provided by the acquiring bank (if available).  It's recommended to use the field "reference" as the unique identifier instead.

The JWT format will allow you to guarantee the integrity and source of the information provided thanks to the signature that is created using the credential defined in the previous chapter. For more information on the format, you can visit: https://jwt.io/.

Before obtaining the information contained within the JWT, it is recommended to validate it using the previously defined credentials. Once it is determined valid, you can access the body of the token, where you will find the following information:

{ "reference": (string), "customReference": (string),    "authCode": (string),    "currency": (string),    "amount": (string),     "gratuity_amount": (string),    "createdAt": (int),    "clientData": (dict),      "transactionId": (string)}

"reference" is a validated copy of the field described above.

"customReference" is a validated copy of the field described above.

"authCode" contains the "auth code" provided by the acquiring bank. If not available, the field contains the value null.

"createdAt" is a validated copy of the field described above.

“currency” contains the 3-character ISO alphabetic code that represents the currency used in the payment (ex: “USD”).

"amount" contains the amount of the transaction in “Decimal” format of up to 2 characters.

"gratuity_amount" (if available) contains the tip or gratuity amount of the transaction in “Decimal” format of up to 2 characters.

"transactionId" is a UUID the identifies the transaction.

"clientData" is a dictionary that contains the information of the customer who made the purchase. Its structure is as follows:

{    "name": (string),    "email": (string),     "phone": (string)}

"name": name and surname entered by the customer when making the payment.

"email": Email entered by the customer when making the payment.

"phone": Telephone entered by the customer when making the payment.

*

Deprecated Fields:

Avoid using them, they will be eliminated in a future release.

"transactionReference" is a validated copy of the field described above.  It's recommended to use the "reference" field (unique identifier) and the "authCode" field ("auth code" from the acquiring bank, if available) instead.

Hook Response

Requests made to the requested URL await a successful response using status 200. Any other response or time-out status will be considered a failure and the request will be retried later.

A single request will be attempted up to 4 times, each attempt taking longer to break than the last to allow your system to recover from errors or crashes.

Please note that multiple consecutive failed requests may cause a temporary suspension of sending new requests for the same payment button. Repetitive suspensions can cause a permanent hook lock.

Updated on: 02/27/2025