Transactions · Platon API

Endpoint

POST /platon/transactions

Submit a structured POS transaction to generate and deliver a digital receipt. The receipt can include itemized product lines, VAT details per product, and one or more credit card payment records.

Example request

cURL

                                   }       }]     }],              }],       }   }'

d">curl --request POST \ '{BASE_URL}/platon/transactions' \ --header 'Authorization: Bearer {YOUR_API_TOKEN}' \ --header 'Content-Type: application/json' \ --data '{ "requestId": "0efc54d1-a04c-46f1-94d2-ee58fd740485", "amount": "37", "shopId": 1, "externalTransactionRef": "698547865872", "tillId": 1, "timezone": "Europe/Paris", "mode": "email", "currencySymbol": "€", "shopName": "Main Street", "shopStreet": "149 Av. de Bretagne", "shopCity": "Lille", "shopPostalCode": "59000", "receipts": [{ "products": [{ "name": "Keyboard", "price": "15", "quantity": "1", "genCode": "895471234", "family": "Electronics", "vat": { "label": "VAT 20%", "amount": "3", "rate": "20%" "creditCardPayments": [{ "cardNetwork": "VISA", "paymentDate": "2024-05-12", "paymentTime": "13:45", "merchantName": "Acme Corp", "maskedCardNumber": "*1234", "amount": "37", "currencySymbol": "€", "paymentType": "Credit" "customer": { "email": "customer@example.com"

Response

A successful request returns HTTP status 201 Created with an empty body, or a plain-text URL when the web receipt feature is enabled for your account. That URL points to a hosted page where customers can view and download their receipt.

When mode is email or email_and_print, an email is sent to the customer only if a valid email address is present in the customer.email field.

Delivery modes

Value	Description
`email`	Send the receipt by email to the customer. Requires a valid `customer.email`.
`print`	Generate a paper receipt at the POS terminal. No email is sent.
`email_and_print`	Send by email and generate a paper receipt simultaneously.
`no_print`	Record the transaction without delivering a receipt.

Request body reference

StructuredTransactionDTO

Field	Type	Required	Description
`requestId`	`string`	Yes	UUID v4 used for idempotency. Duplicate requests with the same value are ignored.
`mode`	`string`	Yes	Delivery mode. See Delivery modes.
`receipts`	`StructuredReceipt[]`	Yes	One or more receipts, each containing a list of products.
`amount`	`string`	No	Total transaction amount. May be negative (refund).
`shopId`	`number`	No	Internal shop identifier.
`externalTransactionRef`	`string`	No	Your own reference for this transaction.
`externalReceiptRef`	`string`	No	Your own reference for this receipt.
`tillId`	`number`	No	POS register or till identifier.
`transactionDate`	`string`	No	ISO 8601 date string of when the transaction occurred.
`timezone`	`string`	No	IANA timezone name (e.g. `Europe/Paris`).
`currencySymbol`	`string`	No	Currency symbol (`€`, `$`) or ISO code (`EUR`).
`companyName`	`string`	No	Merchant company name displayed on the receipt.
`shopName`	`string`	No	Store name displayed on the receipt.
`shopPhone`	`string`	No	Store phone number.
`shopStreet`	`string`	No	Store street address.
`shopCity`	`string`	No	Store city.
`shopPostalCode`	`string`	No	Store postal code.
`customer`	`Customer`	No	Customer contact details, consents, and preferences.
`creditCardPayments`	`CreditCardPaymentDTO[]`	No	Payment breakdown for card transactions. Multiple entries supported.
`vats`	`VatDTO[]`	No	VAT summary for the entire transaction (as opposed to per-product VAT).
`barcode`	`StructuredBarcode`	No	Optional barcode for receipt validation or lookup.
`tags`	`string[]`	No	Custom metadata tags.

StructuredReceipt

Field	Type	Required	Description
`products`	`StructuredProductDTO[]`	No	List of products included in the receipt.

StructuredProductDTO

Field	Type	Required	Description
`name`	`string`	Yes	Product name.
`price`	`string`	Yes	Line total (price × quantity).
`quantity`	`string`	Yes	Number of units purchased.
`genCode`	`string`	Yes	Product barcode or identifier.
`family`	`string`	Yes	Product category.
`guarantee`	`string`	No	Warranty duration (e.g. `2 years`).
`vatRate`	`string`	No	VAT rate applied to this product (e.g. `20%`).
`unitPrice`	`string`	No	Price per unit, before multiplying by quantity.
`quantityUnit`	`string`	No	Unit label for the quantity (e.g. `kg`, `L`).
`metadata`	`object`	No	Arbitrary key-value metadata (values are arrays of strings). Use for coupons, discounts, or custom attributes.

CreditCardPaymentDTO

Attach one or more card payment records to the receipt. Each entry represents a single card transaction.

Field	Type	Required	Description
`cardNetwork`	`string`	Yes	Card network (e.g. `VISA`, `MasterCard`).
`paymentDate`	`string`	Yes	Payment date in ISO format (e.g. `2024-05-12`).
`paymentTime`	`string`	Yes	Time of payment (e.g. `13:45`).
`merchantName`	`string`	Yes	Merchant display name.
`maskedCardNumber`	`string`	Yes	Masked card number (e.g. `*1234`). Leading asterisks are added automatically if omitted.
`amount`	`string`	Yes	Amount charged on this card.
`currencySymbol`	`string`	Yes	Currency symbol or ISO code.
`paymentType`	`string`	Yes	`Credit` or `Debit`.
`paymentMethod`	`string`	No	How the card was used (e.g. `Contactless`, `PIN`).
`transactionReference`	`string`	No	Unique identifier for this card transaction.
`authorizationNumber`	`string`	No	Authorization code returned by the card network.
`terminalId`	`string`	No	Payment terminal identifier.
`storeId`	`string`	No	Store location identifier.
`merchantId`	`string`	No	Merchant identifier (e.g. SIRET).
`merchantPostalCode`	`string`	No	Merchant postal code.
`merchantCity`	`string`	No	Merchant city.
`bankCode`	`string`	No	Bank or processing code.
`cardTransactionId`	`string`	No	Internal card transaction identifier.
`merchantCustomHeader`	`string`	No	Custom header text displayed in the merchant section of the receipt.

StructuredBarcode

Field	Type	Required	Description
`type`	`string`	Yes	Barcode format. Supported values: `128`, `012`, `008`, `013`, `125`, `039`.
`value`	`string`	Yes	Data to encode in the barcode.

Customer

Field	Type	Required	Description
`email`	`string`	No	Customer email address. Required for email delivery modes.
`consents`	`Consent[]`	No	List of customer consent records (e.g. marketing opt-in).
`preferences`	`Preference[]`	No	Customer preferences (e.g. preferred receipt delivery channel).
`custom`	`CustomField[]`	No	Arbitrary key-value pairs for custom customer attributes.