SWiP Customer Loyalty Summary API

Overview

The SWiP Customer Loyalty Summary API provides endpoints for recieving information about customer’s balance, name using phone number or AppleWallet/GoogleWallet/WalletSave pass id

Base URL: /customer-profile

Authentication: P-o-S authentication required

Authentication

Transport and protocol

The API uses HTTPS as a protocol. Messages are represented in the JSON format.

Authentification

Authentification is implemented by a static token. The token must be sent in the header of HTTP requests.

The header in every API request should include:

Field name	Value example	Description
Authorization	Bearer 8c6b8b64-6815-6084-0a3e-178401251b68	Token from the merchant’s marketing engine.
X-Merchant-ID	ABCD	The value is sent by the SWiP employee after the merchant's onboarding. Four-letter codes are used at the moment. The values can be expanded in the future.
X-Store-ID	Test storeID	The Store ID that the SWiP employee sends after the merchant's onboarding. The value is taken from the merchant's system: either the real identifier of the store or, if it cannot be received from the terminal, the value from the SWiP plugin settings.
X-Cash-ID	1231	Terminal ID in the merchant's system.
Api-Version	2	API version.

Endpoints

1. Customer Signup

GET /customer-profile

Creates a new customer account and automatically generates a discount card for the authenticated merchant.

Request Headers

Header	Type	Required	Description

Header	Type	Required	Description
`Authorization`	string	Yes	POS authentication token
`Content-Type`	string	Yes	`application/json`

Request Parameters

Parameter	Type	Required	Description

Parameter	Type	Required	Description
`phone`	string	No*	Customer phone number (8 prefix converted to 7)
`pass`	string	No*	Customer’s Apple/Google/WalletSave pass number

*- either ‘phone’ or ‘pass’ should be present in request

Response

Status: 200 OK

{
  "name": string,
  "balance": number,
  "phone": string
}

Response Fields

Field	Type	Description

Field	Type	Description
name	string	First name of customer
balance	number	amount of points
phone	string	phone number

Example

POST /customer-profile?pass=23
Authorization: Bearer <token>
Content-Type: application/json

Success Response:

HTTP/1.1 200 OK

{
  "name": "Иван",
  "balance": 1500,
  "phone": "12324343"
}

Error Responses

Common Error Codes

Status Code	Description

Status Code	Description
`400 Bad Request`	Invalid request parameters or customer blocked
`401 Unauthorized`	Missing or invalid authentication
`403 Forbidden`	Insufficient permissions
`422 Unprocessable Entity`	Business logic validation failed
`500 Internal Server Error`	Server error

Error Response Format

{
  "error": "string",
  "message": "string",
  "timestamp": "string",
  "status": "integer"
}

Error Scenarios

Scenario	Status	Description

Scenario	Status	Description
Missing phone number	400	Phone number is required for customer creation
Blacklisted phone	400	Customer phone number is blocked by merchant blacklist
Authentication failure	401	Invalid or missing POS authentication token
Service unavailable	500	External customer service is unavailable

Example Error Response

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Bad Request",
  "message": "Customer phone number is blocked by blacklist",
  "timestamp": "2023-12-21T10:30:00Z",
  "status": 400
}

Business Flow

Authentication Flow

POS Authentication: Validate merchant's POS authentication token
Merchant Context: Extract merchant ID from authenticated principal
Store Association: Link signup to specific merchant store
Permissions Check: Verify merchant has signup permissions

API SWIP Customer Loyalty Summary