PKpass API
This document describes Eurobate’s PKPASS interface for creating Apple PKPass and pushing a link via SMS message to the phone using JSON over HTTPS.
You also need to register the IP address you send from in Eurobate's system.
All new IP adresses that uses the API will be auto registered and has to be manually whitelisted by a sales person or technical department.
Pass Design and Creation from Apple on how PKPass are built
Endpoint URL PKpass API
- https://api.eurobate.com/pkpass_api.php
Parameter description:
| Name | Required | Description |
|---|---|---|
| user | Yes | Username provided by Eurobate |
| password | Yes | Password provided by Eurobate |
| msisdn | Yes | The receiver’s mobile phone number. With preceding countrycode. For example: msisdn=4799999999 |
| pkpasstemplate | Yes | Name of the template used for building the PKPass. Eurobate will provide one for you upon request. The template consists of logo, background and icons in PNG format which is used to package the PKPass together with your pkpass JSON data. To avoid unneccesarry data transfers on creation of the PKPass we store these file locally at our servers so only textual JSON data is transferred between our and your server. |
| pkpass | Yes | JSON data which defines the pass. The JSON data contains information that identifies the pass, text that appears on the pass, and other information about the pass. |
| message | Yes | The actual message text. For one SMS, the maximum length will be 160 characters. The variable #PASSURL# is put into the text so we can replace this with the actual uniq link to download the PKPass to the endusers phone. |
| originator | Yes | A text or GSM number identifying the sender. If it is a GSM number then you must prefix it with the countrycode (without + sign). Do not use space or special characters. Field length is 15 if numeric, or 11 if alphanumeric. The limitations are due to operator and phone differences. |
| ttl | no | Time To Live. How long should the message be attempted delivered. Legal values are between 5 minutes and 72 hours and is specified in seconds. For example ttl=7200 is two hours. If the message is not delivered within the specified ttl, it will be discarded and get ”failed” status. Default value is 24 hours. |
| dlrurl | no | Specifies the url for receiving delivery reports. (See below for more information) |
| simulate | no | 0 = off (default), 1 = on. Simulates a batch sending of messages, nothing will actually be sendt to the phone. You can use this when you want to test the API. |
PKpass result
The result will contain the following parameters:
| Parameter | Value |
|---|---|
| msisdn | The gsm number with country code |
| transactionid | Contains the unique message identifier set by the SMS gateway if reportID is set. |
| error | A numerical error code (see below) |
| info | A textual description of the error. (see below) |
| messageParts | The number of SMS the full message consists of. |
| ttl | TTL set for this message |
| logon | Status for logon |
| pkpass | Status for PKPass |
| pkpasstemplate | Value of pkpasstemplate |
| simulate | Value of simulate if set |
| serialnumber | The autogenerated serial number for the PKPass |
| landingpageurl | The landing page url sent to the end user replace by #PKPASS# variablel in the sms |
| directurl | Direct url to the pkpass for immediate download omitting the landing page. |
Error Codes
| Error code | Error string |
|---|---|
| 0 | Ok |
| 1 | Missing parameters |
| 2 | Wrong user/password |
| 3 | IP not authorized |
| 4 | Network error |
| 5 | Message body is not valid |
| 6 | An error occurred when sending the message to the operator |
| 7 | Wrong number format |
| 8 | User not allowed |
| 9 | Unspecified error |
| 10 | Illegal originator |
| 11 | Countrycode not allowed Your account is not open for this country, contact you sales person |
| 12 | Not in use |
| 13 | PKPass is missing! |
| 14 | PKPass could not be created |
| 15 | PKPasstemplate id is missing |
| 16 | JSON decode error |
| 17 | PKPasstemplate directory does not exist |
| 18 | Invalid sendtime date format. Valid dateformat: YYYY-MM-DD HH:MM |
| 19 | Date for sending is too far into the future |
Delivery reports
It is possible to receive delivery reports (DLR) from the operator network with information on the status of the message sendt to the phone. To set it up you will need a script on your server that can receive the DLR. This script will be called by Eurobate each time the status changes. You specify the URL to this script on parameter dlrurl.
For example: dlrurl = https://host.com/script.php?myid=1234&ebmsgid=MSGID&status=STATUS
Possible parameters to be parsed to the correct values are:
| Value | Description |
|---|---|
| MSGID | Unique Eurobate messageid |
| STATUS | One of the following operator delivery statuses |
| AVSENDER | Originator of the message |
| DELER | Number of parts the message consists of |
| MCC | Mobile country code, or ‘0’ if unknown |
| MNC | Mobile network code, or ‘0’ if unknown |
| LEVERINGSTID | Time the message was delivered, or empty if not provided by operator. |
| UUID | Universally unique identifier of the sms transaction if sendtime is used. |
Encoding
The message encoding can have one of the following autodetected encodings ISO-8859-1 or UTF-8. The encoding of the message determines the alphabet used for the sms encoding. The sms encoding is either GSM 7-bit or UCS-2 (16 bit).
It is the sms encoding that determines how many characters a single sms or a part in a concatenated sms can contain.
When using ISO-8859-1 as encoding, Message encoding is always done in GSM 7bit alphabet. Some characters in the ISO-8859-1 character set do not exist in the GSM-7bit character set. These characters will typically be replaced with a question mark character in the resulting sms message.
When using UTF-8 all characters must be in the GSM-7bit alphabet. If at least one character is not in the GSM 7-bit alphabet, UCS-2 encoding will be used in the resulting sms message. Messages with UCS-2 encoding allows for less characters before the message is split into multiple parts.
GSM encoding:
- 1 standard SMS message = up to 160 characters
- 2 concatenated SMS messages = up to 306 characters
- 3 concatenated SMS messages = up to 459 characters
UCS-2 encoding:
- 1 standard SMS message = up to 70 characters
- 2 concatenated SMS messages = up to 134 characters
- 3 concatenated SMS messages = up to 201 characters
TESTING
We have provided a couple of example clients in PHP if you would like to test this. If you already have a username and password from Eurobate for pushing SMS you can use this. Otherwise contact us for a test account.
Variables that must be set in the PKPass JSON data:
#PASSTYPEID#
#TEAMID#
#SERNO#
These variables are replaced by us to proper values.
PHP example
<?php
$customer[] = array('gsm'=>4799999991,'navn'=>'Ola Nordmann','mnr'=>'99956','gyldig'=>'05/20');
$customer[] = array('gsm'=>4799999992,'navn'=>'Kari Nordmann','mnr'=>'654321','gyldig'=>'12/20');
$customer[] = array('gsm'=>4799999993,'navn'=>'Thomas Toget','mnr'=>'66666','gyldig'=>'06/20');
foreach($customer as $r) {
$messages = array();
#echo $r['gsm'].' '.$r['navn']."\n";
$pkpass ='
{
"passTypeIdentifier": "#PASSTYPEID#",
"formatVersion": 1,
"organizationName": "Eurobate",
"teamIdentifier": "#TEAMID#",
"serialNumber": "#SERNO#",
"backgroundColor": "rgb(151,184,201)",
"foregroundColor": "rgb(255,255,255)",
"labelColor": "rgb(255,255,255)",
"logoText": "",
"description": "Medlemskort",
"eventTicket": {
"secondaryFields": [
{
"key": "navn",
"label": "NAVN",
"value": "'.$r['navn'].'"
},
{
"key": "medlemsnummer",
"label": "MEDLEMSNUMMER",
"value": "'.$r['mnr'].'"
}
],
"auxiliaryFields": [
{
"key": "valid",
"label": "GYLDIG TIL",
"value": "'.$r['gyldig'].'"
}
],
"backFields": [
{
"key": "medlemsnummer",
"label": "Medlemsnummer",
"value": "'.$r['mnr'].'"
},
{
"key": "navn",
"label": "Navn",
"value": "'.$r['navn'].'"
},
{
"key": "gyldig",
"label": "Gyldig til",
"value": "'.$r['gyldig'].'"
}
]
},
"barcode": {
"format": "PKBarcodeFormatQR",
"message": "'.$r['mnr'].'",
"messageEncoding": "iso-8859-1"
}
}';
$pkpass_array =json_decode($pkpass);
$user='YOURUSER';
$password='YOURPASSWORD';
$simulate =1;
$ttl = 300; # SMS time to live before expire at SMSC
$msisdn = $r['gsm'];
$originator = 'Eurobate';
$message = 'Hei her er ditt medlemskort: #PASSURL#';
#$dlrurl = 'dlrtest.php';
### Start timing of JSON SMS API
$time_start = microtime(true);
$i=0;
$arr = array(
'user' =>$user,
'password' => $password,
'simulate'=>$simulate,
'ttl' => $ttl,
'originator' => $originator,
'msisdn' =>$msisdn,
'message' => $message,
'dlrurl'=>'',
'pkpasstemplate' => 1,
'pkpass' => $pkpass_array
);
$json = json_encode($arr);
$jsond=json_decode($json);
## DEBUG - output of json array sendt to json API
echo $json."\n\n";
$url = 'https://api.eurobate.com/pkpass_api.php';
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($curl, CURLOPT_POSTFIELDS, $json);
if (!$buffer = curl_exec($curl)) {
$buffer = 'EMPTY BUFFER';
}
echo $buffer;
curl_close($curl);
$jsond=json_decode($buffer);
#End timing of JSON SMS API
$time_end = microtime(true);
$execution_time = ($time_end - $time_start);
echo 'Total time = '.$execution_time."\n";
}
?>
Json example output
Sending sms message and creating PKPass membercard :
{
"user": "YOURUSERNAME",
"password": "YOURPASSWORD",
"simulate": 1,
"ttl": 300,
"originator": "Eurobate",
"msisdn": 4799999999,
"message": "Hei her er ditt medlemskort: #PASSURL#",
"dlrurl": "",
"pkpasstemplate": 1,
"pkpass": {
"passTypeIdentifier": "#PASSTYPEID#",
"formatVersion": 1,
"organizationName": "Eurobate",
"teamIdentifier": "#TEAMID#",
"serialNumber": "#SERNO#",
"backgroundColor": "rgb(151,184,201)",
"foregroundColor": "rgb(255,255,255)",
"labelColor": "rgb(255,255,255)",
"logoText": "",
"description": "Medlemskort",
"eventTicket": {
"secondaryFields": [
{
"key": "navn",
"label": "NAVN",
"value": "Ola Nordmann"
},
{
"key": "medlemsnummer",
"label": "MEDLEMSNUMMER",
"value": "99956"
}
],
"auxiliaryFields": [
{
"key": "valid",
"label": "GYLDIG TIL",
"value": "05/20"
}
],
"backFields": [
{
"key": "medlemsnummer",
"label": "Medlemsnummer",
"value": "99956"
},
{
"key": "navn",
"label": "Navn",
"value": "Ola Nordmann"
},
{
"key": "gyldig",
"label": "Gyldig til",
"value": "05/20"
}
]
},
"barcode": {
"format": "PKBarcodeFormatQR",
"message": "99956",
"messageEncoding": "iso-8859-1"
}
}
}
Result:
{
"simulate": 1,
"ttl": 300,
"pkpass": "OK",
"pkpasstemplate": 1,
"serialnumber": "5ce648d79abbb",
"landingpageurl": "https://m.eurobate.com/?id=5ce648d79abbb",
"directurl": "https://m.eurobate.com/pkpass.php?id=5ce648d79abbb",
"LOGON": "OK",
"messages": [
{
"msisdn": 4799999999,
"transactionid": 1314453,
"error": 0,
"info": "Ok",
"messageParts": 1
}
]
}
PKpass on iPhone
Eurobate AS - www.eurobate.no