NAV Navbar
python shell

Introduction

Welcome to the Yavin API! You can use it to get information on your payments stored in our database.

You can find more information on our website.

Download our package on Python package repository.

Review our code on github.

pip install yavin

Note: This API is still in beta, don't hesitate to contact us if you find a bug or would like us to develop a missing feature.

Authentication

To authorize, use this code:

import yavin

api = yavin.authorize('<yavin_secret>')
# With shell, you can just pass the correct header with each request
curl "https://api.yavin.com/api/v1/transactions?yavin_secret=<yavin_secret_key>"

Make sure to replace <yavin_secret_key> with your API key.

Yavin uses API keys to restrict the access to the API to authenticated users. You can get one in your backoffice on my.yavin.com. In the tab API.

All requests on Yavin API should be authenticated. To do so, add the following param in your request::

yavin_secret=<yavin_secret_key>

Metadata

All API response contain 2 fields: meta and data

meta and data can be accessed as follow :

from yavin import Client

yavin_client = Client('<yavin_secret_key>')
yavin_client.transactions.get()
print(yavin_client.transactions.data)
print(yavin_client.transactions.meta)
curl "https://api.yavin.com/api/v1/transactions/?yavin_secret=<yavin_secret_key>"

The meta field

The meta field contains technical information described as follow:

field Meaning
code http code of the request.
message Human readable message for debug purpose.
total The total number of elements available. Used for pagination purpose if applicable.
start The start of the elements retreived. Used for pagination purpose if applicable.
count The number of elements retreived. If applicable.

The data field

This field contains the data requested.

Errors

The Yavin API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
404 Not Found -- The specified path could not be found.
405 Method Not Allowed -- You tried to access a path with an invalid method.
500 Internal Server Error -- We had a problem with our server. Try again later.

Transactions

Example transaction:

{
    "transaction_id": "1",
    "date": "2020-01-15",
    "time": "11:19:31",
    "amount": 1000,
    "currency": "EUR",
    "status": "DEBIT",
    "pan": "527345XXXXXX2315",
    "logical_number": "003",
    "scheme": "VISA"
}

The transaction object contains the following fields:

Parameter Description
transaction_id unique identifier of the transaction
date date of the transaction
time time of the transaction
amount amount in cent of the transaction
currency currency of the transaction
status DEBIT = the transaction was successful, TNA = the transaction aborted
pan hidden card number
logical_number number for the merchant to identify the terminal
scheme scheme used for the transaction (CB,CBSC (contactless),VISA,MASTERCARD,CONECS...)

Get All Transactions

from yavin import Client

yavin_client = Client('<yavin_secret_key>')
yavin_client.transactions.get({
    'start_date': '2019-12-12',
    'end_date': '2020-03-03',
    'limit': 2
})
print(yavin_client.transactions.data)
curl "https://api.yavin.com/api/v1/transactions/?yavin_secret=<yavin_secret_key>"

The above command returns JSON structured like this:

{
  "meta": {
    "total": 55,
    "start": 0,
    "count": 2,
    "code": 200,
    "message": "ok"
  },
  "data": {
    "transactions": [
      {
        "transaction_id": "1",
        "date": "2020-01-15",
        "time": "11:19:31",
        "amount": 1000,
        "currency": "EUR",
        "status": "DEBIT",
        "pan": "527345XXXXXX2315",
        "logical_number": "003",
        "scheme": "VISA"
      },
      {
        "transaction_id": "2",
        "date": "2020-01-14",
        "time": "15:43:14",
        "amount": 300,
        "currency": "EUR",
        "status": "TNA",
        "pan": "472906XXXXXX4031",
        "logical_number": "003",
        "scheme": "MASTERCARD"
      }
    ]
  }
}

This endpoint retrieves all transactions.

HTTP Request

GET https://api.yavin.com/api/transactions

Query Parameters

Parameter Default Description
end_date today End date filter.
start_date 30 days before the end_date Start date filter.
limit 20 Limit of the number of payments to retreive.