Passquare
Sign up
Log in

API documentation.

Passquare API for working with Apple & Google Wallet Passes and push notifications
Version 2.7.6
When working with the API, it is mandatory to store the customer database in your system. Upon receiving an wallet card by the customer, the Passquare system will send a hook to your system, which you must process and save the customer data in your database. If the data gets updated in your system (for example, discount percentage or bonus), you need to send a hook to Passquare. The Passquare system will then update the customer's card and send a push notification to it. In the examples for clarity, JSON code includes comments according to the JSON5 specification. However, comments cannot be used in JSON code when working with the API.

Transferring data from Passquare to your CRM

The Passquare service calls the URL specified in your integration settings (URL integration type). Your address must be HTTPS, and there should be a working script at that address. For access control, you can use either "http basic authentication" or "crm_key".
If you choose "http basic authentication," specify your login and password in the integration settings. If you choose "crm_key," specify your "crm_key" as the password in the integration settings, leaving the login field blank.
The parameters "Organization ID", "Program ID", "Wallet ID" from the integration settings are transferred in the request headers "X-organization-id", "X-program-id", "X-wallet-id".
For access control, you can also use IP filtering (164.90.200.81). During testing, you can use the service https://webhook.site.
In all methods, the phone number must be in international format (E.164 format).
Method 1.1. createCustomer [POST]
Registering a customer's card.
https://webhook.site
{
  "crm_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "method": "createCustomer",
  "customer": {
    "name": "Joe",
    "surname": "Master",
    "middlename": "Remaster",
    "email": "joe@passquare.com",
    "phone": "+420000000001",
    "birthday": "1980-01-25",
    "cardNumbers": ["120"],
    "cardTracks": [{"card": "120", "track": "7862374687"}],
    "extra": {
      "sex": "male", //optional parameter
      "promo": "BBBBB" //promo code entered by the customer during registration
    },
    "balance": 300.00,
    "bonus": 10.00,
    "discount": 25.00,
    "promo": "AAAAA", //customer's referral promo code
    "referCustomerPhone": "+420000000002"
  }
}
The handler receives the data, checks for the presence of the customer in the CRM system based on the phone number. If there is no customer with such a phone number, it needs to be created, a card needs to be created for them, and return the "customerId". If a customer with such a phone number exists, the handler should update the data for this customer, add a new card (replace if the CRM system does not support multiple cards), and return the "customerId". Card numbers are assigned on the Passquare side, and during integration, you need to specify the starting number of the free range of cards in the settings.
The required response from CRM:
"customerId" - a unique identifier of the user in your CRM.
Example of a successful response (HTTP 200):
{"customerId": "6d2845ff-0a07-11e7-25df-d8d18565926f"}
Example of a failed response (HTTP 400):
{"error": "Detailed error description..."}
Method 1.2. readBalance [POST]
Balance request, necessary for manual querying for updates on the client's card balance and percentage.
Example of a request:
https://webhook.site
{
  "crm_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "method": "readBalance",
  "customer": {
    "phone": "+420000000001",
    "cardNumbers": ["120"]
  }
}
The handler should return the balance/bonus/discount for the specified customer (identification by phone number and card number).
Example of a response:
{
  "success": true,
  "bonus" : 12.5,
  "balance": 5,
  "discount": 17.88
}
Method 1.3. addBalance [POST]
Hook for adding bonuses, necessary for granting bonuses.
Example of a request:
https://webhook.site
{
  "crm_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "method": "addBalance",
  "customer": {
    "phone": "+420000000001",
    "cardNumbers": ["120"],
    "sum": 50.00,
    "transactionId": "id/guid",
    "lifetime": 14 //optional, bonus lifetime in days (24h)
  }
}
The handler should add balance to the specified customer (identification by phone number and card number). If the "lifetime" parameter is passed, this accrual must be set to burn after a specified number of days (24h).
Example of a response:
{
  "success": true
}

Requests from your CRM to Passquare

It is used for creating/updating wallet cards when information changes in your CRM and for reading information from Passquare. During testing, you can use the application https://postman.com.
Method 2.1. status [POST]
Checking the private key and status of your account.
URL: 
https://core.passquare.com/api/v2/status
Data:
{
  "app_key": "private_key"
}
Response:
{
  "app": "account_name",
  "balance": 980.00
}
Method 2.2. user_create_or_update [POST]
Updating or creating a customer in Passquare, where the phone number is the key.
URL:
https://core.passquare.com/api/v2/crm/user_create_or_update
Data (custom variables can also be passed in the block):
{
  "app_key": "private_key",
  "name": "name",
  "phone": "customer's mobile phone",
  "email": "email address", //optional
  "surname": "surname", //optional
  "middlename": "patronymic", //optional
  "birthday": "date of birth dd.mm.yyyy", //optional
  "discount": "discount percentage", //float, default 0
  "bonus": "bonus percentage", //float, default 0
  "balance": "amount of bonuses", //float, default 0
  "card_track": "...", //new card track, when changing the track the card is overwritten in your CRM
  "template_uuid": "...", //uuid of the card design template
  "customerId": "customer identifier in your CRM",
  "link": "link to the card issuance form",
  "sms": "Your card: %link%" //SMS to send to the customer
}
To create a personalized link to the form for installing the card, you need to pass the link to the form in the "link" field. In the text of the SMS message, %link% will be replaced with the personalized link for obtaining the card.
Response:
{
  "success": "message about customer creation", //bool
  "sms_send": "message about SMS sending", //bool
  "card": "message about card creation", //bool
  "card_number": "created card number", //string
  "card_track": "created card track", //string
  "card_url": "personalized link to Apple Wallet card", //url
  "card_gpay_url": "personalized link to Google Pay card", //url
  "form_url": "personalized link to the form", //url
  "user_hash": "hash for form personalization" //hash
}
Example of creating a customer:
When creating a customer, if you want to send them an SMS, you need to specify the link to your form in the "link" field and the text of the message itself in the "sms" field, as shown in the example.
https://core.passquare.com/api/v2/crm/user_create_or_update
{
  "app_key" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "phone" : "+420000000001",
  "email" : "joe@passquare.com",
  "name" : "Joe",
  "surname" : "Master",
  "middlename" : "Remaster",
  "birthday" : "11.11.1980",
  "discount" : 0,
  "bonus" : 3.50,
  "balance" : 100,
  "link" : "https://form.passquare.com/00000000-0000-0000-0000-000000000000",
  "sms" : "Your card: %link%"
}
Example of SMS message text (the card is issued via the link without entering personal data):
"Your card: https://form.passquare.com/00000000-0000-0000-0000/?hash=2f10171a33f66f3bc425335690ec880c"
Changing the card balance. Additionally, if push to change the balance is configured in the card template, a message about the balance change will be displayed on the customer's phone:
https://core.passquare.com/api/v2/crm/user_create_or_update
{
  "app_key" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "phone" : "+420000000001",
  "balance" : 120
}
Sending a personalized push notification to wallet card:
When sending a push, do not change the variables to which notifications are bound in the card design template. If you send a push and simultaneously change such a variable, a push with a system notification will be sent that the card has been modified.
https://core.passquare.com/api/v2/crm/user_create_or_update
{
  "app_key" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "phone" : "420000000001",
  "push" : "Your order is ready for pickup!"
}
Sending a personalized web push notification (requires connected web push from the Marketplace).
https://core.passquare.com/api/v2/crm/user_create_or_update
{
  "app_key" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "phone" : "+420000000001",
  "send_webpush" : "Your order is ready for pickup!"
}
Sending a personalized Telegram message (requires connected Telegram from the Marketplace).
https://core.passquare.com/api/v2/crm/user_create_or_update
{
  "app_key" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "phone" : "+420000000001",
  "send_telegram" : "Your order is ready for pickup!"
}
Method 2.3. read_customer [POST]
Retrieving customer data by phone number or card number.
URL:
https://core.passquare.com/api/v2/crm/read_customer
Parameters (use "phone" or "card"):
{
  "app_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "phone": "", //phone number
  "card": "", //card number
  "invites": bool, //whether referral information is needed
  "installs": bool //whether information about card installations is needed
}
Response:
{
  "customer": {
    "phone": "+420000000001",
    "email": "joe@passquare.com",
    "name": "Joe",
    "surname": "Master",
    "middlename": "Remaster",
    "birthday": "11.11.1980",
    "cardNumbers": ["120"],
    "cardTracks": [{"card": "120", "track": "78374598987"}],
    "cardInstalls": [{"card": "120", "install": true}], //the flag for card installations
    "discount": 4.5,
    "bonus": 0,
    "balance": 0,
    "template_uuid": "...", //uuid of card design template
    "remoteId": "6326", //ID in the external CRM system
    "invitedBy": "+420000000000",
    "invites": [ //referral information
      "+420000000011",
      "+420000000012"
    ]
  }
}
Method 2.4. read_customers [POST]
Get a list of customers by registration date.
URL:
https://core.passquare.com/api/v2/crm/read_customers
Parameters:
{
  "app_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "start_date": "datetime", //01.01.2020
  "end_date": "datetime", //31.12.2020 23:59:59
  "installed": true,
  "offset": 0
}
Parameter "installed":
  • If the parameter is not specified, the method will return all customers.
  • If the parameter is true, the method will return customers with installed cards.
  • If the parameter is false, the method will return customers with cards not installed.
  • The method returns the first 100 customers. To retrieve the next set of customers, use the offset argument.
Response:
{
  "customers":
  [
    "+420000000011",
    "+420000000012"
  ]
}
Method 2.5. push/create [POST]
Create a push notification campaign for the entire customer base or for a segment.
The type of campaign can be push to cards, web push, or Telegram.
For web push and Telegram, a connected application from the Marketplace is required.
After creating the push notification campaign, it needs to be sent using method 2.5.
URL:
https://core.passquare.com/api/v2/crm/push/create
Parameters:
{
  "app_key": "", //private key
  "message": "", //message text
  "type": "", //message type - text, webpush, telegram
  "name": "", //name, displayed in the dashboard, optional parameter
  "segment_uuid": "" //segment identifier, optional parameter
}
Response:
{
  "result": {
    "name": "Push#0000",
    "uuid": "00000000-0000-0000-0000-000000000000",
    "message": "Test push!"
  }
}
Method 2.6. push/send [POST]
Execute the push notification campaign.
URL:
https://core.passquare.com/api/v2/crm/push/send
Parameters:
{
  "app_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "push_uuid": "00000000-0000-0000-0000-000000000000" //push campaign identifier
}
Appendix A. Example CURL from Linux console (Cygwin for Windows).
curl -d '{"app_key":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "phone":"+420000000001", "email":"joe@passquare.com", "name":"Joe", "surname":"Master", "middlename":"Remaster", "birthday":"03.05.1980", "discount":0, "bonus":5, "balance":200}' -H "Content-Type: application/json" -X POST https://core.passquare.com/api/v2/crm/user_create_or_update
Appendix B. Example implementation in PHP.
<?php

$url = 'https://core.passquare.com/api/v2/crm/user_create_or_update';
$post = [
  'app_key' => 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  'phone' => '+420000000001',
  'email' => 'joe@passquare.com',
  'name' => 'Joe',
  'surname' => 'Master',
  'middlename' => 'Remaster',
  'birthday' => '03.05.1980',
  'discount' => 0,
  'bonus' => 4.5,
  'balance' => 100
];

$data_string = json_encode($post);

$options = [
  CURLOPT_TIMEOUT => 30,
  CURLOPT_POST => 1,
  CURLOPT_HEADER => 0,
  CURLOPT_URL => $url,
  CURLOPT_FRESH_CONNECT => 1,
  CURLOPT_RETURNTRANSFER => 1,
  CURLOPT_FORBID_REUSE => 1,
  CURLOPT_SSL_VERIFYHOST => 2,
  CURLOPT_SSL_VERIFYPEER => true,
  CURLOPT_POSTFIELDS => $data_string,
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'Content-Length: '.strlen($data_string)
  ]
];

$ch = curl_init();
curl_setopt_array($ch, $options);
$result = curl_exec($ch);

print_r($result);

?>

Notes

1. When working with the API, there are limits on the number of requests:
  • Base plan: 1 request/second, 60 requests/hour.
  • Advanced plan: 1 request/second, 600 requests/hour.
  • Expert plan: 1 request/second, 3600 requests/hour.
  • Exclusive plan: 1 request/second, 3600 requests/hour.
  • All requests from your system to Passquare are counted within these limits.
  • Limits can be increased upon request to technical support.
2. In the examples, comments are used in the JSON code for clarity according to the JSON5 specification. However, comments cannot be used in JSON code when working with the API.
3. In case of receiving an error, please submit a request to technical support with provided logs (request + response).
4. To transmit data about customers to your CRM, implement integration according to the group of methods - Transfer of data from Passquare to your CRM.
5. For debugging hooks during the testing phase, you can use the service https://webhook.site.
6. For debugging outgoing requests during the testing phase, you can use the application https://postman.com.