Introduction

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.

<aside> 💡

For the In-store Cloud API request payloads below, parameters are in camelCase.

</aside>

Key information

Authentication and headers

Yavin uses API keys for authentication, you must insert your API key in the header of your POST.

Every Cloud API request carries a JSON body, so you must also declare its format with the Content-Type header. A missing Content-Type: application/json is the most frequent cause of a rejected request on a payload that is otherwise correct.

<aside> ⚠️

If you omit Content-Type: application/json, the API returns a 400 Bad request even when your payload is valid. Set both headers on every request, including the ones that only carry a serialNumber.

</aside>

Example request

curl --request POST \
  --url <https://api.yavin.com/api/v5/pos/payment> \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 1000,
    "serialNumber": "782996JIS2",
    "transactionType": "debit",
    "vendor": {
      "softwareName": "name",
      "softwareVersion": "1.0"
    }
  }'

Objects breakdown

These objects are used in several API routes, for each use, the context is clearly highlighted.

Customer

ReceiptTicket