Apple Proximity Token API

This guide describes the Apple Proximity Token backend API used by iOS SDK. The iOS SDK uses this token to communicate with the Apple proximity/payment card reader. It focuses on the request/response contract for generating the token that the iOS SDK uses to communicate with the Apple payment card reader.

All requests must be authenticated with a JWT as described in the JWT Integration Guide (see JWT Integration Guide) and follow the header formats in API Docs - Authentication.

---

Generate Apple Proximity Token

POST https://kernelserver.{env}.haloplus.io/apple/proximity-token

Path Parameters

Name	Type	Description
env*	String	Backend environment [dev, qa, prod]

Headers

Name	Type	Description
Authorization Bearer*	String	Required. JWT generated by your backend (see JWT guide). The token must represent the merchant.

Request Body

This endpoint does not require a request body.

Responses

200: OK

{
  "token": "eyJhbGciOiJFUzI1NiIsImtpZCI6Ij..",
  "expiresAt": "2026-03-20T07:56:15.000Z",
  "issuedAt": "2026-03-18T07:56:15.000Z",
  "jwtId": "0c095014-1472-418f-82b0-8ed46299e10f"
}

500: Internal Server Error

{
  "error": "Internal server error during token generation"
}

Response Field Descriptions

Field	Type	Description
token	String	Proximity token (JWT) used by the iOS SDK / reader integration
expiresAt	String	ISO‑8601 timestamp indicating when the token will expire (server time)
issuedAt	String	ISO‑8601 timestamp indicating when the token was issued (server time)
jwtId	String	Unique identifier (UUID) for this token instance, used for traceability/logging

Error Conditions

• 401 Unauthorized: The Authorization JWT is missing, invalid, expired, or signed with an unknown key.
• 403 Forbidden: The JWT user does not have permission to create an Apple proximity token (missing createAppleProximityToken right).
• 500 Internal Server Error: The JWT is syntactically valid but missing required business claims or configuration, for example:
  • Missing mbn: Merchant business name is required.
  • Missing mcc: Merchant category code is required.
  • Missing or invalid terminal profile ID:
    • x-tid claim is missing from the JWT, or
    • x-tid does not match a configured terminal profile ID (appleTerminalProfileId) for the acquirer.