In-store payment: Local API

Overview

The Local API lets your POS application drive a Yavin terminal over the local network: start a payment, print or share a receipt, reverse or abort a transaction. Choose it when the POS and the terminal are on different devices but share the same network.

At a glance

Base URL	`http://<LOCAL_IP>:16125/localapi/v4`
Authentication	None on the API itself: the merchant must be logged in to Yavin Pay with their My Yavin credentials (terminals can be pre-configured by our onboarding team)
Naming convention	camelCase for all fields, except the entries of `tax_breakdown` which are snake_case
Current version	`v4`
Result delivery	Synchronous: the HTTP response contains the transaction result

Endpoints

Endpoint	Method	Purpose
`/ping`	GET	Check connectivity and configuration
`/payment`	POST	Start a debit or refund transaction
`/print`	POST	Print free content (receipt, invoice)
`/share-receipt`	POST	Share a receipt by SMS, email or print
`/reversal`	POST	Reverse a recent transaction (less than 16 hours old)
`/abort`	POST	Abort the ongoing payment

Versions

API version	Last updated
`v4`	29/04/2026
`v1`	02/05/2022

Before you start

Network. The terminal must be connected to the same local network as your POS, and that network must have internet access to approve transactions. Address the terminal by its local IP, or preferably by Network Service Discovery (Apple Bonjour compatible), which survives IP changes: see Add on: Protocole Bonjour.

Port. Always include port 16125 in the URL (easy to remember: P=16, A=1, Y=25).

Protocol. HTTP by default, which is enough for a secured network between the cash register and the terminal. For HTTPS and response signature, see Add on: Security, signature and HTTPS. Both are conditional: HTTPS requires the terminal to have retrieved its certificate, and responses are signed only when signature is enabled for your company.

Responses. The endpoints documented on this page return a JSON body with a status field: ok on success, ko on failure. Application errors are returned with HTTP 200 and {"status": "ko", "message": "..."}; error messages are quoted verbatim under each endpoint. A malformed JSON body is rejected with an HTTP 400 or 500 without a JSON body: check the HTTP status before parsing the response. Payment endpoints return the Transaction object, documented at the end of this page along with the other shared objects. Keys whose value is null are omitted from responses: your parser must tolerate missing keys.

Timeouts. A payment has a 120 second window between the moment the request is received and a successful card read, split in two phases:

Up to 60 seconds for optional screens (tips, reference, review). If this phase times out, the transaction is aborted.
Up to 60 seconds for the card read itself.

Client-side timeout to set: 125 seconds for classic terminal use, 62 seconds for kiosk use (optional screens disabled) and for refunds.

Idempotency. Send an idempotentUuid on every payment request, one per payment attempt. See IdempotentUuid Management. The terminal keeps a payment request open for up to 15 minutes. If your client-side timeout expires, resend the same request with the same idempotentUuid: if the payment is still in progress, the new request attaches to it and returns its result.

Currency. The currency is the one configured on the merchant profile in the Yavin database. Supported today: EUR, CHF, GBP.

Ping terminal

GEThttp://<LOCAL_IP>:16125/localapi/v4/ping

Verifies your configuration. A good practice is to add a TEST button in your POS settings screen that calls this route and displays the result.

Parameters

showMessageBooleandefault false: true: displays "Hello there" on the terminal. false: nothing is shown

Request

curl -X GET 'http://<LOCAL_IP>:16125/localapi/v4/ping'

(async () => {
  const response = await fetch("http://<LOCAL_IP>:16125/localapi/v4/ping", {
    method: "GET",
  });

  if (!response.ok) throw new Error(`Yavin API error ${response.status}`);
  const data = await response.json();
  console.log(data);
})();

Response

JSON

{ "status": "ok" }

Start a debit transaction

POSThttp://<LOCAL_IP>:16125/localapi/v4/payment

Starts a debit payment on the terminal. Specify the amount and optional parameters; the terminal handles the payment flow and returns the result synchronously.

Parameters

amountIntegerrequired

Amount in cents, must be greater than 0

transactionTypeStringdefault debit

Use debit. Values are strict (debit or refund): any other value, credit included, is silently processed as a debit

idempotentUuidString

Unique identifier of the payment attempt. If the terminal knows a transaction with this UUID (last 24h), it returns that transaction instead of starting a new one. A ko transaction is returned as is: generate a new UUID to retry. If you do not provide one, Yavin generates one internally, which does not protect your POS from double submission

cartIdString

Your order number, shown in the MyYavin backoffice to link a transaction to an order

customerCustomer

Customer information attached to the transaction

Show Customer parameters

customer.firstNameString: First name
customer.lastNameString: Last name
customer.emailString: Email
customer.phoneString: International format starting with + (eg +33612345678)
customer.birthDateString: Birthdate

enableGiftScreenBoolean

null (default): the terminal tips configuration applies. A non-null value overrides it for this transaction: true shows the tips screen, false skips it

acceptedPaymentAcceptedPaymentdefault {"acceptedMediumType":"all"}

Restricts the payment methods the terminal accepts for this transaction. See The AcceptedPayment object at the end of this page

Show AcceptedPayment parameters

acceptedPayment.acceptedMediumTypeStringdefault all: all: every payment method configured on the terminal. lunch_vouchers_only: meal voucher cards only. bank_cards_only: bank cards only

giftAmountIntegerdefault 0

Tip or donation in cents, if the tip was selected on the POS side

receiptTicketReceiptTicket

Receipt content printed together with the card ticket

Show ReceiptTicket parameters

receiptTicket.dataStringrequired: Content to print
receiptTicket.formatStringdefault text: Format of the content
receiptTicket.tax_breakdownArray: Array of Tax objects, one per tax rate

referenceString

Waiter or person processing the transaction

vendorVendor

Your software name and version, useful for support and debugging

Show Vendor parameters

vendor.softwareNameString: Name of the POS software
vendor.softwareVersionString: Version of the POS software, helps track and identify bugs quickly

checkoutExternalIdString

Merchant-unique checkout ID, required when any external order field below is sent. It must be unique: a request is rejected if a completed ok transaction already uses this value, so send a different value for each transaction of a split payment

externalTableNumberString

Table number. Only used with checkoutExternalId

externalOrderNumberString

Human-readable order number shown to merchant and customer. Only used with checkoutExternalId

externalOrderIdString

Unique technical order ID from your POS, for reconciliation. Only used with checkoutExternalId

Request

{
  "amount": 1000,
  "transactionType": "debit",
  "idempotentUuid": "2f1c2e2a-6c21-4a4b-9c2b-9f6f2c8e9b51",
  "vendor": {
    "softwareName": "MyPOS",
    "softwareVersion": "1.0"
  },
  "receiptTicket": {
    "data": "This is the receipt ticket\nto print",
    "format": "text"
  },
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@yavin.com"
  },
  "acceptedPayment": {
    "acceptedMediumType": "all"
  },
  "checkoutExternalId": "6843z9fgved8",
  "externalTableNumber": "54",
  "externalOrderNumber": "642558",
  "externalOrderId": "14763642558"
}

curl -X POST 'http://<LOCAL_IP>:16125/localapi/v4/payment' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 1000,
  "transactionType": "debit",
  "idempotentUuid": "2f1c2e2a-6c21-4a4b-9c2b-9f6f2c8e9b51",
  "vendor": {
    "softwareName": "MyPOS",
    "softwareVersion": "1.0"
  },
  "receiptTicket": {
    "data": "This is the receipt ticket\nto print",
    "format": "text"
  },
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@yavin.com"
  },
  "acceptedPayment": {
    "acceptedMediumType": "all"
  },
  "checkoutExternalId": "6843z9fgved8",
  "externalTableNumber": "54",
  "externalOrderNumber": "642558",
  "externalOrderId": "14763642558"
}'

(async () => {
  const response = await fetch("http://<LOCAL_IP>:16125/localapi/v4/payment", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "amount": 1000,
      "transactionType": "debit",
      "idempotentUuid": "2f1c2e2a-6c21-4a4b-9c2b-9f6f2c8e9b51",
      "vendor": {
        "softwareName": "MyPOS",
        "softwareVersion": "1.0"
      },
      "receiptTicket": {
        "data": "This is the receipt ticket\nto print",
        "format": "text"
      },
      "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@yavin.com"
      },
      "acceptedPayment": {
        "acceptedMediumType": "all"
      },
      "checkoutExternalId": "6843z9fgved8",
      "externalTableNumber": "54",
      "externalOrderNumber": "642558",
      "externalOrderId": "14763642558"
    }),
  });

  if (!response.ok) throw new Error(`Yavin API error ${response.status}`);
  const data = await response.json();
  console.log(data);
})();

import requests

headers = {
    "Content-Type": "application/json",
}

payload = {
  "amount": 1000,
  "transactionType": "debit",
  "idempotentUuid": "2f1c2e2a-6c21-4a4b-9c2b-9f6f2c8e9b51",
  "vendor": {
    "softwareName": "MyPOS",
    "softwareVersion": "1.0"
  },
  "receiptTicket": {
    "data": "This is the receipt ticket\nto print",
    "format": "text"
  },
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@yavin.com"
  },
  "acceptedPayment": {
    "acceptedMediumType": "all"
  },
  "checkoutExternalId": "6843z9fgved8",
  "externalTableNumber": "54",
  "externalOrderNumber": "642558",
  "externalOrderId": "14763642558"
}

response = requests.post(
    "http://<LOCAL_IP>:16125/localapi/v4/payment",
    headers=headers,
    json=payload,
    timeout=125,
)
response.raise_for_status()
data = response.json()

Response

JSON

{
  "amount": 1000,
  "appVersion": "3.2.8",
  "cardToken": "1234567890",
  "clientCardTicket": "...",
  "currencyCode": "EUR",
  "giftAmount": 0,
  "scheme": "CB",
  "status": "ok",
  "transactionId": "xPUyi4fmdibD",
  "transactionType": "debit"
}

Start a refund transaction

POSThttp://<LOCAL_IP>:16125/localapi/v4/payment

Credits funds back to the customer card, on the same /payment endpoint, with transactionType set to refund. There are no optional screens, so the recommended client-side timeout is 62 seconds.

Parameters

amountIntegerrequired

Amount in cents to credit back, must be positive

transactionTypeStringrequired

Must be set to refund. Omitting it, or sending any other value such as credit, starts a debit

idempotentUuidString

Unique identifier of the refund attempt. If the terminal knows a transaction with this UUID (last 24h), it returns that transaction instead of starting a new one. A ko transaction is returned as is: generate a new UUID to retry. If you do not provide one, Yavin generates one internally, which does not protect your POS from double submission

cartIdString

Your order number, shown in the MyYavin backoffice to link a transaction to an order

customerCustomer

Customer information attached to the transaction

Show Customer parameters

customer.firstNameString: First name
customer.lastNameString: Last name
customer.emailString: Email
customer.phoneString: International format starting with + (eg +33612345678)
customer.birthDateString: Birthdate

enableGiftScreenBoolean

No effect on refunds: optional screens (tips, reference, review) are disabled

giftAmountIntegerdefault 0

Tip or donation in cents, if the tip was selected on the POS side

receiptTicketReceiptTicket

Receipt content printed together with the card ticket

Show ReceiptTicket parameters

receiptTicket.dataStringrequired: Content to print
receiptTicket.formatStringdefault text: Format of the content
receiptTicket.tax_breakdownArray: Array of Tax objects, one per tax rate

referenceString

Waiter or person processing the transaction

vendorVendor

Your software name and version, useful for support and debugging

Show Vendor parameters

vendor.softwareNameString: Name of the POS software
vendor.softwareVersionString: Version of the POS software, helps track and identify bugs quickly

checkoutExternalIdString

externalTableNumberString

Table number. Only used with checkoutExternalId

externalOrderNumberString

Human-readable order number shown to merchant and customer. Only used with checkoutExternalId

externalOrderIdString

Unique technical order ID from your POS, for reconciliation. Only used with checkoutExternalId

Request

{
  "amount": 1000,
  "transactionType": "refund",
  "idempotentUuid": "8a4d1f0b-2e57-4c1a-b3d9-1c7e5f2a6d40",
  "vendor": {
    "softwareName": "MyPOS",
    "softwareVersion": "1.0"
  },
  "receiptTicket": {
    "data": "This is the receipt ticket\nto print",
    "format": "text"
  }
}

curl -X POST 'http://<LOCAL_IP>:16125/localapi/v4/payment' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 1000,
  "transactionType": "refund",
  "idempotentUuid": "8a4d1f0b-2e57-4c1a-b3d9-1c7e5f2a6d40",
  "vendor": {
    "softwareName": "MyPOS",
    "softwareVersion": "1.0"
  },
  "receiptTicket": {
    "data": "This is the receipt ticket\nto print",
    "format": "text"
  }
}'

(async () => {
  const response = await fetch("http://<LOCAL_IP>:16125/localapi/v4/payment", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "amount": 1000,
      "transactionType": "refund",
      "idempotentUuid": "8a4d1f0b-2e57-4c1a-b3d9-1c7e5f2a6d40",
      "vendor": {
        "softwareName": "MyPOS",
        "softwareVersion": "1.0"
      },
      "receiptTicket": {
        "data": "This is the receipt ticket\nto print",
        "format": "text"
      }
    }),
  });

  if (!response.ok) throw new Error(`Yavin API error ${response.status}`);
  const data = await response.json();
  console.log(data);
})();

import requests

headers = {
    "Content-Type": "application/json",
}

payload = {
  "amount": 1000,
  "transactionType": "refund",
  "idempotentUuid": "8a4d1f0b-2e57-4c1a-b3d9-1c7e5f2a6d40",
  "vendor": {
    "softwareName": "MyPOS",
    "softwareVersion": "1.0"
  },
  "receiptTicket": {
    "data": "This is the receipt ticket\nto print",
    "format": "text"
  }
}

response = requests.post(
    "http://<LOCAL_IP>:16125/localapi/v4/payment",
    headers=headers,
    json=payload,
    timeout=125,
)
response.raise_for_status()
data = response.json()

Response

JSON

{
  "amount": 1000,
  "appVersion": "3.2.8",
  "clientCardTicket": "...",
  "currencyCode": "EUR",
  "giftAmount": 0,
  "scheme": "CB",
  "status": "ok",
  "transactionId": "kQm2Vw9pLxTc",
  "transactionType": "refund"
}

Print a receipt ticket

POSThttp://<LOCAL_IP>:16125/localapi/v4/print

Prints free content on the terminal (invoice, receipt, kitchen slip), as plain text (text) or as ESC/POS commands (escpos).

Parameters

dataStringrequired: Content to print
formatStringdefault text: text or escpos

Request

{
  "data": "This is the text\nto print",
  "format": "text"
}

(async () => {
  const response = await fetch("http://<LOCAL_IP>:16125/localapi/v4/print", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "data": "This is the text\nto print",
      "format": "text"
    }),
  });

  if (!response.ok) throw new Error(`Yavin API error ${response.status}`);
  const data = await response.json();
  console.log(data);
})();

import requests

headers = {
    "Content-Type": "application/json",
}

payload = {
  "data": "This is the text\nto print",
  "format": "text"
}

response = requests.post(
    "http://<LOCAL_IP>:16125/localapi/v4/print",
    headers=headers,
    json=payload,
    timeout=125,
)
response.raise_for_status()
data = response.json()

Response

status = ok means the print request was accepted, not that the receipt was printed: a terminal that cannot print also answers ok. On failure, status = ko with one of:

Parameter 'data' is missing or empty: empty or missing data field
Wrong parameter 'format': format is not text or escpos

Share a receipt ticket

POSThttp://<LOCAL_IP>:16125/localapi/v4/share-receipt

Shares a receipt by SMS, email or print. The terminal prompts for the recipient information (phone number or email).

Parameters

receiptTicketReceiptTicketrequired

Receipt to share

Show ReceiptTicket parameters

receiptTicket.dataStringrequired: Content to print
receiptTicket.formatStringdefault text: Format of the content
receiptTicket.tax_breakdownArray: Array of Tax objects, one per tax rate

transactionIdStringrequired

Transaction linked to the receipt

mediumStringrequired

One of yavin, sms, email, print, in lowercase (SMS is rejected). With yavin, the receipt is stored and shared according to the user notification preferences

Request

{
  "receiptTicket": {
    "data": "This is the receipt ticket\nto print",
    "format": "text"
  },
  "transactionId": "fsOv53g7wxZ",
  "medium": "email"
}

curl -X POST 'http://<LOCAL_IP>:16125/localapi/v4/share-receipt' \
  -H 'Content-Type: application/json' \
  -d '{
  "receiptTicket": {
    "data": "This is the receipt ticket\nto print",
    "format": "text"
  },
  "transactionId": "fsOv53g7wxZ",
  "medium": "email"
}'

(async () => {
  const response = await fetch("http://<LOCAL_IP>:16125/localapi/v4/share-receipt", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "receiptTicket": {
        "data": "This is the receipt ticket\nto print",
        "format": "text"
      },
      "transactionId": "fsOv53g7wxZ",
      "medium": "email"
    }),
  });

  if (!response.ok) throw new Error(`Yavin API error ${response.status}`);
  const data = await response.json();
  console.log(data);
})();

import requests

headers = {
    "Content-Type": "application/json",
}

payload = {
  "receiptTicket": {
    "data": "This is the receipt ticket\nto print",
    "format": "text"
  },
  "transactionId": "fsOv53g7wxZ",
  "medium": "email"
}

response = requests.post(
    "http://<LOCAL_IP>:16125/localapi/v4/share-receipt",
    headers=headers,
    json=payload,
    timeout=125,
)
response.raise_for_status()
data = response.json()

Response

status = ok (with an optional message) when the receipt was shared. On failure, status = ko with one of:

Parameter 'transactionId' is missing or invalid: transactionId null or not found
Parameter 'receiptTicket' is missing or invalid: receiptTicket null, data null, or format is not text
Parameter 'medium' is missing or invalid: medium is missing, or is not print, email, sms or yavin in lowercase
Error: bad request: request badly formatted

Reverse a transaction

POSThttp://<LOCAL_IP>:16125/localapi/v4/reversal

Reverses a recent transaction.

Reversal conditions. The original transaction is an ok debit processed on the same terminal issuing the reversal, less than 16 hours ago (terminal time), and the reversal amount is equal to the original total amount, tip included (amount + giftAmount).

Parameters

amountIntegerrequired: Amount in cents, must equal the original total amount (amount • giftAmount)
initialTransactionIdStringrequired: Transaction to reverse

Request

{
  "amount": 1000,
  "initialTransactionId": "xPUyi4fmdibD"
}

(async () => {
  const response = await fetch("http://<LOCAL_IP>:16125/localapi/v4/reversal", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "amount": 1000,
      "initialTransactionId": "xPUyi4fmdibD"
    }),
  });

  if (!response.ok) throw new Error(`Yavin API error ${response.status}`);
  const data = await response.json();
  console.log(data);
})();

import requests

headers = {
    "Content-Type": "application/json",
}

payload = {
  "amount": 1000,
  "initialTransactionId": "xPUyi4fmdibD"
}

response = requests.post(
    "http://<LOCAL_IP>:16125/localapi/v4/reversal",
    headers=headers,
    json=payload,
    timeout=125,
)
response.raise_for_status()
data = response.json()

Response

status = ok with reversalTransactionId (the new reversal transaction) and initialTransactionId (the reversed one). On failure, status = ko with one of the following messages, always prefixed with Error : :

Error : Transaction ID is mandatory: initialTransactionId missing
Error : Transaction not found for ID: <transactionId>: unknown transaction on this terminal
Error : Amount mismatch: amount differs from the original total amount (amount + giftAmount)
Error : Transaction has already been reversed
Error : Cannot reverse this Transaction or time window expired: the transaction is not an ok debit or VAD transaction, or is more than 16 hours old
Error : No suitable gateway found to handle reversal
Error : An unexpected error occurred. Please try again later.: generic error

Abort a transaction

POSThttp://<LOCAL_IP>:16125/localapi/v4/abort

Aborts the ongoing payment: every payment screen is closed and the terminal returns to its main screen.

Avoid aborting during the card reading phase. The payment gateway screen may close unexpectedly and the payment information may not be transmitted properly, leading to data inconsistencies.

When the abort can act. The abort acts from the moment the payment request is received until the terminal hands over to the banking screen. On a payment without optional screens (tips, reference, review), this handover happens within about 1 to 2 seconds after the /payment call. Past that point the abort can no longer interrupt the payment, even if no card has been presented yet: the customer can still present a card and complete the payment at the requested amount.

Parameters

idempotentUuidString: UUID of the payment attempt to abort

Request

{
  "idempotentUuid": "2f1c2e2a-6c21-4a4b-9c2b-9f6f2c8e9b51"
}

(async () => {
  const response = await fetch("http://<LOCAL_IP>:16125/localapi/v4/abort", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "idempotentUuid": "2f1c2e2a-6c21-4a4b-9c2b-9f6f2c8e9b51"
    }),
  });

  if (!response.ok) throw new Error(`Yavin API error ${response.status}`);
  const data = await response.json();
  console.log(data);
})();

import requests

headers = {
    "Content-Type": "application/json",
}

payload = {
  "idempotentUuid": "2f1c2e2a-6c21-4a4b-9c2b-9f6f2c8e9b51"
}

response = requests.post(
    "http://<LOCAL_IP>:16125/localapi/v4/abort",
    headers=headers,
    json=payload,
    timeout=125,
)
response.raise_for_status()
data = response.json()

Response

status = ok when the transaction is aborted.

The response is sent once the outcome is known: if the payment can no longer be interrupted, it only arrives after the payment completes, which can take tens of seconds while the terminal waits for the card and shows the result screen.

On failure (transaction still ongoing or nothing to abort), status = ko with one of:

Abort not possible: the payment could not be interrupted and ran to completion. The response to the initial /payment is then authoritative: a status = ok there means the customer has been charged
Nothing to abort: no payment is in progress
Abort is not allowed: the ongoing payment was not started through the Local API
A transaction with the given idempotentUuid is already in progress (in the actual message, idempotentUuid is wrapped in backticks): the request is trying to abort a different transaction
Error while responding to local API: <cause>: Yavin Pay internal error

After requesting an abort. Always wait for the abort response before treating the payment as cancelled. On ko, wait for the response to the initial /payment and process it: on ok the customer has been charged, and the order must account for it or a refund must be triggered. Do not start a new payment for the same order before that response arrives: it would be rejected with A transaction with the given idempotentUuid is already in progress.

The Transaction object

Returned by the payment endpoints. Fields coming from your request are echoed back as is. Keys whose value is null are omitted: tolerate missing keys. A declined payment has status = ko and no message field.

Attributes

statusString: ok or ko
transactionIdString: Server-side identifier
amountInteger: Amount in cents, excluding giftAmount. The customer is debited the sum of amount and giftAmount (equal to total_amount in the webhook payload)
giftAmountInteger: Tip or donation in cents
currencyCodeString: ISO 4217 code
transactionTypeString: Lowercase: debit or refund. Tolerate other values (eg na)
appVersionString: Yavin Pay app version
cardTokenString: Unique token of the customer card
clientCardTicket / merchantCardTicketString: Customer and merchant card tickets
paymentApplicationString: AMEX, ANCV, CONECS_CONTACT, CONECS_CONTACTLESS, EMV_CONTACT, EMV_CONTACTLESS, EMV_MOTO, EMV_PAYMENT_LINK, RESTOFLASH, DISCOVER, CUP
schemeString: Acceptance network (eg VISA)
issuerString: Card issuer (eg CB, VISA, MASTERCARD)
idempotentUuidString: UUID from the request
cartId, reference, customer: Echoed from the request
checkoutExternalId, externalTableNumber, externalOrderNumber, externalOrderIdString: Echoed from the request

JSON

{
  "status": "ok",
  "transactionId": "xPUyi4fmdibD",
  "amount": 1000,
  "giftAmount": 0,
  "currencyCode": "EUR",
  "transactionType": "debit",
  "appVersion": "3.2.8",
  "cardToken": "1234567890",
  "clientCardTicket": "...",
  "merchantCardTicket": "...",
  "paymentApplication": "EMV_CONTACTLESS",
  "scheme": "CB",
  "issuer": "VISA",
  "idempotentUuid": "2f1c2e2a-6c21-4a4b-9c2b-9f6f2c8e9b51",
  "cartId": "ORDER-2026-000123",
  "reference": "Luke",
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@yavin.com"
  },
  "checkoutExternalId": "6843z9fgved8",
  "externalTableNumber": "54",
  "externalOrderNumber": "642558",
  "externalOrderId": "14763642558"
}

The Customer object

Optional on /payment. Customer information attached to the transaction and echoed back in the response. It is not used by /share-receipt, where the terminal always prompts for the recipient.

Attributes

firstNameString: First name
lastNameString: Last name
emailString: Email
phoneString: International format starting with + (eg +33612345678)
birthDateString: Birthdate

JSON

{
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+33612345678",
    "email": "john@yavin.com"
  }
}

The ReceiptTicket object

Content printed alongside the card ticket on /payment, or shared on /share-receipt.

Attributes

dataStringrequired: Content to print
formatStringdefault text: Format of the content
tax_breakdownArray: Array of Tax objects, one per tax rate

JSON

{
  "receiptTicket": {
    "data": "Receipt ticket here to print if needed",
    "format": "text"
  }
}

The Tax object

Optional breakdown attached to a ReceiptTicket, under the tax_breakdown key, with one entry per tax rate.

The key is tax_breakdown (not tax), and its entries are in snake_case.

Attributes

tax_amountInteger: Calculated tax amount in cents, from tax_percentage applied to the transaction amount
tax_percentageInteger: Percentage applied to the amount (eg 20 for 20%)

JSON

{
  "tax_breakdown": [
    { "tax_amount": 167, "tax_percentage": 20 },
    { "tax_amount": 50, "tax_percentage": 10 }
  ]
}

The Vendor object

Identifies your POS software. Optional everywhere, but strongly recommended: it is what lets our support team trace an issue back to a specific integration and version.

Attributes

softwareNameString: Name of the POS software
softwareVersionString: Version of the POS software, helps track and identify bugs quickly

JSON

{
  "vendor": {
    "softwareName": "MyPOS",
    "softwareVersion": "1.0"
  }
}

The AcceptedPayment object

Optional on /payment for debit transactions. Restricts the payment methods the terminal accepts: the customer cannot pay with an excluded method. Typical use: split payments where a first transaction is paid in meal vouchers only and a second transaction covers the remainder in bank card only. If you send a checkoutExternalId, use a different value for each transaction: a value already used by an ok transaction is rejected. Note that the terminal never splits a payment on its own: if the requested amount exceeds the card limit (eg the meal voucher cap), the transaction is fully declined (status ko), there is no partial approval.

Attributes

acceptedMediumTypeStringdefault all: all: every payment method configured on the terminal. lunch_vouchers_only: meal voucher cards only. bank_cards_only: bank cards only

JSON

{
  "acceptedPayment": {
    "acceptedMediumType": "lunch_vouchers_only"
  }
}

IdempotentUuid Management

Add on : Protocole Bonjour

Add on : Security, signature and HTTPS

In-store payment: Local API

Overview

At a glance

Endpoints

Versions

Before you start

Ping terminal

Parameters

Request

Response

Start a debit transaction

Parameters

Request

Response

Start a refund transaction

Parameters

Request

Response

Print a receipt ticket

Parameters

Request

Response

Share a receipt ticket

Parameters

Request

Response

Reverse a transaction

Parameters

Request

Response

Abort a transaction

Parameters

Request

Response

The Transaction object

Attributes

The Customer object

Attributes

The ReceiptTicket object

Attributes

The Tax object

Attributes

The Vendor object

Attributes

The AcceptedPayment object

Attributes

Related pages