Endpoints, parameters and response codes for the Benten platform. Building with .NET? The Benten SDK handles all of this for you.
Using .NET? Install the Benten SDK with dotnet add package Benten.SDK. It handles tokens, WebSocket connections and response parsing for every request below. Use this page if you're integrating from another language or want to see the protocol the SDK uses.
Get an Access Token (JWT)
Exchange your API key for a JSON Web Token (JWT). Every other request on this page needs this token. Create API keys on the developer dashboard: sign in, choose Create API key and copy the key (it starts with bnt_sk_). Keep API keys on your server; never put them in a mobile app or web page.
The token expires after one hour. Get a new one before it expires; the Benten SDK does this for you. A revoked API key can't be exchanged for new tokens, so it stops working within an hour.
Request
POST
https://api.bententechnologies.com/v2/auth/token
Parameter
Parameters
Type
Description
ApiKey
String
Your API key (bnt_sk_…)
Timeout
int
Optional. Token lifetime in seconds, between 60 and 3600. Default 3600 (one hour).
API to register User’s online account with Benten. This request requires a valid JWT. Once the account has been created successfully, Benten will inform the client’s device of the newly created account.
Client Account Inactive. Please contact Benten support
404
BSC4022
No registered device found for given phone number
400
BSC4023
Account already exists for given phone number
400
BSC4024
Failed to create Online Account for given username and merchant site
500
N/A
Internal Server Error
200
N/A
Success - Online Account saved successfully
Response Example
{
"Response": “Success”
}
Register Credit Card Info
API to register user’s credit card info with Benten. This request requires a valid JWT. Once the credit card info has been created successfully, Benten server will inform the client’s device of the newly created Credit Card info. A credit card can only be configured against one single phone number. Credit card number is salted and hashed before it is saved in the database.
No registered device found for the given country and phone number.
400
BSC4027
Failed to create CC for the given Card Number and Zipcode
500
N/A
Internal Server Error
200
N/A
Success - CC Info saved successfully
Response Example
{
"Response": “Success”
}
Register IoT Device Info
API to register User’s IoT device with Benten. This request requires a valid JWT. Once the IoT has been created successfully, Benten server will inform the client’s device of the newly created IoT device.
API to allow user to log into their online account using a phone number and a username. This request requires a valid JWT. Benten server will send a message to BentenApp on the user’s associated iOS/Android device requesting permission to continue with the login process. The response will either be Allow or Deny.
After the Socket Open request is received, server will wait for 10 seconds to receive from Client the following json message:
Parameters
Element
Value
RequestType
LoginRequest
JWT
JWT Token
Country
Country name associated with the phone number
PhoneNumber
Phone number of the device to be used to process login request
RequestId
Optional value. Unique ID for this request, e.g. a new GUID. Use a fresh value for every request and never reuse one. Server will assign one, if this value is not provided
UserName
Optional value. Username of the online account to which access is being requested
Request IDs: send a new RequestId (for example a new GUID) with every request. The server uses it to route the user's answer back to your connection, so a fixed or reused value can mix up replies between requests. The Benten SDK does this for you.
Server will forward this login request to the registered device for the given phone number. Once server receives user’s response of either Allow or Deny, the server will send the response back the client. If the user does not respond within 60 seconds, the server will send NoResponse string back to the Client.
Response Parameters
Element
Value
_id / RequestId
Your request's RequestId, echoed back: as _id in Allow/Deny responses, as RequestId in NoResponse and error responses
PhoneNumber
Phone number of the device responding
Country
Country of the phone number
Response
Allow/Deny/NoResponse/BentenStatusCode/Error Text
RequestType
Value will be same as in request JSON. Available only for error response.
Username
Value will be same as in request JSON. Available only for error response.
Response Example (Notification from server to client)
Please NOTE: Any response other than Allow/Deny/NoResponse should be considered as error response. It is client’s responsibility to handle such errors accordingly.
Besides the response above, Client may receive the following error response, depending on the situation. Response will contain the actual error message or a Benten error status code, where available. For example:
API to allow user to either approve or reject a credit card transaction. This request requires a valid JWT. Benten will send a message to BentenApp on the user’s associated iOS/Android device requesting permission to continue with the credit card transaction. The response will either be Allow or Deny.
After the Socket Open request is received, server will wait for 10 seconds to receive from Client the following json message:
Parameters
Element
Value
JWT
JWT token
CreditCardId
Benten Id of the associated Credit Card
Amount
Transaction Amount
Retailer
Retailer associated with this transaction
RequestId
Optional value. Unique ID for this request, e.g. a new GUID. Use a fresh value for every request and never reuse one. Server will assign one, if this value is not provided
Server will forward this Credit Card transaction request to the registered device for this credit card. Once server receives user’s response of either Allow or Deny, the server will send the response back the client.
Response Parameters
Element
Value
_id / RequestId
Your request's RequestId, echoed back: as _id in Allow/Deny responses, as RequestId in NoResponse and error responses
PhoneNumber
Phone number of the device responding. Available only for non-error response.
Country
Country of the phone number. Available only for non-error response.
Response
Allow/Deny/NoResponse/BentenStatusCode/Error Text
RequestType
Value will be same as in request JSON. Available only for error response.
CreditCardId
Value will be same as in request JSON. Available only for error response.
Amount
Value will be same as in request JSON. Available only for error response.
Retailer
Value will be same as in request JSON. Available only for error response.
Response Example (Notification from server to client)
Please NOTE: Any response other than Allow/Deny/NoResponse should be considered as error response. It is client’s responsibility to handle such errors accordingly.
Besides the response above, Client may receive the following error response, depending on the situation. Response will contain the actual error message. For example:
BSC4056 - Device associated with the given country and phone number is not active. Please activate your Device first
BSC4059 - System currently unavailable. Please contact Benten support if this error persists
BSC4073 - Invalid request. The request message could not be read
BSC4074 - Request message is too large
IoT Setting Change Request
API to allow user to either approve or reject an IoT Setting change transaction. This request requires a valid JWT. Benten will send a message to BentenApp on the user’s associated iOS/Android devices requesting permission to continue with the IoT Setting change transaction. User can respond using any one of his or her registered devices. The response will either be Allow or Deny.
After the Socket Open request is received, server will wait for 10 seconds to receive from Client the following json message:
Parameters
Element
Value
RequestType
IoTSettingChange
JWT
JWT token
Name
Name of the IoT device
MacAddress
Mac Address of the IoT device
SettingChange
Setting change that needs to be applied to the Iot Device
RequestId
Optional value. Unique ID for this request, e.g. a new GUID. Use a fresh value for every request and never reuse one. Server will assign one, if this value is not provided
Server will forward this IoT Setting change request to the registered devices for this IoT device. Once server receives user’s response of either Allow or Deny, the server will send the response back the client.
Response Parameters
Element
Value
_id / RequestId
Your request's RequestId, echoed back: as _id in Allow/Deny responses, as RequestId in NoResponse and error responses
PhoneNumber
Phone number of the device responding. Available only for non-error response
Country
Country of the phone number. Available only for non-error response
Response
Allow/Deny/NoResponse/BentenStatusCode/Error Text
RequestType
Value will be same as in request JSON. Available only for error response.
Name
Value will be same as in request JSON. Available only for error response.
MacAddress
Value will be same as in request JSON. Available only for error response.
SettingChange
Value will be same as in request JSON. Available only for error response.
Response Example (Notification from server to client)
Please NOTE: Any response other than Allow/Deny/NoResponse should be considered as error response. It is client’s responsibility to handle such errors accordingly.
Besides the response above, Client may receive the following error response, depending on the situation. Response will contain the actual error message. For example:
Response Example (Error)
{
"RequestId": "552b6c85-71de-468e-b5b0-4b5497688d75",
"Name": "LRT",
"MacAddress": "AA-AA-AA-AA-AA-07",
"RequestType": "IoTSettingChange",
"SettingChange": "Change temp from 72 to 68",
"Response": "BSC4019"
}
Following error messages can be sent by the server to the Client:
Message received is not a WebSocket request!
BSC4049 - Invalid Token - Missing Client id
BSC4019 - Invalid Token
One or more required field/s is missing!
BSC4020 - No registered user found for given Client Id
BSC4021 - Client Account Inactive. Please contact Benten support
BSC4062 - No IoT device found for the given Name and MacAddress
BSC4064 - No devices configured for the given IoT device
BSC4059 - System currently unavailable. Please contact Benten support if this error persists
BSC4073 - Invalid request. The request message could not be read
BSC4074 - Request message is too large
Generic Notification
API to allow user to either approve or reject a Generic Notification request. This request requires a valid JWT. Benten will send a message to the user’s associated iOS/Android device requesting user to respond. The response will either be Allow or Deny.
The user only needs the Benten App installed and activated on their phone; they don’t need an account registered with you first. To protect users from floods of prompts, one developer account can send at most 30 generic notifications to the same phone in any 10 minutes. More are refused with BSC4079.
After the Socket Open request is received, server will wait for 10 seconds to receive from Client the following json message:
Parameters
Element
Value
JWT
JWT Token
RequestType
GenericNotification
NotificationSubType
Title to be displayed for the notification
Country
Country associated with the Device Phone Number
PhoneNumber
Phone number associated with the Device where the notification is to be delivered
Line1Placeholder
Text to be used as a placeholder for Line1
Line1
Any text that should be displayed on the first line of the Notification
Line2Placeholder
Text to be used as a placeholder for Line2
Line2
Any text that should be displayed on the second line of the Notification
Line3Placeholder
Text to be used as a placeholder for Line3
Line3
Any text that should be displayed on the third line of the Notification
RequestId
Optional value. Unique ID for this request, e.g. a new GUID. Use a fresh value for every request and never reuse one. Server will assign one, if this value is not provided
Request Example
{
"jwt":"xxxxx",
"RequestType": "Generic Request",
"Country": "United States",
"PhoneNumber": "6501111111",
"NotificationSubType":"Medical Data Req",
"Line1Placeholder": "Doctor",
"Line1":"Bilbo Baggins",
"Line2Placeholder": "Patient",
"Line2":"Alfie Noakes",
"Line3Placeholder": "Desc",
"Line3":"Request to review Test data"
}
Server will forward this Generic Notification request to the device for given country and phone number. Once server receives user’s response of either Allow or Deny, the server will send the response back the client.
Response Parameters
Element
Value
_id / RequestId
Your request's RequestId, echoed back: as _id in Allow/Deny responses, as RequestId in NoResponse and error responses
Country
Country of the phone number.
PhoneNumber
Phone number of the device responding.
Response
Allow/Deny/NoResponse/BentenStatusCode/Error Text
RequestType
Value will be same as in request JSON. Available only for error response.
NotificationSubType
Value will be same as in request JSON. Available only for error response.
Line1
Value will be same as in request JSON. Available only for error response.
Line2
Value will be same as in request JSON. Available only for error response.
Line3
Value will be same as in request JSON. Available only for error response.
Response Example (Notification from server to client)
Please NOTE: Any response other than Allow or Deny should be considered as error response. It is client’s responsibility to handle such errors accordingly.
Besides the response above, Client may receive the following error response, depending on the situation. Response will contain the actual error message or Benten status code, if available. For example: