Creare una dilazione

Introduzione

Per attivare una dilazione o un pagamento è necessario prima inviare una richiesta di dilazione, quindi reindirizzare l'utente al gateway di pagamento con l'identificativo della dilazione ricevuto, passando un URL di ritorno. Il gateway reindirizzerà all'URL inviato per gestire il ritorno del pagamento.

Inviare una richiesta di dilazione

L'endpoint chiede l'avviamento della dilazione e ritorna l'identificativo per il reindirizzamento.

Richiesta Http

POST https://api.jatapay.it/scrivi_dilazione

Parametri

Parametro	Richiesto	Tipo	Descrizione
importo	Sì	int	L'importo totale della dilazione espresso in centesimi di Euro
rate	Sì	int	Il numero di rate della dilazione
callback_url	Sì	string	Un URL valido per il ritorno del pagamento
descrizione_prodotto	Sì	string	La descrizione del prodotto
cliente	Sì	string	L'identificativo di un cliente esistente, oppure open per far compilare i dati al cliente sul gateway di pagamento
data_inizio	No	string	La data di inizio della dilazione in formato AAAA-MM-GG (default: oggi)
tipo	No	string	La tipologia della dilazione, attualmente credit
payment_method	No	string	Il metodo di pagamento: card per il pagamento con carta, sdd per SEPA Direct Debit
differenziate	No	boolean	Abilita rate a importi differenti, obbligatorio insieme a dettaglio_rate
dettaglio_rate	No	int[]	L'importo di ogni rata espresso in centesimi, la lunghezza dell'array deve essere uguale al numero di rate, obbligatorio per rate differenziate
consenso_debit	No	boolean	Abilita l'accettazione delle carte di debito e/o prepagate; non obbligatorio, il valore predefinito è false
external_vendor_id	No	string	L'identificativo della pratica nel tuo gestionale
metadata	No	object	Un oggetto di valori personalizzati restituito nelle risposte e nei webhook
note	No	string	Delle note descrittive per la dilazione

shell

curl "https://api.jatapay.it/scrivi_dilazione" \
 -H "Authorization: Bearer IL_TOKEN_DI_ACCESSO" \
 -H "Content-Type: application/json" \
 -d '{
   "importo": 2000,
   "rate": 2,
   "callback_url": "https://e-commerce.example.com/callback_url",
   "note": "Dilazione per motivo esempio",
   "cliente": "open",
   "descrizione_prodotto": "Descrizione del prodotto"
 }'

PHP

$dati_dilazione = array(            
           'importo' => 2000, //Importo in centesimi di euro
           'rate' =>  (int)2 //Numero di rate, 
           'callback_url' => 'https://e-commerce.example.com/callback_url',
           'note' => 'Dilazione per motivo esempio',
           'cliente' => 'open',
           'descrizione_prodotto' => 'Descrizione del prodotto'
         );

   $url = curl_init("https://api.jatapay.it/scrivi_dilazione");
   $authorization = "Authorization: Bearer ".$token;
   curl_setopt($url, CURLOPT_CUSTOMREQUEST, "POST");
   curl_setopt($url, CURLOPT_POSTFIELDS, json_encode($dati_dilazione));
   curl_setopt($url, CURLOPT_RETURNTRANSFER, true);
   curl_setopt($url, CURLOPT_HTTPHEADER, array(
     'Content-Type: application/json',
     'Content-Length: ' . strlen(json_encode($dati_dilazione)),
     $authorization
   ));

   $result = curl_exec($url);

   $api_response = json_decode($result);

   curl_close($url);

Python

import requests
import json

dati_dilazione = {
    'importo': 2000,  # Importo in centesimi di euro
    'rate': 2,  # Numero di rate
    'callback_url': 'https://e-commerce.example.com/callback_url',
    'note': 'Dilazione per motivo esempio',
    'cliente': 'open',
    'descrizione_prodotto': 'Descrizione del prodotto'
}

url = "https://api.jatapay.it/scrivi_dilazione"
token = "your_access_token"  # il tuo token
authorization = "Bearer " + token

headers = {
    'Content-Type': 'application/json',
    'Authorization': authorization
}

response = requests.post(url, data=json.dumps(dati_dilazione), headers=headers)

api_response = response.json()

print(api_response)

Node.js

const token = 'IL_TOKEN_DI_ACCESSO';

const body = {
  importo: 2000, // Importo in centesimi di euro
  rate: 2, // Numero di rate
  callback_url: 'https://e-commerce.example.com/callback_url',
  note: 'Dilazione per motivo esempio',
  cliente: 'open',
  descrizione_prodotto: 'Descrizione del prodotto'
};

const response = await fetch('https://api.jatapay.it/scrivi_dilazione', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
});

console.log(response.status, await response.json());

Go

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	const token = "IL_TOKEN_DI_ACCESSO"

	body := `{
  "importo": 2000,
  "rate": 2,
  "callback_url": "https://e-commerce.example.com/callback_url",
  "note": "Dilazione per motivo esempio",
  "cliente": "open",
  "descrizione_prodotto": "Descrizione del prodotto"
}`

	req, err := http.NewRequest("POST", "https://api.jatapay.it/scrivi_dilazione", strings.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	data, err := io.ReadAll(res.Body)
	if err != nil {
		panic(err)
	}

	fmt.Println(res.StatusCode, string(data))
}

.NET

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        const string token = "IL_TOKEN_DI_ACCESSO";

        var body = """
            {
              "importo": 2000,
              "rate": 2,
              "callback_url": "https://e-commerce.example.com/callback_url",
              "note": "Dilazione per motivo esempio",
              "cliente": "open",
              "descrizione_prodotto": "Descrizione del prodotto"
            }
            """;

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

        var content = new StringContent(body, Encoding.UTF8, "application/json");
        var response = await client.PostAsync("https://api.jatapay.it/scrivi_dilazione", content);

        Console.WriteLine((int)response.StatusCode);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String token = "IL_TOKEN_DI_ACCESSO";

        String body = """
                {
                  "importo": 2000,
                  "rate": 2,
                  "callback_url": "https://e-commerce.example.com/callback_url",
                  "note": "Dilazione per motivo esempio",
                  "cliente": "open",
                  "descrizione_prodotto": "Descrizione del prodotto"
                }
                """;

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api.jatapay.it/scrivi_dilazione"))
                .header("Authorization", "Bearer " + token)
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(body))
                .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
                .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}

Il comando ritornerà un JSON con questa struttura:

{
    "app": false,
    "id_dilazione": "6aec4cd9010c3c59f018f590",
    "link_to_pay": false,
    "payment_url": "https://react.jatapay.it/gateway/6aec4cd9010c3c59f018f590"
}

Risposta

Campo	Tipo	Descrizione
app	boolean	Indica se la richiesta arriva da un client applicativo interno (flag riservato)
id_dilazione	string	L'identificativo della dilazione appena creata
link_to_pay	boolean	Indica se la dilazione è stata creata come link di pagamento condivisibile
payment_url	string	L'URL a cui reindirizzare l'utente per completare il pagamento

warning

La richiesta deve avere l'header Content-Type: application/json e includere il parametro nel corpo del JSON e l'header Authorization: Bearer token

Reindirizzare l'utente al gateway di pagamento

Una volta creata la dilazione bisogna reindirizzare l'utente all'URL restituito nel campo payment_url della risposta:

https://react.jatapay.it/gateway/ID_DELLA_DILAZIONE

L'utente completerà il processo di pagamento e sarà reindirizzato all'url passato in precedenza.

Gestire il ritorno del pagamento

In qualunque momento sarà possibile recuperare le informazioni sulla dilazione per il controllo dell'avvenuta attivazione della stessa.

GET https://api.jatapay.it/entity/dilazioni/ID_DELLA_DILAZIONE

warning

Sostituire ID_DELLA_DILAZIONE con l'id ottenuto in precedenza

Lo stato dilazione 'attiva' indica l'accettazione della dilazione

shell

   curl "https://api.jatapay.it/entity/dilazioni/ID_DELLA_DILAZIONE" \
 -H "Authorization: Bearer IL_TOKEN_DI_ACCESSO"

PHP

$urlstring = "https://api.jatapay.it/entity/dilazioni/".$_GET['id_dilazione'];
   $url = curl_init($urlstring);
   $authorization = "Authorization: Bearer ".$token;
   curl_setopt($url, CURLOPT_CUSTOMREQUEST, "GET");
   curl_setopt($url, CURLOPT_RETURNTRANSFER, true);
   curl_setopt($url, CURLOPT_HTTPHEADER, array(
     $authorization
   ));

   $result = curl_exec($url);
   curl_close($url);
   $api_response = json_decode($result);

Python

import requests
import cgi

form = cgi.FieldStorage()

id_dilazione = form.getValue('id_dilazione')
token = 'IL_TUO_TOKEN'
headers = {"Authorization": "Bearer " + token}
url = 'https://api.jatapay.it/entity/dilazioni/' + id_dilazione
response = requests.get(url,headers=headers)
if response.status_code == 200:
  response = response.json()
else:
  print('Error, ' + str(response.status_code))

Node.js

const token = 'IL_TOKEN_DI_ACCESSO';
const idDilazione = 'ID_DELLA_DILAZIONE';

const response = await fetch(`https://api.jatapay.it/entity/dilazioni/${idDilazione}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const data = await response.json();
console.log(response.status, data);

Go

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	const token = "IL_TOKEN_DI_ACCESSO"
	idDilazione := "ID_DELLA_DILAZIONE"

	req, err := http.NewRequest("GET", "https://api.jatapay.it/entity/dilazioni/"+idDilazione, nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+token)

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	data, err := io.ReadAll(res.Body)
	if err != nil {
		panic(err)
	}

	fmt.Println(res.StatusCode, string(data))
}

.NET

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        const string token = "IL_TOKEN_DI_ACCESSO";
        const string idDilazione = "ID_DELLA_DILAZIONE";

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

        var response = await client.GetAsync($"https://api.jatapay.it/entity/dilazioni/{idDilazione}");

        Console.WriteLine((int)response.StatusCode);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String token = "IL_TOKEN_DI_ACCESSO";
        String idDilazione = "ID_DELLA_DILAZIONE";

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api.jatapay.it/entity/dilazioni/" + idDilazione))
                .header("Authorization", "Bearer " + token)
                .GET()
                .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
                .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}

Il comando ritornerà un JSON con questa struttura:

{
    "_id": "ID_DELLA_DILAZIONE",
    "base": 0, //questo è il valore base della dilazione qualora si usassero rate differenziate
    "callback_url":"https://my-ecommerce.example.com/callback_url", //il callback_url massato in precedenza
    "carta": "6dasde43eww6c4039f27", //l'identificativo della carta del cliente
    "client": "JataPay", 
    "cliente": "5f12321was23e3ec1422", //l'identificativo del cliente
    "contratto": {
        "pdf": "6065ef23se35d684823ec387", //l'identificativo del contratto di dilazione
    },
    "data_fine": "Sat, 01 May 2021 18:05:04 GMT", //la data fine della dilazione
    "data_inizio": "Thu, 01 Apr 2021 18:05:04 GMT", //la data inizio della dilazione
    "data_inserimento": "Thu, 01 Apr 2021 16:05:06 GMT", //la data inserimento della dilazione
    "date_differenziate": false,
    "esercente": "6022a3c41bsa3653fsib044", //il vostro identificativo
    "importo": 200, //l'importo in centesimi di euro
    "metadata": null, 
    "note": "", //le note inserite
    "numero": 526, //il numero della dilazione    
    "rate": 2,
    "rate_differenziate": false, //se la dilazione ha o meno rate differenziate
    "stato": "attiva", //lo stato della dilazione
    "tipo": "credit", //il tipo 

}

Ricevere il webhook

In alternativa al polling puoi ricevere una notifica HTTP POST quando lo stato cambia, senza dover interrogare le API.

Il webhook si configura dalla Dashboard nella sezione Sviluppatori oppure via API con l'endpoint POST /esercente/developer_options (vedi Opzioni sviluppatore).

Ogni notifica è firmata con il webhook_secret dell'esercente: vedi Webhook per il calcolo e la verifica della firma in tutti i linguaggi.