The Cloud API allows merchants to initiate transactions, retrieve transaction history, share receipts, and more through HTTPS requests. It uses API key-based authentication for security and supports various payment methods. This API is flexible, working with multiple devices, and supports asynchronous payment processing via webhooks for streamlined integration with payment terminals.
<aside> 💡
Tips for the Cloud API
The Cloud API allows you to initiate an action on the terminal. It is communicated to the terminal through a notification sent via the Yavin server. The validity of this notification is constrained to a time window of 5 seconds. If the notification is not received by the terminal within this timeframe - potentially due to the terminal being offline - the action is considered expired and will not be retransmitted once the terminal is reconnected.
</aside>
The current API integration version is v5 for pos/payment and v4 for all the others.
| API Version | Last updated date |
|---|---|
v5 |
May 4, 2026 |
v4 |
May 4, 2026 |
v1 |
May 2, 2022 |
<aside> 💡
For the In-store Cloud API request payloads below, parameters are in camelCase.
</aside>
These objects are used in several API routes, for each use, the context is clearly highlighted.
Customer
| Parameters | Type | Default value | Required | Description |
|---|---|---|---|---|
firstName |
String | no | First name of the customer | |
lastName |
String | no | Last name of the customer | |
email |
String | no | Email of the customer | |
phone |
String | no | Phone number of the customer with the international format starting with + symbol (eg: +33612345678) |
ReceiptTicket
| Parameters | Type | Default value | Required | Description |
|---|---|---|---|---|
data |
String | yes | Data to print | |
format |
String | text | no | Format of data to print |
Transaction
| Parameters | Type | Default value | Required | Description |
|---|---|---|---|---|
amount |
Integer | yes | Amount of the transaction in cents, excluding the giftAmount. This field must be positive for classic debit. | |
giftAmount |
Integer | 0 | no | Tips or donation in cents. |
appVersion |
String | yes | Version of Yavin Pay app | |
createdAt |
String | yes | Date of creation in the Yavin database | |
currencyCode |
String | yes | Currency code, ISO 4217 (eg: EUR) |
|
status |
String | yes | Status of the transaction (ok, ko, pending) |
|
transactionId |
String | yes | Identifier of the transaction on Yavin server | |
localId |
String | yes | Local identifier on the terminal of the transaction | |
serialNumber |
String | yes | Terminal identifier from which the transaction has been made | |
paymentApplication |
String | null | no | Payment application of the transaction (AMEX, ANCV, CONECS_CONTACT, CONECS_CONTACTLESS, EMV_CONTACT, EMV_CONTACTLESS, EMV_MOTO, EMV_PAYMENT_LINK, RESTOFLASH, DISCOVER, CUP) |
scheme |
String | null | no | Acceptance network of the transaction (eg: VISA) |
issuer |
String | null | no | Issuer of the card used for the transaction |
reference |
String | null | no | Waiter or person who performed the transaction if feature used |
transactionType |
String | yes | Type of the transaction (eg: debit) | |
clientTicket |
String | null | no | Client ticket |
companyTicket |
String | null | no | Merchant ticket |
pan |
String | null | no | PAN of the card used for the transaction |
id |
Integer | yes | ||
description |
String | null | no | |
ticketUrl |
String | yes | URL of the digital client ticket | |
checkoutExternalId |
String | null | no | Checkout ID which must be unique, and allow to save the other external IDs. |
externalTableNumber |
String | null | no | Table number associated with the order. |
| Only used if there is a checkoutExternalId | ||||
externalOrderNumber |
String | null | no | Human-readable order number displayed to the merchant and customer. It is generally unique within a given day, shift, or service period, depending on the merchant’s organization. |
| Only used if there is a checkoutExternalId | ||||
externalOrderId |
String | null | no | Unique identifier of the order generated by the POS system. This value must remain unique across all orders and is primarily used for technical reconciliation, tracking, and synchronization between systems. |
| Only used if there is a checkoutExternalId |
Vendor
| Parameters | Type | Default value | Required | Description |
|---|---|---|---|---|
softwareName |
String | no | Name of POS software | |
softwareVersion |
String | no | Version of POS software - this could be useful to help track and identify bugs as quickly as possible |
AcceptedPayment
| Parameters | Type | Default value | Required | Description |
|---|---|---|---|---|
acceptedMediumType |
String | all |
no | Possible values: all, lunch_vouchers_only, bank_cards_only |
Item (v5 only for pos/payment)
| Parameters | Type | Default value | Required | Description |
|---|---|---|---|---|
name |
String | yes | Item name | |
total_amount |
Integer | yes | Total amount in cents for the item | |
total_amount_without_tax |
Integer | null | no | Item total before tax |
category |
String | null | no | Item category |
eligible_titre_restaurant |
Boolean | null | no | Whether item is eligible for meal voucher |
free_note |
String | null | no | Free text note |
quantity |
Integer | null | no | Quantity |
unit_price |
Integer | null | no | Unit price in cents |
unit_price_without_tax |
Integer | null | no | Unit price before tax in cents |
tax |
Object | null | no | { "amount": <int>, "rate": <int> } |
items |
Array | no | Nested items |