Do you need to integrate your online payment system with us? With this guide, we will help you integrate it step by step.
First of all, keep in mind that this guide is focused for advanced technical users. If you do not have these skills, you can contact a trusted technician to do the implementation.
It is also important to note that this integration can only be done if you have a server that can accept HTTP calls and responses.
Talonarium offers the service of integrating an online payment system in a generic way. With this, we want to emphasize that we cannot guarantee compatibility with all online payment systems in the market.
Before anything, WE RECOMMEND that you first take a look at this guide to analyze if the integration is possible.
In the following diagram, we can see the different required components and how they interact:
Once the buyer has added all the items to the shopping cart, the 'Go to Payment' button is enabled. When clicked, Talonarium automatically communicates with your server sending all order data and waiting for a web link that will redirect the buyer to the online POS page.
When the buyer is directed to the payment page, he can make the payment with the configured methods. It is important to note that Talonarium does not charge any fee. If there are fees, they depend on the chosen online payment system.
If the payment has been correctly validated by the POS, Talonarium must be notified so that the order becomes valid.
Once the payment is completed and Talonarium has received notification that everything is good, the online payment system can redirect the buyer to a confirmation page, where all the details of the order are displayed.
As previously mentioned, when the buyer clicks on the 'Go to Payment' button, Talonarium automatically communicates with your server to provide the web link.
This communication is made through an HTTP request of type POST to your server. It is necessary to configure the URL of this endpoint by entering the Talonarium application, within the POS configuration for an organizer group.
POST: https://your-server.com/payment-linkTalonarium sends the following information in the JSON body:
{
"paymentIntentId": "63ac23b439eaa500258b84fc",
"price": 15,
"currency": "EUR",
"customerName": "Jean Warner",
"customerEmail": "[email protected]",
"customerLocale": "EN",
"eventTitle": "Music festival in the beach",
"organizerName": "BCN events",
"tickets": [
{
"customerName": "Katerina Dean",
"priceCategory": "vip",
"price": 10
},
{
"customerName": "Rachel Macias",
"priceCategory": "default",
"price": 5
}
]
}At this time, your server must ask the online payment system to generate a payment link with the obtained data and then, return it as a response to the Talonarium's request with the following JSON structure:
{
"paymentLink": "https://your-tpv-payment-link"
}The payment link should be in HTTPS format. Once Talonarium receives the payment link, it automatically redirects the buyer to this page to make the payment.
When the buyer makes the payment, Talonarium needs to know that it has been made correctly. Therefore, your server must notify us that everything is good. In general, online payment systems allow the configuration of a webhook when a payment has been made.
*IMPORTANT: It is necessary to notify Talonarium of the validity of the payment. If it is not notified, the order is considered invalid.
To make this notification, we must make the following POST HTTP request and these data in the JSON body:
POST: https://api.talonarium.com/v1/tpv-wh/payment-validate{
"paymentIntentId": "63ac23b439eaa500258b84fc",
"secretKey": "xxx"
}The secretKey is a private security key that can be generated from the organizer's POS configuration section in the app. Your server must return it along with the paymentIntentId.
Depending on the used POS, we can redirect the buyer to the order confirmation page.
