Paype Public API

Paype Public API is used by Paype partners to communicate with Paype systems. The API supports managing partners clients loyalty, bonus, member or client cards, custom offers and tickets that clients can see and use on their mobile devices.

PROTOCOL


REST API at https://api.paype.com

Consumes HTTP verbs GET, POST, PUT and DELETE on endpoints listed below. Accepting content-type application/json for JSON POST or PUT data and multipart/form-data or application/x-www-form-urlencoded for requests with file uploads.

AUTHENTICATION


API authenticates via 3 query parameters: key, nonce and signature.

Name Description
key API key generated in  management web. Not to confuse with secret that should never be sent in requests or shared.
nonce Arbitrary number used to make signatures unique. Nonce is used only once and should be incremented with every request. One possible way of doing so is using system time in milliseconds as your nonce.
signature Hex encoded SHA256 hash calculated from string concatenated nonce, API key and secret. signature=sha256(nonce+key+secret)

EXAMPLE


CURL example of posting a customer for a fictional business

curl -H "Content-Type: application/json" -d '{"email":"xyz@paype.me","phone_number":"5005667","phone_country":"372","status":"Gold"}' 'https://api.paype.com/customers?nonce=1&key=0bec0097-5565-4bf9-90c5-a262776ca8d1&signature=02d9cdadb853641d343e15166b2b10c9e1f45122696e043e4023ef4026b6b86f'

More examples found in Paype  public GitHub repository.

customers


Creating customer POST /customers

Adding a customer into specific customer status group and assigning them loyalty or bonus card connected to this status group.

Name Required Description Expected
status Name of the customer status group defined in Loyalty App / Customer Info section of business management web
email
  • Email expected.
phone_country Separate the countries calling code from the phone number.
  • Integer expected.
phone_number
  • Integer expected.
first_name
last_name
gender
  • Accepted values: male,female
birthday
  • Date expected in format yyyy-mm-dd. Example 1987-10-19
customer_id Customer id in your system. Can be empty for auto-generated customer id-s from Loyalty App / Customer Info section of business management web
meta_data Custom info in json format. for ex: {"customProperty": "value"}

Returns
success Boolean

Delete customer DELETE /customers/<token>

Delete customer with token (uuid)

Name Required Description Expected
token YES Parameter in URL
  • Identifier in type UUID expected.

Returns
success true if user was found and deleted

Message customer POST /customers/<token>/messages

Customer will get the message to mobile app inbox.

Name Required Description Expected
token YES Parameter in URL
  • Identifier in type UUID expected.
message YES

Returns
success Boolean

Get customer GET /customers/<token>

Get customer data by token (uuid)

Name Required Description Expected
token YES Parameter in URL
  • Identifier in type UUID expected.
email

Returns
first_name
last_name
status Status group the customer belongs to.
gender
age
customer_since Date and time when customer was created from business web or API, or chose to join your company from their mobile device.
last_login_time
customer_id
email
phone_international Phone number in international format.
phone_number
phone_country
user_type Active users can see and use the card and related offers, inactive users have not yet accepted and added the card from their mobile device or not activated and confirmed from the business web and pending users have not yet started using Paype.
comment
meta_data
identification_count
personal_code
last_update
tags

Message customer POST /customers/<token>/tags

Customer will be tagged.

Name Required Description Expected
token YES Parameter in URL
  • Identifier in type UUID expected.
tag YES

Returns
success Boolean

Updating customer PUT /customers/<identifier>

Updating any of the customers fields. Identifier is either Paype supplied token (uuid) or your customer ID (will not work if it is uuid).

Name Required Description Expected
identifier Parameter in URL, can be either customer token or customer_id.
customer_id Customer id in your system. If token is sent you can send this field in JSON body to update the customer.
email
  • Email expected.
phone_country Separate the countries calling code from the phone number.
  • Integer expected.
phone_number
  • Integer expected.
first_name
last_name
gender
  • Accepted values: male,female
birthday
  • Date expected in format yyyy-mm-dd. Example 1987-10-19
status Name of the customer status group defined in Loyalty App / Customer Info section of business management web
active
comment Overwrites the customer comment, please use comment value from GET customer to run update
discount
  • Integer expected.
meta_data

Returns
success Boolean

Listing customers GET /customers

Get list of your customers adding filters as get parameters. All filters are optional.

Name Required Description Expected
created_within Include customers created or updated within last created_within time in seconds. Example 86400 (24h)
  • Integer expected.
active Include only customers who are activated and have accepted your card as boolean
gender
  • Accepted values: male,female
status Name of the customer status group defined in Loyalty App / Customer Info section of business management web
language
age_from
  • Integer expected.
age_to
  • Integer expected.

Returns
first_name
last_name
status Status group the customer belongs to.
gender
age
birthday
language
customer_since Date and time when customer was created from business web or API, or chose to join your company from their mobile device.
last_login_time
customer_id
token
email
phone_international Phone number in international format.
phone_number
phone_country
user_type Active users can see and use the card and related offers, inactive users have not yet accepted and added the card from their mobile device or not activated and confirmed from the business web and pending users have not yet started using Paype.
identification_count
personal_code
meta_data
last_update

offers


Creating offer POST /offers

Name Required Description Expected
category YES Name of the category where offer is posted. If the category does not exist new one is created.
status Offer visible only to customers belonging to specific status group
cover YES Cover image for the offer. Recommended aspect ratio 1:1 (perfect square) with minimum dimensions 640 x 640 pixels.
  • Accepted mimetypes image/gif,image/jpeg,image/png
media Media list up to 5 files with possible mix of types image, audio and video. For images recommended aspect ratio 1:1 (perfect square) with minimum dimensions 640 x 640 pixels.
  • Accepted mimetypes audio/mp3,audio/mp4,audio/mpeg,audio/ogg,audio/vnd.rn-realaudio,audio/vnd.wave,video/avi,video/mpeg,video/mp4,video/ogg,video/quicktime,video/x-ms-wmv,image/gif,image/jpeg,image/png
type Defaults to Offer if not sent
name YES
subtitle
text
language
duration_from
  • Time expected with timezone in format yyyy-mm-dd hh:mm:ssTz where timezone (Tz) is +- from UTC. Example 2014-10-19 10:23:54+02
duration_to
  • Time expected with timezone in format yyyy-mm-dd hh:mm:ssTz where timezone (Tz) is +- from UTC. Example 2014-10-19 10:23:54+02
  • Time has to be in the future.
showtime_from
  • Time expected with timezone in format yyyy-mm-dd hh:mm:ssTz where timezone (Tz) is +- from UTC. Example 2014-10-19 10:23:54+02
showtime_to
  • Time expected with timezone in format yyyy-mm-dd hh:mm:ssTz where timezone (Tz) is +- from UTC. Example 2014-10-19 10:23:54+02
  • Time has to be in the future.
men_from Starting age of men to show the offer to
  • Integer expected.
men_to Maximum age of men to show the offer to
  • Integer expected.
women_from Starting age of women to show the offer to
  • Integer expected.
women_to Maximum age of women to show the offer to
  • Integer expected.
price
  • Floating point numeric value expected. Example 5.55
old_price
  • Floating point numeric value expected. Example 5.55
product_link
  • URL expected. Example www.paype.me
link
  • URL expected. Example www.paype.me
link_text
link_description

Returns
id Offer integer id

Deleting offer DELETE /offers/<id>

Delete existing offers by id

Name Required Description Expected
id YES Parameter in URL
  • Integer expected.

Returns
success Boolean

Updating offer PUT /offers/<id>

Update any fields on your businesses offer. If you choose to change media or cover, all files in both fields have to be renewed.

Name Required Description Expected
category Change name of the category where offer is posted. If the category does not exist new one is created.
status Offer visible only to customers belonging to specific status group. Status groups defined in Loyalty App / Customer Info section of business management web
cover New cover image for the offer. Recommended aspect ratio 1:1 (perfect square) with minimum dimensions 640 x 640 pixels.
  • Accepted mimetypes image/gif,image/jpeg,image/png
media Replace all media, list of up to 5 files with possible mix of types image, audio and video. For images recommended aspect ratio 1:1 (perfect square) with minimum dimensions 640 x 640 pixels.
  • Accepted mimetypes audio/mp3,audio/mp4,audio/mpeg,audio/ogg,audio/vnd.rn-realaudio,audio/vnd.wave,video/avi,video/mpeg,video/mp4,video/ogg,video/quicktime,video/x-ms-wmv,image/gif,image/jpeg,image/png
id YES Offer id parameter in the URL
  • Integer expected.
type
name
subtitle
text
language
duration_from
  • Time expected with timezone in format yyyy-mm-dd hh:mm:ssTz where timezone (Tz) is +- from UTC. Example 2014-10-19 10:23:54+02
duration_to
  • Time expected with timezone in format yyyy-mm-dd hh:mm:ssTz where timezone (Tz) is +- from UTC. Example 2014-10-19 10:23:54+02
  • Time has to be in the future.
showtime_from
  • Time expected with timezone in format yyyy-mm-dd hh:mm:ssTz where timezone (Tz) is +- from UTC. Example 2014-10-19 10:23:54+02
showtime_to
  • Time expected with timezone in format yyyy-mm-dd hh:mm:ssTz where timezone (Tz) is +- from UTC. Example 2014-10-19 10:23:54+02
  • Time has to be in the future.
men_from Starting age of men to show the offer to
  • Integer expected.
men_to Maximum age of men to show the offer to
  • Integer expected.
women_from Starting age of women to show the offer to
  • Integer expected.
women_to Maximum age of women to show the offer to
  • Integer expected.
price
  • Floating point numeric value expected. Example 5.55
old_price
  • Floating point numeric value expected. Example 5.55
product_link
  • URL expected. Example www.paype.me
link
  • URL expected. Example www.paype.me
link_text
link_description

Listing offers GET /offers

Get overview of all the offers created for your business.

Returns
id Offer integer id
category
status
name
subtitle
type
language
like_count
comment_count
creation_date
published Boolean

sync


Synchronization status GET /sync

Get synchronization status.

Returns
last_customer_push_id Last customer ID you as a partner have pushed to Paype via Public API
last_customer_pull_time UNIX timestamp when you last asked for customers added via Paype systems (mobile or business web) to add to your databases.
customer_count Total amount of customers your business has in Paype systems

tickets


Creating boarding pass POST /tickets

Name Required Description Expected
email YES
  • Email expected.
phone_number YES
  • Phone number expected in international format starting with +, followed by a country code and only numeric values phone number with no spaces, dashes etc.
time YES
  • Time expected with timezone in format yyyy-mm-dd hh:mm:ssTz where timezone (Tz) is +- from UTC. Example 2014-10-19 10:23:54+02
  • Time has to be in the future.
boarding_time YES
  • Time expected in format hh:mm. Example 23:01
external_event_id YES
departure_airport YES
  • Airports 3 letter IATA code in upper case expected.
arrival_airport YES
  • Airports 3 letter IATA code in upper case expected.
seat YES
gate YES
data
data_type
  • Accepted values: qr_code,bar_code
flight_code
  • Expected airline 2 character designation code followed by up to 4 digit flight number. Example JU1051
external_ticket_id

Updating customers boarding pass. PUT /tickets/<ticket id>

Name Required Description Expected
seat
gate
flight_code
  • Expected airline 2 character designation code followed by up to 4 digit flight number. Example JU1051
external_event_id
boarding_time
  • Time expected in format hh:mm. Example 23:01
data
data_type
  • Accepted values: qr_code,bar_code
departure_airport
  • Airports 3 letter IATA code in upper case expected.
arrival_airport
  • Airports 3 letter IATA code in upper case expected.
external_ticket_type

Creating event ticket POST /tickets

Name Required Description Expected
email YES
  • Email expected.
phone_number YES
  • Phone number expected in international format starting with +, followed by a country code and only numeric values phone number with no spaces, dashes etc.
name YES
location YES
external_event_id YES
time
  • Time expected with timezone in format yyyy-mm-dd hh:mm:ssTz where timezone (Tz) is +- from UTC. Example 2014-10-19 10:23:54+02
  • Time has to be in the future.
seat
row
sector
data
data_type
  • Accepted values: qr_code,bar_code
geographic_coordinates
url
  • URL expected. Example www.paype.me
info
external_ticket_type
external_ticket_id

Updating customers event ticket. PUT /tickets/<ticket id>

Name Required Description Expected
seat
row
sector
data
data_type
  • Accepted values: qr_code,bar_code
name
location
event
geographic_coordinates
url
  • URL expected. Example www.paype.me
info
external_ticket_type

Updating flights boarding passes. PUT /tickets/?external_event_id=<flight id>

Name Required Description Expected
external_event_id YES
gate
boarding_time
  • Time expected in format hh:mm. Example 23:01
time
  • Time expected with timezone in format yyyy-mm-dd hh:mm:ssTz where timezone (Tz) is +- from UTC. Example 2014-10-19 10:23:54+02
flight_code
  • Expected airline 2 character designation code followed by up to 4 digit flight number. Example JU1051
status
  • Accepted values: ,cancelled,delayed,location_changed

Updating events tickets. PUT /tickets/?external_event_id=<event id>

Name Required Description Expected
external_event_id YES
location
status
  • Accepted values: ,cancelled,delayed,location_changed
time
  • Time expected with timezone in format yyyy-mm-dd hh:mm:ssTz where timezone (Tz) is +- from UTC. Example 2014-10-19 10:23:54+02
geographic_coordinates
url
  • URL expected. Example www.paype.me
info