Request / response

This page is applicable for the following endpoints:

Request parameters

Path variables

rental_type (string, required) The rental type: either pickup or return.
location_id (string, required) The location identifier: an unique identifier for the shop.
battery_id (string, required) The battery barcode on the back of the Chimpy (CODE128)
user_coupon (string, optional) The user coupon: it can take multiple forms (a QR code in the user mobile app, a swisspass, a free charge coupon in a sms, a paper coupon, etc.) and can lead to special deals (free charge) and / or in-app payments. Optional param.

Query parameters

lang (string, optional) The language to be used for the response. See Locales for more info.
slip_width (number, optional) The width of the sales slip in characters. Accepted values: 32, 42. Default/fallback value: 42.
partner_transaction_id (string, optional) An unique transaction id given by the partner terminal software. Optional param.
partner_terminal_id (string, optional) An unique id of the terminal where the rental is performed, according to the partner's numbering system. Optional param.
support_code (number, optional) During a return rental, a code to identify physical problems with the battery (example: cable missing). Currently supported values: 200 (cable missing).

Response

Response body

For HTTP status 200 OK the response body contains a JSON object with the following structure:

Response
    
 
{  "data": {    "rental": {      "status": <status>,      "error_type": <error_type>,      "error_message": <error_message>,      "rental_type": <rental_type>,      "payment_via": <app_or_shop>,      "hashed_rental_id": <hashed_rental_id>,      "coupon_type": <coupon_type>,      "charge_currency": <charge_currency>,      "total_amounts": {        "charge": <charge_amount>,        "deposit": <deposit_amount>,        "detraction": <detraction_amount>,        "detraction_net": <detraction_net_amount>,        "cable_missing": <cable_missing_amount>,        "late_fee": <late_fee_amount>,        "battery_damaged": <battery_damaged_amount>,        "refund": <refund_amount>,        "shop": <shop_amount>,        "user": <user_amount>,        "shop_net": <shop_net_amount>,        "user_net": <user_net_amount>,        "vat_types_user": <vat_types_user_amount>,        "vat_user": <vat_user_amount>,        "vat_shop": <vat_shop_amount>,      },    "shop_provision": {       "net": <shop_provision_net>,         "gross": <shop_provision_gross>,      },      "sales_slip": {        "complete_slip": [          "slip_line_1",          "slip_line_2",          "    ...    ",          "slip_line_N"        ],        "slip_width": <slip_width>,        "number_of_lines": <number_of_lines>      }    }  },  "locale": <locale>,  "req": <request_object>}
Copy

Response items

status (string) The request status. Can be one of error, ready_for_pickup, ready_for_return, pickup_completed, return_completed.
error_type (string or null) The error type, expressed in a codified expression. It can be either null for a successful request or one of battery_non_existing, battery_not_rented_out, battery_already_returned, battery_expired, battery_already_used, user_hash_invalid, user_inactive, undefinedfor a failed request. See Error types for more.
error_message (string or null) The verbose description of the error in the requested locale. This field can be used to display an error on the screen.
rental_type (string) Either pickup or return.
coupon_type (string) Either free_charge or null. This field will be filled only if a valid user coupon that gives was used.
payment_via (string) Either app or shop.By default, the payment is carried out by the shop. But a user coupon may lead to a in-app payment (premium users, online coupon, etc.)
hashed_rental_id (string) A unique hash consisting of lowercase letters and numbers referencing a successful rental object. Can be used to retrieve a digital sales slip.
charge_currency (string) The currency used for the money transaction (ISO 4217 alphabetic currency code).
total_amounts (object of numbers) The total amounts of the transaction, listed by category. See Total amounts for more.
shop_provision (object of numbers) The previsional shop provision for the rental. Important note: a given rental may create provision amounts for other associated rentals (e.g. a return rental might create provision amounts for a pickup rental), thus the aggregation of this value over a period of time is not necessarily enough to calculate invoice amounts.
complete_slip (array of strings) The sales slip that can be printed, generated in the requested locale and with the requested slip width in characters.
slip_width (number) The slip width of the sales slip in characters.
number_of_lines (number) The length of the sales slip in lines.
locale (string) The locale as specified in the request. See Locales for more info.
req (object) Relevant information concerning the request received by the API.

The following request are all done using the GET method, hence they would not alter any database record. The response of the same requests done using the POST method would look exactly alike - except for the request status - and would create new records in the database.

Example I

A customer wants to pick up battery 10000001 at location sandbox_retail_fr_10001

Request - Pickup example
    
 
curl -X GET \     'https://{{POS_API_URI}}/api/v2/rentals/pickup/locations/sandbox_retail_ch_10001/batteries/10000001?lang=en' \     -H 'Authorization: Bearer {{access_token}}'
Copy

The battery can be picked up by the customer. Yay!

Response - Pickup example
    
{    "data": {        "rental": {            "status": "ready_for_pickup",            "error_type": null,            "error_message": "Everything worked as expected.",            "rental_type": "pickup",            "charge_currency": "CHF",            "coupon_type": null,            "payment_via": "shop",            "hashed_rental_id": "o43joy",            "total_amounts": {                "charge": 4.0,                "deposit": 15.0,                "detraction": 0.0,                "detraction_net": 0.0,                "cable_missing": 0.0,                "late_fee": 0.0,                "battery_damaged": 0.0,                "refund": 0.0,                "shop": 19.0,                "user": 19.0,                "app": 0.0,                "shop_net": 18.71,                "user_net": 18.71,                "vat_types_user": {                    "A": 0.29,                    "B": 0.0                },                "vat_user": 0.29,                "vat_shop": 0.29            },            "shop_provision": {                "gross": 1.0,                "net": 0.93            },            "sales_slip": {                "complete_slip": [                    "                Chimpy AG                 ",                    "            Baslerstrasse 106             ",                    "               8048 Zürich                ",                    "             CHE-281.804.523              ",                    "------------------------------------------",                    "               CHIMPY RENTAL              ",                    "------------------------------------------",                    "Battery rental                CHF   4,00 A",                    "Battery and cable deposit     CHF  15,00 B",                    "                              ------------",                    "TOTAL CASH                    CHF  19,00  ",                    "Net amount                    CHF  18,71  ",                    "A=VAT 7.7%                    CHF   0,29  ",                    "B=VAT 0.0%                    CHF   0,00  ",                    "                                          ",                    "* Revenue on behalf of Chimpy AG.         ",                    "  Deposit is not subject to VAT.          ",                    "------------------------------------------",                    "CONDITIONS OF RENT                        ",                    "* Deposit: refunded if the battery,       ",                    "  cable and tag are intact.               ",                    "* Rental period: 1 week (up toTue.        ",                    "  7.4.20).                                ",                    "* Late penalty: CHF 2.- per week of       ",                    "  additional delay, deducted from the     ",                    "  deposit (max CHF 15.-).                 ",                    "* Return points: you will find all        ",                    "  Chimpy 2000 Points are to be found in   ",                    "  the app Chimpy                          ",                    "* General conditions on                   ",                    "  heychimpy.com/terms                     ",                    "                                          ",                    "SUPPORT (your code:s3wf-9772)             ",                    "* chimpy.ch/support                       ",                    "* Facebook Messenger: m.me/hellochimpy    ",                    "* Tel: +41 44 500 29 95                   ",                    "                                          ",                    "RENTING INFO Battery (#10000000)          ",                    "Out:-                                     ",                    "In:-                                      ",                    "------------------------------------------",                    "             INSTALL THE APP!             ",                    "              heychimpy.com               "                ],                "slip_width": 42,                "number_of_lines": 43            },        }    },    "locale": "en-CH",    "req": {        "method": "GET",        "url": "https://{{POS_API_URI}}/api/v2/rentals/pickup/locations/sandbox_retail_ch_10001/batteries/10000000?lang=en"    }}
Copy

Example II

A customer wants to pick up battery 10000001 at location sandbox_retail_ch_100001 with the valid free charge coupon greenaf000000

Request - Pickup with coupon
    
curl -X GET \     'https://{{POS_API_URI}}/api/v2/rentals/return/locations/sandbox_retail_ch_10001/batteries/10000001/users/greenaf00000?lang=en' \     -H 'Authorization: Bearer {{access_token}}'
Copy

The coupon is valid and has been applied to the pricing

Response - Pickup with coupon
    
{    "data": {        "rental": {            "status": "ready_for_pickup",            "error_type": null,            "error_message": "Everything worked as expected.",            "rental_type": "pickup",            "charge_currency": "CHF",            "coupon_type": "free_charge",            "payment_via": "shop",            "hashed_rental_id": "y1rw64",            "total_amounts": {                "charge": 0.0,                "deposit": 15.0,                "detraction": 0.0,                "detraction_net": 0.0,                "cable_missing": 0.0,                "late_fee": 0.0,                "battery_damaged": 0.0,                "refund": 0.0,                "shop": 15.0,                "user": 15.0,                "app": 0.0,                "shop_net": 15.0,                "user_net": 15.0,                "vat_types_user": {                    "A": 0.0,                    "B": 0.0                },                "vat_user": 0.0,                "vat_shop": 0.0            },            "shop_provision": {                "gross": 2.0,                "net": 1.86            },            "sales_slip": {                "complete_slip": [                    "                Chimpy AG                 ",                    "            Baslerstrasse 106             ",                    "               8048 Zurich                ",                    "           CHE-281.804.523 MWST           ",                    "------------------------------------------",                    "           CHIMPY RENTAL                  ",                    "------------------------------------------",                    "Battery rental (coupon)       CHF   0.00 A",                    "Battery and cable deposit     CHF  15.00 B",                    "                              ------------",                    "TOTAL CASH                    CHF  15.00  ",                    "Net amount                    CHF  15.00  ",                    "A=VAT 7.7%                    CHF   0.00  ",                    "B=VAT 0.0%                    CHF   0.00  ",                    "                                          ",                    "* Revenue on behalf of Chimpy AG.         ",                    "  Deposit is not subject to VAT.          ",                    "------------------------------------------",                    "CONDITIONS OF RENT                        ",                    "* Deposit: refunded if the battery,       ",                    "  cable and tag are intact.               ",                    "* Rental period: 1 week (up toMon.        ",                    "  13.7.20).                               ",                    "* Late penalty: CHF 2 per week of         ",                    "  additional delay, deducted from the     ",                    "  deposit (max 15).                       ",                    "* Return points: you will find all        ",                    "  Chimpy 2000 Points are to be found in   ",                    "  the app Chimpy                          ",                    "* General conditions on                   ",                    "  heychimpy.com/terms                     ",                    "                                          ",                    "SUPPORT (your code:np6d-7198)             ",                    "* chimpy.ch/support                       ",                    "* Facebook Messenger: m.me/hellochimpy    ",                    "* Tel: +41 44 500 29 95                   ",                    "                                          ",                    "RENTING INFO Battery (#10000001)          ",                    "Out:Zürich HB, 6.7                        ",                    "In:-                                      ",                    "------------------------------------------",                    "             INSTALL THE APP!             ",                    "              heychimpy.com               "                ],                "slip_width": 42,                "number_of_lines": 43            },        }    },    "locale": "en-CH",    "req": {        "method": "GET",        "url": "https://pos-staging.heychimpy.com/api/v2/rentals/pickup/locations/sandbox_retail_ch_10001/batteries/10000001/users/greenaf000000?lang=en"    }}
Copy

Example III

A customer wants to return battery 10000100 at location sandbox_retail_ch_100001

Request - Return example
    
 
curl -X GET \     'https://{{POS_API_URI}}/api/v2/rentals/return/locations/sandbox_retail_ch_10001/batteries/10000100?lang=en' \     -H 'Authorization: Bearer {{access_token}}'
Copy

The battery can be returned. The deposit to be reimbursed at the point of sale is CHF 15.

Response - Return example
    
{    "data": {        "rental": {            "status": "ready_for_return",            "error_type": null,            "error_message": "Everything worked as expected.",            "rental_type": "return",            "coupon_type": null,            "payment_via": "shop",            "hashed_rental_id": "p8d1rk",            "charge_currency": "CHF",            "coupon_type": null,            "total_amounts": {                "charge": 0.0,                "deposit": -15.0,                "detraction": 0.0,                "detraction_net": 0.0,                "cable_missing": 0.0,                "late_fee": 0.0,                "battery_damaged": 0.0,                "refund": 0.0,                "shop": -15.0,                "user": -15.0,                "app": 0.0,                "shop_net": -15.0,                "user_net": -15.0,                "vat_types_user": {                    "A": 0.0,                    "B": 0.0                },                "vat_user": 0.0,                "vat_shop": 0.0            },            "shop_provision": {                "gross": 0.25,                "net": 0.23            },            "sales_slip": {                "complete_slip": [                    "                Chimpy AG                 ",                    "            Baslerstrasse 106             ",                    "               8048 Zürich                ",                    "             CHE-281.804.523              ",                    "------------------------------------------",                    "              CHIMPY RETURN               ",                    "------------------------------------------",                    "Cable present                 CHF   0,00 A",                    "No delay                      CHF   0,00 A",                    "Battery intact                CHF   0,00 A",                    "                              ------------",                    "TOTAL DEDUCTION               CHF   0,00  ",                    "                                          ",                    "Depot in advance              CHF -15,00 B",                    "                              ------------",                    "REMAINING CASH                CHF -15,00  ",                    "                                          ",                    "* Revenue on behalf of Chimpy AG.         ",                    "  Deposit is not subject to VAT.          ",                    "------------------------------------------",                    " !!! THANKS FOR THE RESTITUTION !!! <3 <3 ",                    "------------------------------------------",                    "SUPPORT (your code:)                      ",                    "* chimpy.ch/support                       ",                    "* Facebook Messenger: m.me/hellochimpy    ",                    "* Tel: +41 44 500 29 95                   ",                    "                                          ",                    "RENTING INFO Battery (#10000100)          ",                    "Out:Zürich HB, 28.3                       ",                    "In:Paris Gare de Lyon, 31.3               ",                    "------------------------------------------",                    "             INSTALL THE APP!             ",                    "              heychimpy.com               "                ],                "slip_width": 42,                "number_of_lines": 33            },        }    },    "locale": "en-CH",    "req": {        "method": "GET",        "url": "https://{{POS_API_URI}}/api/v2/rentals/return/locations/sandbox_retail_ch_10001/batteries/10000100?lang=en"    }}
Copy

Last updated on