Webservice api

Documentazione API: Endpoint `/checkout`

Endpoint:

POST https://api.posway.io/checkout

Metodo: POST

Autenticazione:

L’autenticazione avviene tramite header api_key. Assicurati di includere questo header in ogni richiesta.

api_key: YOUR_API_KEY

Sostituisci YOUR_API_KEY con la tua chiave API effettiva.

Header Richiesta:

Content-Type: application/json - Indica che il corpo della richiesta è in formato JSON.
api_key: YOUR_API_KEY - La tua chiave API per autenticare la richiesta.

Corpo della Richiesta (Request Body) - JSON:

Il corpo della richiesta deve essere un oggetto JSON con le seguenti proprietà:

Nome Parametro	Tipo	Obbligatorio	Descrizione	Esempio
`customer`	Oggetto	Sì	Dettagli del cliente.	`{ "name": "Test Customer", "email": "[email protected]" }`
`customerId`	Stringa	Condizionato	L’ID del cliente creato o recuperato.	`"cus_Ruu5qzk00bs1lt" - null se nuovo cliente`
`customer.name`	Stringa	Sì	Nome del cliente.	`"Test Customer"`
`customer.email`	Stringa	Sì	Email del cliente.	`"[email protected]"`
`products`	Array	Sì	Un array di oggetti che rappresentano i prodotti o servizi per cui il cliente sta effettuando il checkout.	`[{ "name": "Test Product 1", "prices": [...] }]`
`products[].productId`	Stringa	Condizionato	L’ID del prodotto creato o recuperato.	`"prod_Ru7t4T744gMSVo" - null se nuovo prodotto`
`products[].name`	Stringa	Sì	Nome del prodotto.	`"Test Product 1"`
`products[].prices`	Array	Sì	Un array di oggetti che definiscono i prezzi associati al prodotto. Un prodotto può avere più prezzi (es. pagamento una tantum e abbonamento).	`[{ "amount": 1000, "currency": "eur", "interval": "month" }, { "amount": 2000, "currency": "eur" }]`
`products[].prices[].priceId`	Stringa	Condizionato	L’ID del prezzo creato o recuperato.	`"price_1R14Hi4Y0rDkdD0j0wJm6iRC" - null se nuovo price`
`products[].prices[].amount`	Numero	Sì	L’ammontare del prezzo in centesimi (o la più piccola unità della valuta). Ad esempio, 1000 per 10.00 EUR.	`1000`
`products[].prices[].currency`	Stringa	Sì	La valuta del prezzo, in formato ISO 4217 (es. “eur”, “usd”).	`"eur"`
`products[].prices[].interval`	Stringa	Opzionale	Se presente, indica che si tratta di un prezzo ricorrente. Valori possibili: `day`, `week`, `month`, `year`. Se omesso, si assume un pagamento una tantum.	`"month"`
`trialPeriodDays`	Numero	Opzionale	Numero di giorni per il periodo di prova gratuito (se applicabile). Se `null` o omesso, non viene applicato un periodo di prova.	`null` / `30`
`metadata`	Oggetto	Opzionale	Metadati personalizzati che vuoi associare alla sessione di checkout. Questi metadati saranno disponibili negli eventi webhook.	`{ "transactionId": "testTxnMultiProduct", "orderId": "ORDER-1234" }`
`cancelAt`	Timestamp	Opzionale	Un timestamp Unix in secondi. Se fornito, indica la data e l’ora in cui la sottoscrizione dovrebbe essere cancellata automaticamente. Utile per creare abbonamenti a tempo determinato.	`1719878400`

Risposta (Response) - JSON:

In caso di successo (codice di stato HTTP 200), la risposta sarà un oggetto JSON con le seguenti proprietà:

Nome Parametro	Tipo	Descrizione	Esempio
`metadata`	Oggetto	I metadati che hai inviato nella richiesta.	`{ "transactionId": "testTxnMultiProduct", "orderId": "ORDER-1234" }`
`success`	Booleano	Indica se la chiamata API è andata a buon fine (`true`) o meno (`false`).	`true`
`customerId`	Stringa	L’ID del cliente creato o recuperato.	`"cus_Ruu5qzk00bs1lt"`
`sessionId`	Stringa	L’ID della sessione di Checkout creata.	`"cs_test_b1HGsZC682xkt7xU1g4GTFRfXK2b6MmXl6NBvR5VXrCoZ2JpY6MHMeDaWq"`
`url`	Stringa	L’URL a cui il cliente deve essere reindirizzato per completare il pagamento sulla pagina di checkout	`"https://pway.me/20d4b5"`
`products`	Array	Un array di oggetti che descrivono i prodotti, arricchito con informazioni aggiuntive come `productId` e `priceId`	`[{ "productId": "prod_Ru7t4T744gMSVo", "name": "Test Product 1", "prices": [{ "amount": 1000, "currency": "eur", "interval": "month", "priceId": "price_1R14Hi4Y0rDkdD0j0wJm6iRC" }, { "amount": 2000, "currency": "eur", "interval": "one_time", "priceId": "price_1R14Hi4Y0rDkdD0j9gfwXlHf" }] }]`
`products[].productId`	Stringa	L’ID del prodotto creato o recuperato.	`"prod_Ru7t4T744gMSVo"`
`products[].prices[].priceId`	Stringa	L’ID del prezzo creato o recuperato.	`"price_1R14Hi4Y0rDkdD0j0wJm6iRC"`

Esempio Richiesta (curl):

curl --location 'https://api.posway.io/checkout' \
--header 'Content-Type: application/json' \
--header 'api_key: YOUR_API_KEY' \
--data-raw '{
  "customer": {
  	"customer_id": null,
    "name": "Test Customer",
    "email": "[email protected]"
  },
  "products": [
    {
	  "product_id" : null,
      "name": "Test Product 1",
      "prices": [
        {
          "amount": 1000,
          "currency": "eur",
          "interval": "month"
        },
        {
          "amount": 2000,
          "currency": "eur"
        },
		{
          "price_id": price_xxxxxyyyyy
        }
      ]
    }
  ],
  "trialPeriodDays": null,
  "metadata": {
    "transactionId": "testTxnMultiProduct",
    "orderId": "ORDER-1234"
  },
  "cancelAt": 1719878400
}'

Esempio Risposta (JSON):

{
  "metadata": {
    "transactionId": "testTxnMultiProduct",
    "orderId": "ORDER-1234"
  },
  "success": true,
  "customerId": "cus_Ruu5qzk00bs1lt",
  "sessionId": "cs_test_b1HGsZC682xkt7xU1g4GTFRfXK2b6MmXl6NBvR5VXrCoZ2JpY6MHMeDaWq",
  "url": "https://pway.me/20d4b5",
  "products": [
    {
      "productId": "prod_Ru7t4T744gMSVo",
      "name": "Test Product 1",
      "prices": [
        {
          "amount": 1000,
          "currency": "eur",
          "interval": "month",
          "priceId": "price_1R14Hi4Y0rDkdD0j0wJm6iRC"
        },
        {
          "amount": 2000,
          "currency": "eur",
          "interval": "one_time",
          "priceId": "price_1R14Hi4Y0rDkdD0j9gfwXlHf"
        }
      ]
    }
  ]
}

Documentazione API: Endpoint `/subscription` (DELETE)