SWiP Customer Signup API

Overview

The SWiP Customer Signup API provides endpoints for registering new customers directly through P-o-S terminals in the SWiP ecosystem. This API enables merchants to create customer accounts, automatically generate discount cards, and integrate with loyalty programs without requiring customers to have pre-existing accounts.

Base URL: /customer-signups

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	3	API version.

Endpoints

1. Customer Signup

POST /customer-signups

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 Body

{
  "phone": "string",
  "firstName": "string",
  "lastName": "string"
  "birthday": "string"
}

Request Parameters

Parameter	Type	Required	Description

Parameter	Type	Required	Description
`phone`	string	Yes	Customer phone number (8 prefix converted to 7)
`firstName`	string	No	Customer first name
`lastName`	string	No	Customer last name
`birthday`	string	No	Date of birth in following format `yyyy-MM-dd`

Response

Status: 204 No Content

Example

POST /customer-signups
Authorization: Bearer <token>
Content-Type: application/json

{
  "phone": "79123456789",
  "firstName": "Иван",
  "lastName": "Иванов"
  "birthday": "1990-01-24"
}

Success Response:

HTTP/1.1 204 No Content

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

Customer Signup Process

Request Validation: Validate request parameters and authentication
Phone Normalization: Convert phone number format
Blacklist Check: Verify customer phone is not blacklisted
Account Creation: Create new customer account with auto-generated device ID
Profile Setup: Complete customer profile with provided names
Discount Card Generation: Automatically create merchant-specific discount card
White Label Integration: Associate with merchant's white label configuration

Notes

Customer signup creates both account and discount card in single operation
Phone number normalization handles phone number formats
White label integration provides customized customer experience
All operations are authenticated via merchant POS credentials
Discount cards automatically generated through merchant offer system

API SWIP Customer Signup on P-o-S