Poynt API


Introduction

Poynt REST APIs provide applications an ability to integrate with Poynt Services in the cloud.


Standards

All Poynt APIs are built with commonly used RESTful design patterns in the industry. Below you'll see all the Poynt Services and Entities exposed as Resources that you can access through standard HTTP semantics. HTTP status codes are used to communicate the success/failures states, OAuth2.0 is used for API Authentication and Authorization, and HTTP methods are used to operate on the resources.

Please take a note of the common patterns listed below that would help in simplifying your integration process.

Endpoint

All Poynt APIs can be accessed at: https://services.poynt.net.

HTTP Headers

All Poynt APIs should be invoked with the following standard HTTP headers unless otherwise specified:

HTTP Status Code

All Poynt APIs return one or more of the following codes.

Dates/Times

All date time values are in GMT and is formatted in ISO 8601 format YYYY-MM-DDThh:mm:ssZ.

Resource Updates

HTTP PATCH method is used to allow updates to existing Resources using json-patch as the request payload. Currently only add, remove, and replace operations are supported.

Pagination

Pagination is controlled by five parameters for most GET collection APIs. These parameters determine the result set and allow you to paginate through them.

If-Modified-Since header
ISO8601 Time to filters result by item's last updated time.
startAt query
ISO8601 Time to filters result by a specific start time.
startOffset query
Integer offset from first item.
endAt query
ISO8601 Time to filters result by a specific end time.
limit query
Integer value 1 to 100 to limit the number of items returned. Default is 10.

Clients are encouraged to begin paging through a collection by specifying the If-Modified-Since header at the start of their paging request. A limit should also be specified to control the number of returned items. Should there be more items than can be returned, a HATEOAS link will also be returned.

If, however, the client wishes to specify a specific time window, it should use the startAt/endAt time window. This time window will be used to filter items out based on the item's updatedAt time. When startAt is specified, the server will ignore the If-Modified-Since header. If no endAt time is specified, it is assumed to be up to the latest time (now).

Clients should generally not need to use the startOffset parameter. This parameter is used by the server to control the paging range in the HATEOAS links that it generates.


Oauth

Poynt APIs are secured with OAuth 2.0 to allow merchants to share data with developer applications as appropriate. The Poynt OAuth2.0 authorization API consist of a single token resource (end point) where client applications can obtain access tokens that can be used to invoke all other APIs.


Definition

POST /token

Sample Request

curl -H "api-version:1.2" -d "grantType=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=MY.SELFSIGNED.JWT" https://services.poynt.net/token


curl -H "api-version:1.2" -H "Authorization: MY.SELFSIGNED.JWT" -d "grantType=PASSWORD&businessId=d4b4ec82-0b3a-49c9-8424-1a6c16e3562a&username=Kelly&password=1234" https://services.poynt.net/token

Sample Response

{"expiresIn":900, "accessToken":"POYNT.ISSUED.JWT", "refreshToken":"REFRESH_TOKEN", "scope":"ALL", "tokenType":"BEARER"}

token

Generate an access token with either Json Web Token (JWT) bearer, password, or refresh token grant type.

The JWT bearer grant requires that the input grantType form parameter be urn:ietf:params:oauth:grant-type:jwt-bearer as defined by the JWT Profile for OAuth 2.0 specification. A self-signed JWT token must be provided by the client that is signed using the client's private key.

The password grant requires that a self-signed JWT token be provided via the Authorization http header in addition to the business user's businessId, username, and password.

Refresh token is also granted along with Access tokens to allow applications to refresh tokens that have expired. These tokens must always be stored securely by the applications.

Response

Returns a TokenResponse.


Payments


Orders

Orders resource represents a customer's request to purchase one or more items (goods or services) from a business. As such an order contains details about all the items that we purchased, discounts applied and transactions that paid for the order. An order can be in Opened, Cancelled or Completed states. The only thing these states really tell is whether the order is active from the merchant’s perspective or not. An active order will be in Opened state. An order that the merchant is done with will be in Completed or Cancelled state. Similarly items have their own states (Ordered, Fulfilled and Returned) and transactions their own (see documentation for Transactions). Typically a merchant would want to keep the Order in Opened state until all items in the order have either been Fulfilled or Returned and all payments have been completed.


Definition

GET /businesses/{businessId}/orders

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get all orders

Get all orders that match the specified filters. If no filter is specified it will fetch all orders for the business since it started. We currently return 10 records at a time with a HATEOS link to the next 10. The following optional filters are supported:

  1. startTimeSec: the time from which to start fetching transactions,
  2. limit: the number of order to fetch,
  3. cardNumberFirst6: limit results to orders with transactions done by cards starting with these 6 numbers,
  4. cardNumberLast4: limit results to orders with transactions done by cards ending with these 4 numbers,
  5. cardExpirationMonth: limit results to orders with transactions done by cards expiring in this month,
  6. cardExpirationYear: limit results to orders with transactions done by cards expiring in this year,
  7. cardHolderFirstName: limit results to orders with transactions done by cards with this card holder first name,
  8. cardHolderLastName: limit results to orders with transactions done by cards with this card holder last name,
  9. storeId: only fetch transactions for this store.

Arguments

businessId path
string (required)
If-Modified-Since header
string (optional)
startAt query
string (optional)
startOffset query
integer (optional)
endAt query
string (optional)
limit query
integer (optional)
cardNumberFirst6 query
string (optional)
cardNumberLast4 query
string (optional)
cardExpirationMonth query
integer (optional)
cardExpirationYear query
integer (optional)
cardHolderFirstName query
string (optional)
cardHolderLastName query
string (optional)
storeId query
string (optional)
includeStaysAll query
boolean (optional)

Response

Returns a OrderList.


Definition

PUT /businesses/{businessId}/orders/{orderId}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Record order

Record an order that has already happened. A full order object must be populated as this operation will simply record what is passed to it.

Arguments

Poynt-Request-Id header
string (required)
businessId path
string (required)
orderId path
string (required)
order body
Order (optional)

Response

Returns a Order.


Definition

PATCH /businesses/{businessId}/orders/{orderId}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Update order

Update an order. This takes a JsonPatch object as request. We allow updates to order level amounts and replace on /items and /discounts.

Arguments

Poynt-Request-Id header
string (required)
businessId path
string (required)
orderId path
string (required)
patch body
JsonPatch (optional)

Response

Returns a Order.


Definition

GET /businesses/{businessId}/orders/{orderId}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get an order

Get an order (along with HATEOS links to all immediately related orders).

Arguments

If-Modified-Since header
string (optional)
businessId path
string (required)
orderId path
string (required)

Response

Returns a Order.


Definition

POST /businesses/{businessId}/orders/{orderId}/cancel

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Cancel order

(DEPRECATED) This is a convenience operation that will undo everything in this order.

Arguments

Poynt-Request-Id header
string (required)
businessId path
string (required)
orderId path
string (required)

Response

Returns a Order.


Transactions

Transactions resource represents a financial transaction. It has operations to manage the entire lifecycle of a transaction initiated through MSR, manual key-in, NFC or EMV. It provides operations to:

  1. save a transaction at the Poynt server for later processing,
  2. record a transaction that has already happened -- maybe offline or through some other path with the acquirer,
  3. initiate interaction with the acquirer to move funds (for a previously saved transaction or a brand new transaction),
  4. capture, void or update a previously authorized transaction,
  5. refund a previously completed transaction,
  6. record EMV tags associated with an authorized transaction or
  7. get details about all transactions meeting a certain filter criteria.

Definition

GET /businesses/{businessId}/transactions

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get all transactions

Get all transactions that match the specified filters. If no filter is specified it will fetch all transactions for the business since it started. We currently return 10 records at a time with a HATEOS link to the next 10. The following optional filters are supported:

  1. If-Modified-Since: will only return transaction since If-Modified-Since,
  2. startAt: the time in seconds from which to start fetching transactions,
  3. startOffset: for all transactions at startAt the offset from where to start,
  4. endAt: the time in seconds at which to end,
  5. limit: the number of transactions to fetch in one go,
  6. storeId: only fetch transactions for this store,
  7. deviceId: only fetch transactions for this device,
  8. searchKey: instead of specifying which exact field to look at, the client can simply pass this search key and the server will look at various different fields,
  9. cardNumberFirst6: limit results to transactions done by cards starting with these 6 numbers,
  10. cardNumberLast4: limit results to transactions done by cards ending with these 4 numbers,
  11. cardExpirationMonth: limit results to transactions done by cards expiring in this month,
  12. cardExpirationYear: limit results to transactions done by cards expiring in this year,
  13. cardHolderFirstName: limit results to transactions done by cards with this card holder first name,
  14. cardHolderLastName: limit results to transactions done by cards with this card holder last name,
  15. transactionIds: only fetch transactions matching these transactionIds,
  16. authOny: only fetch authOnly transactions,
  17. unsettledOnly: only fetch unsettled transactions. note: this will limit result to creditDebitOnly,
  18. creditDebitOnly: only fetch credit-debit transactions. note: if one of the card filters or unsettledOnly filter above are enabled, it automatically limits result to credit-debit only,

Arguments

businessId path
string (required)
If-Modified-Since header
string (optional)
startAt query
string (optional)
startOffset query
integer (optional)
endAt query
string (optional)
limit query
integer (optional)
storeId query
string (optional)
deviceId query
string (optional)
searchKey query
string (optional)
cardNumberFirst6 query
string (optional)
cardNumberLast4 query
string (optional)
cardExpirationMonth query
integer (optional)
cardExpirationYear query
integer (optional)
cardHolderFirstName query
string (optional)
cardHolderLastName query
string (optional)
action query
string (optional)
status query
string (optional)
transactionIds query
array (optional)
authOnly query
boolean (optional)
unsettledOnly query
boolean (optional)
creditDebitOnly query
boolean (optional)

Response

Returns a TransactionList.


Definition

PATCH /businesses/{businessId}/transactions/{transactionId}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Update transaction

Update a transaction. This only works on an authorization transaction. This takes a JsonPatch object as request. We currently support replace on all the fields in the /amounts object and an add on /receiptEmailAddress and /signature.

Arguments

Poynt-Request-Id header
string (required)
businessId path
string (required)
transactionId path
string (required)
patch body
JsonPatch (optional)

Response

Returns a Transaction.


Definition

GET /businesses/{businessId}/transactions/{transactionId}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get a transaction

Get a transaction (along with HATEOS links to all immediately related transactions).

Arguments

If-Modified-Since header
string (optional)
businessId path
string (required)
transactionId path
string (required)

Response

Returns a Transaction.


Definition

PUT /businesses/{businessId}/transactions/{transactionId}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Record transaction

Record a transaction that has already happened. A full transaction object must be populated as this operation will simply record what is passed to it. If the references field in the body includes a POYNT_ORDER, this transaction will be attached to it.

Arguments

Poynt-Request-Id header
string (required)
businessId path
string (required)
transactionId path
string (required)
transaction body
Transaction (optional)

Response

Returns a Transaction.


Customers

Operations for customers of a business


Definition

POST /businesses/{businessId}/customers

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Create a customer

Create a customer of a business.

Arguments

businessId path
string (required)
customer body
Customer (optional)

Response

Returns a Customer.


Definition

GET /businesses/{businessId}/customers

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Search customers

Get all customers of a business by various criterias.

Arguments

businessId path
string (required)
If-Modified-Since header
string (optional)
startAt query
string (optional)
startOffset query
integer (optional)
endAt query
string (optional)
limit query
integer (optional)
cardNumberFirst6 query
string (optional)
cardNumberLast4 query
string (optional)
cardExpirationMonth query
integer (optional)
cardExpirationYear query
integer (optional)
cardHolderFirstName query
string (optional)
cardHolderLastName query
string (optional)

Response

Returns a CustomerList.


Definition

POST /businesses/{businessId}/customers/lookup

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Lookup by card

Find a customer by his card.

Arguments

businessId path
string (required)
card body
Card (optional)

Response

Returns a array.


Definition

GET /businesses/{businessId}/customers/{customerId}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get By Id

Get customer by id.

Arguments

If-Modified-Since header
string (optional)
businessId path
string (required)
customerId path
integer (required)

Response

Returns a Customer.


Merchants


Businesses

Business resource represents the merchant business. The Poynt system assumes the following business hierarchy. There is the parent business at the root. Each business could have 0 or more stores. Each store could have 0 or more terminals. This resource provides operations to create, update and view this entire hierarchy.


Definition

GET /businesses

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get by device Id

Get a business by a device id.

Arguments

storeDeviceId query
string (required)

Response

Returns a Business.


Definition

GET /businesses/{businessId}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get by businessId

Get a business by id.

Arguments

businessId path
string (required)
includeField query
Set (optional)

Response

Returns a Business.


Business Users

Operations for owners and employees of a business


Definition

GET /businesses/{businessId}/businessUsers

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get All Users

Get all users at a business.

Arguments

businessId path
string (required)

Response

Returns a array.


Definition

GET /businesses/{businessId}/businessUsers/{businessUserId}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get User

Get a user at a business.

Arguments

businessId path
string (required)
businessUserId path
integer (required)

Response

Returns a BusinessUser.



Products

Products are what a merchant sell at their business. Products have a name, shortCode, sku, and price. sku should be unique for tracking inventory purpose. shortCode should be unique and represents an easily remembered identifier for the business user.


Definition

POST /businesses/{businessId}/products

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Batch Create

Create multiple product definitions for a business by uploading a csv file.

Arguments

businessId path
string (required)
Poynt-Request-Id header
string (required)
productUpload form
File (required)

Definition

GET /businesses/{businessId}/products

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get List

Get all product since time. Result is paginated

Arguments

If-Modified-Since header
string (optional)
startAt query
string (optional)
startOffset query
integer (optional)
endAt query
string (optional)
limit query
integer (optional)
businessId path
string (required)

Response

Returns a ProductList.


Definition

POST /businesses/{businessId}/products

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Create

Create a product definition for a business.

Arguments

businessId path
string (required)
product body
Product (optional)

Response

Returns a Product.


Definition

GET /businesses/{businessId}/products/lookup

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get Multiple Id

Get multiple products by ids.

Arguments

businessId path
string (required)
ids query
string (required)

Response

Returns a ProductList.


Definition

GET /businesses/{businessId}/products/summary

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get Summary

Get all product summary. Result is paginated

Arguments

If-Modified-Since header
string (optional)
startAt query
string (optional)
startOffset query
integer (optional)
endAt query
string (optional)
limit query
integer (optional)
businessId path
string (required)

Response

Returns a ProductSummaryList.


Definition

GET /businesses/{businessId}/products/upload/{productUploadId}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get ProductUpload By Id

Get the ProductUpload status by id

Arguments

businessId path
string (required)
productUploadId path
string (required)

Response

Returns a ProductUpload.


Definition

DELETE /businesses/{businessId}/products/{productId}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Deactivate

Deactivate a product. Deactivated product will be removed from all catalog references.

Arguments

businessId path
string (required)
productId path
string (required)

Definition

GET /businesses/{businessId}/products/{productId}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get By Id

Get a business product by id.

Arguments

businessId path
string (required)
If-Modified-Since header
string (optional)
productId path
string (required)

Response

Returns a Product.


Definition

PATCH /businesses/{businessId}/products/{productId}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Update By Id

Update a product by id.

Arguments

businessId path
string (required)
productId path
string (required)
patch body
JsonPatch (optional)

Response

Returns a Product.


Definition

DELETE /businesses/{businessId}/products/{productId}/relations

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Remove relation

Remove one or more product relationship.

Arguments

businessId path
string (required)
productId path
string (required)
relatedProductIds body
List (optional)

Definition

GET /businesses/{businessId}/products/{productId}/relations

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get relations

Get all relations of a product.

Arguments

businessId path
string (required)
productId path
string (required)

Response

Returns a ProductRelationList.


Definition

POST /businesses/{businessId}/products/{productId}/relations

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Add relation

Create one or more product relationships.

Arguments

businessId path
string (required)
productId path
string (required)
relations body
array (optional)

Response

Returns a array.


Definition

PUT /businesses/{businessId}/products/{productId}/variants

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Upsert variant

Upsert a variant of a product, retaining its inventory, if any.

Arguments

businessId path
string (required)
productId path
string (required)
variant body
Variant (optional)

Response

Returns a Variant.


Definition

GET /businesses/{businessId}/products/{productId}/variants

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get all variants

Get all variants of this product.

Arguments

businessId path
string (required)
productId path
string (required)

Response

Returns a array.


Definition

DELETE /businesses/{businessId}/products/{productId}/variants/{sku}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Delete variant

Delete a variant of a product

Arguments

businessId path
string (required)
productId path
string (required)
sku path
string (required)

Catalogs

A catalog is a complete list of products for sale by the merchant. Catalog can contain products and/or categories of products organized in a hierarchy. Catalogs, once defined, can be assigned to a store or individual Poynt Terminal.


Definition

POST /businesses/{businessId}/catalogs

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Create

Create a catalog for a business.

Arguments

catalog body
Catalog (optional)
businessId path
string (required)

Response

Returns a Catalog.


Definition

GET /businesses/{businessId}/catalogs

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get List

Get all catalog since time. Result is paginated

Arguments

If-Modified-Since header
string (optional)
startAt query
string (optional)
startOffset query
integer (optional)
endAt query
string (optional)
limit query
integer (optional)
businessId path
string (required)

Response

Returns a CatalogList.


Definition

POST /businesses/{businessId}/catalogs/full

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Create Full

Create a catalog with all its embedded products.

Arguments

catalog body
CatalogWithProduct (optional)
businessId path
string (required)

Response

Returns a CatalogWithProduct.


Definition

GET /businesses/{businessId}/catalogs/search

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Search Catalog

Search for a catalog by name or device id.

Arguments

businessId path
string (required)
name query
string (optional)
deviceId query
string (optional)

Response

Returns a Catalog.


Definition

PATCH /businesses/{businessId}/catalogs/{catalogId}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Update catalog

Update a catalog.

Arguments

businessId path
string (required)
catalogId path
string (required)
patch body
JsonPatch (optional)

Response

Returns a Catalog.


Definition

DELETE /businesses/{businessId}/catalogs/{catalogId}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Delete catalog

Delete a catalog.

Arguments

businessId path
string (required)
catalogId path
string (required)

Definition

GET /businesses/{businessId}/catalogs/{catalogId}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get By Id

Get a catalog by id.

Arguments

If-Modified-Since header
string (optional)
businessId path
string (required)
catalogId path
string (required)

Response

Returns a Catalog.


Definition

POST /businesses/{businessId}/catalogs/{catalogId}/categories

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Create category

Create a category for a catalog.

Arguments

businessId path
string (required)
catalogId path
string (required)
category body
Category (optional)

Response

Returns a Category.


Definition

GET /businesses/{businessId}/catalogs/{catalogId}/categories/lookup

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get Multiple Id

Get multiple category by ids.

Arguments

businessId path
string (required)
catalogId path
string (required)
ids query
string (required)

Response

Returns a CategoryList.


Definition

GET /businesses/{businessId}/catalogs/{catalogId}/categories/{categoryId}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get category by id

Getall a category by id.

Arguments

businessId path
string (required)
catalogId path
string (required)
categoryId path
string (required)

Response

Returns a Category.


Definition

DELETE /businesses/{businessId}/catalogs/{catalogId}/categories/{categoryId}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Delete category

Delete a category.

Arguments

businessId path
string (required)
catalogId path
string (required)
categoryId path
string (required)

Definition

PATCH /businesses/{businessId}/catalogs/{catalogId}/categories/{categoryId}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Update category

Update a category.

Arguments

businessId path
string (required)
catalogId path
string (required)
categoryId path
string (required)
patch body
JsonPatch (optional)

Response

Returns a Category.


Definition

GET /businesses/{businessId}/catalogs/{catalogId}/full

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get Full Catalog By Id

Get a catalog by id with all product details info embedded in the Catalog.

Arguments

If-Modified-Since header
string (optional)
businessId path
string (required)
catalogId path
string (required)

Response

Returns a CatalogWithProduct.


Taxes

Merchants must collect appropriate taxes based on the location their business and the products they sell. A tax, once defined, can be associated at the catalog, category, or individual product level.


Definition

GET /businesses/{businessId}/taxes

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get List

Get all tax rate for this business.

Arguments

If-Modified-Since header
string (optional)
startAt query
string (optional)
startOffset query
integer (optional)
endAt query
string (optional)
limit query
integer (optional)
businessId path
string (required)

Response

Returns a TaxList.


Definition

POST /businesses/{businessId}/taxes

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Create

Create a tax rate definition for a business.

Arguments

businessId path
string (required)
tax body
Tax (optional)

Response

Returns a Tax.


Definition

DELETE /businesses/{businessId}/taxes/{taxId}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Delete tax

Delete a tax.

Arguments

businessId path
string (required)
taxId path
string (required)

Definition

GET /businesses/{businessId}/taxes/{taxId}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get

Get a tax rate detail.

Arguments

If-Modified-Since header
string (optional)
businessId path
string (required)
taxId path
string (required)

Response

Returns a Tax.


Definition

PATCH /businesses/{businessId}/taxes/{taxId}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Update

Update tax details.

Arguments

businessId path
string (required)
taxId path
string (required)
patch body
JsonPatch (optional)

Response

Returns a Tax.


Notifications

Cloud Messages can be sent from the cloud applications running on the Poynt Smart Terminal.

Webhooks allow developers to register their application to receive callback events from Poynt or replay missed events.

To register for an event type, the developer can create a hook specifying the business and event type they would like to receive callbacks on. This can be done programmatically or via our developer portal UI.

When an event matching the criterias defined in a hook happens, a delivery is made to the developer application endpoint. Webhook deliveries can be redelivered or lookup based on time range as needed.


Cloudmessages

A message sent from the cloud through the Poynt Cloud Messaging to applications running on the Poynt Smart Terminal.


Definition

POST /cloudMessages

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Send cloud message

Send a message from the cloud to your application running at a Poynt terminal.

Arguments

message body
CloudMessage (optional)

Hooks

A hook represent an application's registration to be notified should a particular resource event occurs.


Definition

GET /hooks

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get List

Get all webhooks since time. Result is paginated

Arguments

If-Modified-Since header
string (optional)
startAt query
string (optional)
startOffset query
integer (optional)
endAt query
string (optional)
limit query
integer (optional)
businessId query
string (required)

Response

Returns a HookList.


Definition

POST /hooks

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Create

Create a web hook. Client application MUST have already have been authorized by the business to access the resource of the events in this hook. The following webhooks event are available:

Arguments

hook body
Hook (optional)

Response

Returns a Hook.


Definition

DELETE /hooks/{hookId}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Delete hook

Delete a hook.

Arguments

hookId path
string (required)

Definition

GET /hooks/{hookId}

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get By Id

Get a hook by id.

Arguments

If-Modified-Since header
string (optional)
hookId path
string (required)

Response

Returns a Hook.


Delivery

When a event occurs which matches the registered Hooks of an application, a delivery is made to the registered delivery url. Delivery are attempted up to 10 times with exponential backoff should there be a failure reaching the delivery url.


Definition

GET /businesses/{businessId}/deliveries

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Get List

Get all webhook delivery since time. Result is paginated

Arguments

If-Modified-Since header
string (optional)
startAt query
string (optional)
startOffset query
integer (optional)
endAt query
string (optional)
limit query
integer (optional)
businessId path
string (required)

Response

Returns a DeliveryList.


Definition

POST /businesses/{businessId}/deliveries/redeliver

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Redeliver By Time

Redeliver all webhook within a time window.

Arguments

businessId path
string (required)
startTime query
string (required)
endTime query
string (required)

Definition

POST /businesses/{businessId}/deliveries/{deliveryId}/redeliver

Sample Request

TODO: Add request

Sample Response

TODO: Add response

Redeliver Event

Redeliver a webhook delivery.

Arguments

businessId path
string (required)
deliveryId path
string (required)

Response

Returns a Delivery.


AVSResult

Attributes

addressResult
string, enum['MATCH', 'NO_MATCH', 'PARTIAL_MATCH', 'NOT_PROVIDED', 'ISSUER_NOT_CERTIFIED', 'NO_RESPONSE_FROM_CARD_ASSOCIATION', 'UNKNOWN_RESPONSE_FROM_CARD_ASSOCIATION', 'NOT_VERIFIED', 'BAD_FORMAT', 'ERROR', 'UNSUPPORTED_BY_ISSUER', 'UNAVAILABLE']
stateResult
string, enum['MATCH', 'NO_MATCH', 'PARTIAL_MATCH', 'NOT_PROVIDED', 'ISSUER_NOT_CERTIFIED', 'NO_RESPONSE_FROM_CARD_ASSOCIATION', 'UNKNOWN_RESPONSE_FROM_CARD_ASSOCIATION', 'NOT_VERIFIED', 'BAD_FORMAT', 'ERROR', 'UNSUPPORTED_BY_ISSUER', 'UNAVAILABLE']
countryResult
string, enum['MATCH', 'NO_MATCH', 'PARTIAL_MATCH', 'NOT_PROVIDED', 'ISSUER_NOT_CERTIFIED', 'NO_RESPONSE_FROM_CARD_ASSOCIATION', 'UNKNOWN_RESPONSE_FROM_CARD_ASSOCIATION', 'NOT_VERIFIED', 'BAD_FORMAT', 'ERROR', 'UNSUPPORTED_BY_ISSUER', 'UNAVAILABLE']
phoneResult
string, enum['MATCH', 'NO_MATCH', 'PARTIAL_MATCH', 'NOT_PROVIDED', 'ISSUER_NOT_CERTIFIED', 'NO_RESPONSE_FROM_CARD_ASSOCIATION', 'UNKNOWN_RESPONSE_FROM_CARD_ASSOCIATION', 'NOT_VERIFIED', 'BAD_FORMAT', 'ERROR', 'UNSUPPORTED_BY_ISSUER', 'UNAVAILABLE']
cardHolderNameResult
string, enum['MATCH', 'NO_MATCH', 'PARTIAL_MATCH', 'NOT_PROVIDED', 'ISSUER_NOT_CERTIFIED', 'NO_RESPONSE_FROM_CARD_ASSOCIATION', 'UNKNOWN_RESPONSE_FROM_CARD_ASSOCIATION', 'NOT_VERIFIED', 'BAD_FORMAT', 'ERROR', 'UNSUPPORTED_BY_ISSUER', 'UNAVAILABLE']
cityResult
string, enum['MATCH', 'NO_MATCH', 'PARTIAL_MATCH', 'NOT_PROVIDED', 'ISSUER_NOT_CERTIFIED', 'NO_RESPONSE_FROM_CARD_ASSOCIATION', 'UNKNOWN_RESPONSE_FROM_CARD_ASSOCIATION', 'NOT_VERIFIED', 'BAD_FORMAT', 'ERROR', 'UNSUPPORTED_BY_ISSUER', 'UNAVAILABLE']
actualResult
string
postalCodeResult
string, enum['MATCH', 'NO_MATCH', 'PARTIAL_MATCH', 'NOT_PROVIDED', 'ISSUER_NOT_CERTIFIED', 'NO_RESPONSE_FROM_CARD_ASSOCIATION', 'UNKNOWN_RESPONSE_FROM_CARD_ASSOCIATION', 'NOT_VERIFIED', 'BAD_FORMAT', 'ERROR', 'UNSUPPORTED_BY_ISSUER', 'UNAVAILABLE']

ActiveTime

Attributes

repeatType
string, enum['DAILY', 'WEEKLY', 'MONTHLY']
every
array [long]
endAt
string
The time in ISO-8601 format. E.g. 2014-09-11T23:14:44Z.
startAt
string
The time in ISO-8601 format. E.g. 2014-09-11T23:14:44Z.
startHour
integer
endHour
integer

Address

Attributes

postalCodeExtension
string
status
string, enum['ADDED']
territoryType
string, enum['STATE', 'PROVINCE', 'OTHER']
TerritoryType enum and territory go hand in hand. This enum specifies what kind of territory is in the territory field. E.g. in the US, this will typically be STATE.
countryCode
string
line1
string
line2
string
updatedAt
string
The time (in ISO-8601 format) at which the address was updated. E.g. 2014-09-11T23:14:44Z.
createdAt
string
The time (in ISO-8601 format) at which the address was created. E.g. 2014-09-11T23:14:44Z.
city
string
territory
string
postalCode
string
id
integer
type
string, enum['HOME', 'WORK', 'BUSINESS', 'OTHER']

AvailableDiscount

Attributes

scope
string, enum['ITEM', 'ORDER']
code
string
fixed
integer
percentage
float
when
ActiveTime
id
string
type
string, enum['FIXED', 'PERCENTAGE']

Business

This is the base object for the businesses resource. Businesses resource represents a merchant business.

Attributes

businessUrl
string
The url of the business' website.
industryType
string
The industry type that this business belongs to.
logoUrl
string
The business' main logo url.
description
string
[Required] A short description of the business.
status
string, enum['ADDED', 'ACTIVATED', 'LOCKED', 'CLOSED']
It is set to ADDED as soon as the business is added into the system. Moved to ACTIVATED once the first terminal is activated. It may move to LOCKED if for whatever reason, operations need to be stopped. It is moved to CLOSED if the business is closed for good.
activeSince
string
This is a response only field. It is set internally and returned in response. The time (in ISO-8601 format) at which the first terminal at the business was activated. E.g. 2014-09-11T23:14:44Z.
sic
string
[Required] The standard industry code of the business.
processorData
object
timezone
string
[Required] The timezone that the headquarters belong to.
processor
string, enum['CHASE_PAYMENTECH', 'REDE', 'EVO', 'FIRST_DATA', 'GLOBAL_PAYMENTS', 'HEARTLAND_PAYMENT_SYSTEM', 'ELAVON', 'MERCURY', 'MONERIS', 'PAYPAL', 'STRIPE', 'TSYS', 'VANTIV', 'WORLDPAY', 'EPX', 'BRIDGEPAY', 'CREDITCALL', 'NA_BANCARD', 'MOCK']
acquirer
string, enum['CHASE_PAYMENTECH', 'REDE', 'EVO', 'FIRST_DATA', 'GLOBAL_PAYMENTS', 'HEARTLAND_PAYMENT_SYSTEM', 'ELAVON', 'MERCURY', 'MONERIS', 'PAYPAL', 'STRIPE', 'TSYS', 'VANTIV', 'WORLDPAY', 'EPX', 'BRIDGEPAY', 'CREDITCALL', 'NA_BANCARD', 'MOCK'] [Required] The acquirer that this business belongs to.
stores
array [Store]
The list of stores within this business.
mcc
string
[Required] The merchant category code of the business.
updatedAt
string
ISO 8601 format YYYY-MM-DDThh:mm:ssZ
createdAt
string
ISO 8601 format YYYY-MM-DDThh:mm:ssZ
legalName
string
[Required] The legal name of the business.
doingBusinessAs
string
[Required] The name the business likes to be known as.
emailAddress
string
The main business email address.
phone
Phone
[Required] The main business phone.
externalMerchantId
string
This is the unique identifier assigned by the acquirer to the business. It is a business level MID.
address
Address
[Required] The main business address.
id
string
The id of the business. This id could be generated by the client and passed in. If not passed in, it is generated internally during create business.
type
string, enum['MERCHANT', 'TEST_MERCHANT', 'DEVELOPER', 'DISTRIBUTOR', 'ORGANIZATION'] [Required] The type of business.
attributes
object
A name/value pair list that could be persisted and later retreived.

BusinessUser

Attributes

employmentDetails
EmploymentDetails
credentials
array [UserCredential]
status
string, enum['EMPLOYED', 'TERMINATED']
email
string
cards
array [Card]
emailSignupCode
string
middleInitial
string
middleName
string
userId
integer
firstName
string
lastName
string
nickName
string
startDate
integer
endDate
integer
businessId
string
UUID version 1, 2, 3, or 4. All server generated values are version 4.

Card

Object to carry credit/debit card information.

Attributes

sequenceNumber
string
Sequence number to distinguish between 2 cards with same PAN.
status
string, enum['ACTIVE', 'REMOVED']
Status of the card.
numberMasked
string
This is a response field. PAN with everything except first6 and last4 masked.
track3data
string
Track3 for future use. Carries track from custom funding sources.
numberHashed
string
encryptedExpirationDate
string
If encryption is true, a single encrypted expiration date (containing year, month and possibly date) is provided here.
expirationDate
integer
The date from expiration. Date is typically only present in EMV cards.
expirationYear
integer
The year from expiration.
serviceCode
string
track2data
string
Required for swiped transactions. Track2 read from the card contains PAN, expiration, etc.
expirationMonth
integer
The month from expiration.
keySerialNumber
string
KeySerialNumber of the Poynt P2PE DUKPT key. If encrypted is true, only one of key and keySerialNumber can be populated (not both).
track1data
string
In some use-cases (like airlines) Track1 is required. Track1 contains some extra information over Track2 (like cardholder's name).
numberLast4
string
This is a response field. The last4 numbers of the PAN.
cardHolderFullName
string
Card holder's full name usually picked from track1.
cardHolderFirstName
string
Card holder's first name usually picked from track1.
cardHolderLastName
string
Card holder's last name usually picked from track1.
numberFirst6
string
This is a response field. The first6 numbers of the PAN.
key
array [CardKeyData]
List of keys and their versions being used. If encrypted is true, only one of key and keySerialNumber can be populated (not both).
id
integer
The id of the card created.
type
string, enum['AMERICAN_EXPRESS', 'MAESTRO', 'DISCOVER', 'DINERS_CLUB', 'JCB', 'MASTERCARD', 'DANKORT', 'OTHER', 'VISA', 'UNIONPAY', 'PAYPAL']
The network card belongs to: DISCOVER, VISA, MASTERCARD, AMEX, etc.
number
string
Required for keyed-in transactions. The card account number (PAN). Not required if Track1 or 2 are available.

CardKeyData

Attributes

version
string
Version of the key.
id
string, enum['WCK', 'WAEK', 'WMACK']
The key identifier.

Catalog

This is a swagger model description.

Attributes

priceBookId
string
products
array [CatalogItem]
availableDiscounts
array [AvailableDiscount]
taxes
array [Tax]
businessId
string
UUID version 1, 2, 3, or 4. All server generated values are version 4.
updatedAt
string
The time (in ISO-8601 format) at which the Catalog was updated. E.g. 2014-09-11T23:14:44Z.
createdAt
string
The time (in ISO-8601 format) at which the Catalog was created. E.g. 2014-09-11T23:14:44Z.
categories
array [Category]
name
string
id
string

CatalogItem

An item inside a catalog. Can be a product or a category.

Attributes

availableDiscounts
array [AvailableDiscount]
displayOrder
integer
color
string
id
string

CatalogItemWithProduct

An item inside a catalog. Can be a product or a category.

Attributes

product
Product
availableDiscounts
array [AvailableDiscount]
displayOrder
integer
color
string

CatalogList

Attributes

catalogs
array [Catalog]
links
array [Link]

CatalogWithProduct

This is a swagger model description.

Attributes

products
array [CatalogItemWithProduct]
availableDiscounts
array [AvailableDiscount]
taxes
array [Tax]
businessId
string
UUID version 1, 2, 3, or 4. All server generated values are version 4.
updatedAt
string
The time (in ISO-8601 format) at which the Catalog was updated. E.g. 2014-09-11T23:14:44Z.
createdAt
string
The time (in ISO-8601 format) at which the Catalog was created. E.g. 2014-09-11T23:14:44Z.
categories
array [CategoryWithProduct]
name
string
id
string

Category

A category is a grouping of products with optional display info.

Attributes

products
array [CatalogItem]
availableDiscounts
array [AvailableDiscount]
taxes
array [Tax]
parentCategoryId
string
shortCode
string
displayOrder
integer
color
string
name
string
id
string

CategoryList

Attributes

links
array [Link]
categories
array [Category]

CategoryWithProduct

A category is a grouping of products with optional display info.

Attributes

products
array [CatalogItemWithProduct]
availableDiscounts
array [AvailableDiscount]
taxes
array [Tax]
parentCategoryId
string
shortCode
string
displayOrder
integer
color
string
name
string
id
string

ClientContext

Colors the operation with some important context about the client.

Attributes

storeAddressTerritory
string
storeAddressCity
string
storeTimezone
string
source
string, enum['INSTORE', 'WEB', 'MOBILE', 'CALLIN', 'CATALOG']
This is required if ClientContext is inside Order. The source where the transaction was initiated.
transactionInstruction
string, enum['NONE', 'EXTERNALLY_PROCESSED']
Any instructions about the transaction. EXTERNALLY_PROCESSED implies that this order was paid for outside of the Poynt system.
businessType
string, enum['MERCHANT', 'TEST_MERCHANT', 'DEVELOPER', 'DISTRIBUTOR', 'ORGANIZATION']
The type of the client business.
mid
string
The acquirer assigned merchant ID (aka MID) for this store.
tid
string
The acquirer assigned terminal ID (aka TID) for the terminal.
businessId
string
This is optional as it can always be picked from the JWT token used for authentication.
storeId
string
This is optional as it can always be picked from the JWT token used for authentication.
storeDeviceId
string
This is optional as it can always be picked from the JWT token used for authentication.
transmissionAtLocal
string
This is required if ClientContext is inside Transaction. The time at the terminal (in ISO-8601 format) at the time of the transaction in the terminal's timezone. This comes specially handy in case of offline transactions where the transaction might have happened hours before this data is sent to the server. E.g. 2014-09-11T23:14:44Z.
mcc
string
The business already has an MCC (merchant category code) set during onboarding. That will be used by default. But we can override it per transaction using this field.
employeeUserId
integer
This is optional as it can always be picked from the JWT token used for authentication.
sourceApp
string

CloudMessage

Attributes

collapseKey
string
sender
string
data
string
ttl
integer
serialNum
string
recipient
ComponentName
businessId
string
UUID version 1, 2, 3, or 4. All server generated values are version 4.
storeId
string
UUID version 1, 2, 3, or 4. All server generated values are version 4.
deviceId
string
id
string

ComponentName

Attributes

packageName
string
className
string

CurrencyAmount

Attributes

amount
integer
currency
string

Customer

Attributes

devices
array [Device]
addresses
array [Entry]
This represents customer's addresses. It is modeled as a map, where the AddressType enum is the key and the Address object is the value.
insights
CustomerInsights
loyaltyCustomers
array [LoyaltyCustomer]
nickName
string
businessPreferences
CustomerBusinessPreferences
cards
array [Card]
middleName
string
middleInitial
string
businessId
string
UUID version 1, 2, 3, or 4. All server generated values are version 4.
phones
array [Entry]
This represents customer's phones. It is modeled as a map, where the PhoneType enum is the key and the Phone object is the value.
emails
array [Entry]
This represents customer's emails. It is modeled as a map, where the EmailType enum is the key and the Email object is the value.
updatedAt
string
The time (in ISO-8601 format) at which the Customer was updated. E.g. 2014-09-11T23:14:44Z.
createdAt
string
The time (in ISO-8601 format) at which the Customer was created. E.g. 2014-09-11T23:14:44Z.
firstName
string
lastName
string
id
integer
attributes
object

CustomerBusinessPreferences

Attributes

preferredCardId
integer

CustomerInsights

Attributes

since
string
The time (in ISO-8601 format) since when this customer has been on file. E.g. 2014-09-11T23:14:44Z.
poyntLoyalty
PoyntLoyalty
scores
array [CustomerScore]
topItems
array [CustomerTopItem]
totalOrders
integer
lifetimeSpend
array [CurrencyAmount]

CustomerList

Attributes

count
integer
customers
array [Customer]
links
array [Link]

CustomerScore

Attributes

score
double
type
string, enum['LOYALTY', 'VALUE', 'OVERALL']

CustomerTopItem

Attributes

variationId
integer
lastPurchasedAt
integer
count
double
countUnit
string, enum['EACH', 'HOURS', 'DAYS', 'SECONDS', 'CRATE_OF_12', 'SIX_PACH', 'GALLON', 'LITRE', 'INCH', 'FOOT', 'MILLIMETER', 'CENTIMETER', 'METER', 'SQUARE_METER', 'CUBIC_METER', 'GRAM', 'KILOGRAM', 'POUND', 'ANNUAL', 'DEGREE_CELCIUS', 'DEGREE_FARENHEIT']
productId
integer
firstPurchasedAt
integer
name
string

Delivery

Attributes

attempt
integer
status
string, enum['SCHEDULED', 'RESCHEDULED', 'ERRORED_RETRYING', 'DELIVERED', 'ERRORED']
eventType
string
resourceId
string
applicationId
string
deliveryUrl
string
secret
string
links
array [Link]
businessId
string
UUID version 1, 2, 3, or 4. All server generated values are version 4.
storeId
string
UUID version 1, 2, 3, or 4. All server generated values are version 4.
deviceId
string
updatedAt
string
The time (in ISO-8601 format) at which the Delivery was updated. E.g. 2014-09-11T23:14:44Z.
createdAt
string
The time (in ISO-8601 format) at which the Delivery was created. E.g. 2014-09-11T23:14:44Z.
hookId
string
resource
string
id
string

DeliveryList

Attributes

deliveries
array [Delivery]
links
array [Link]

Device

Attributes

macAddresses
array [DeviceMacAddress]
deviceType
string, enum['MOBILE', 'UNKNOWN']
id
integer

DeviceMacAddress

Attributes

macAddress
string
networkInterface
string, enum['BLUETOOTH', 'WIFI']
id
integer

Discount

Details about the item being purchased.

Attributes

amount
integer
[Required] Amount of discount.
customName
string
[Required] Name of the discount.
percentage
float
Percentage of discount.
id
string
If the discount was applied as a result of a pre-set discount (at the catalog or product level), pass the id of that discount here.
provider
string
processor
string
processorResponse
ProcessorResponse

EMVData

All EMV specific data. During an EMV transaction, objects such as Card, TransactionAmounts, ClientContext, etc will be filled. But everything EMV specific ends up here.

Attributes

emvTags
object
Tags that are not modeled in explicit fields can be passed here. These will be passed untouched to the acquirer.

EmploymentDetails

Attributes

role
string, enum['OWNER', 'MANAGER', 'EMPLOYEE']
endAt
integer
startAt
integer

FundingSource

The funding source used for funding transactions.

Attributes

debitEBTReEntryDetails
DebitEBTReEntry
card
Card
If type is CREDIT_DEBIT, this is required. This carries details about the card.
accountType
string, enum['EBT']
The type of account this funding source taps into.
ebtDetails
EBTDetails
entryDetails
FundingSourceEntryDetails
If type is CREDIT_DEBIT, this is required. This carries details about how the funding source data was collected on the terminal.
emvData
EMVData
If type is CREDIT_DEBIT and its an EMV transaction, this is required. This carries any EMV tags in addition to card data.
verificationData
VerificationData
If type is CREDIT_DEBIT, this will carry any data needed to verify the card.
customFundingSource
CustomFundingSource
If type is CUSTOM_FUNDING_SOURCE, this is required. This carries details about the custom funding source.
type
string, enum['CHEQUE', 'CUSTOM_FUNDING_SOURCE', 'CREDIT_DEBIT', 'CASH'] [Required] The type of funding source (CASH, CREDIT_DEBIT).

FundingSourceEntryDetails

Attributes

customerPresenceStatus
string, enum['PRESENT', 'MOTO', 'ECOMMERCE', 'ARU']
entryMode
string, enum['KEYED', 'TRACK_DATA_FROM_MAGSTRIPE', 'CONTACTLESS_MAGSTRIPE', 'INTEGRATED_CIRCUIT_CARD', 'CONTACTLESS_INTEGRATED_CIRCUIT_CARD']

Hook

The object representing the webhook.

Attributes

applicationId
string
ApplicationId e.g. urn:aid:c5aaffaf-ee8c-41bc-82fa-88882222ddde.
eventTypes
array [string]
List of events to subscribe to.
deliveryUrl
string
The Url at which to deliver the webhook event.
secret
string
Used for signing the webhook event.
businessId
string
The business whose events to subscribe to.
updatedAt
string
The time (in ISO-8601 format) at which the Hook was updated. E.g. 2014-09-11T23:14:44Z.
createdAt
string
The time (in ISO-8601 format) at which the Hook was created. E.g. 2014-09-11T23:14:44Z.
id
string

HookList

Attributes

hooks
array [Hook]
links
array [Link]

Inventory

Attributes

stockCount
float
The actual physical count of the product the business has.
availableCount
float
The subset of the stockCount which is available for sale i.e. If an item is already sold, but not shipped, it is not available.
reOrderLevel
float
When a re-order is triggered, the stockCount should be brought back up to this value.
reOrderPoint
float
When the stockCount reach this value, inventory should be reordered.
createdAt
string
The time (in ISO-8601 format) at which the Inventory was created. E.g. 2014-09-11T23:14:44Z.
storeId
string
UUID version 1, 2, 3, or 4. All server generated values are version 4.
updatedAt
string
The time (in ISO-8601 format) at which the Inventory was updated. E.g. 2014-09-11T23:14:44Z.

JsonPatch

Attributes


Attributes

rel
string
href
string
method
string

Order

This is the base object for the orders resource. Orders resource represents a purchase order for items or services. This object captures all items, amounts and transactions related to an order. One important point to note upfront is that all the order-level amount fields could be positive or negative. That is because unlike an item which is always either purchased or returned, an order could be a mixed bag of purchased or returned items. So the amounts could be positive or negative.

Attributes

orderNumber
string
Stores often use a human readable order number to hand out to customers. Such numbers could be passed here.
statuses
OrderStatuses
Represents various order related statuses (including the order's own status). This is optional input. If not provided while creating an order, the order will be in CREATED state.
links
array [Link]
This is a response only field. It will include HATEOS links to any related orders.
transactions
array [Transaction]
A list of transactions being performed to pay for this order.
items
array [OrderItem]
A list of items (or services) being purchased.
discounts
array [Discount]
Order level discounts. An order level discount will be negative if it is being given to the customer and positive if it is being returned. Note that discounts can also be applied at a per item level. Those are present inside the OrderItem object.
fees
array [Fee]
parentId
string
When creating a return order, the original order's ID can be specified here.
amounts
OrderAmounts
[Required] A summary of all amounts represented in the items, discounts and transactions objects.
customerUserId
integer
This field can be provided by the caller. If provided by the caller, Poynt ensures that it is a valid customer. If not provided by the caller, Poynt tries to determine the customer itself. Poynt assigns a userId to every customer using a card (credit or debit) for a payment. The customer's userId will be returned in this field. If an order contains multiple transactions, each using a different card, Poynt will leave this field as blank.
stayType
string, enum['REGULAR_STAY', 'QUICK_STAY', 'NON_LODGING']
notes
string
Any special notes from the customer or merchant about the order could be recorded here.
updatedAt
string
This is a response only field. The time (in ISO-8601 format) at which the order was updated. E.g. 2014-09-11T23:14:44Z.
createdAt
string
This is a response only field. The time (in ISO-8601 format) at which the order was created. E.g. 2014-09-11T23:14:44Z.
context
ClientContext
[Required] Contains context about the order. Source must be populated. All other fields are optional.
id
string
The id of the order created. If provided in the request, it will be used as the order ID. If not provided, id will be generated internally.

OrderAmounts

Summary of all amounts related to the order.

Attributes

currency
string
[Required] Currency of the order.
authorizedTotals
TransactionAmounts
This is a response field. Sum of all transactions still in authorized state.
voidedTotals
TransactionAmounts
capturedTotals
TransactionAmounts
This is a response field. Sum of all transactions that have been completed.
refundedTotals
TransactionAmounts
This is a response field. Sum of all transactions that have been refunded.
savedTotals
TransactionAmounts
This is a response field. Sum of all transactions that are still in saved state (not processed).
netTotal
integer
This is a response field. Sum of subTotal, discountTotal and taxTotal. Note that its a simple summation as those amounts already have the correct sign.
discountTotal
integer
[Required] Sum of all order and item level discounts. Negative amount for purchases, positive amount for returns.
feeTotal
integer
subTotal
integer
[Required] Sum of all item amounts (excluding item level discounts and taxes). Positive amount for purchases and negative amount for returns.
taxTotal
integer
[Required] Sum of all item level taxes. Positive amount for purchases, negative amount for returns.

OrderItem

Details about the item being purchased. Here are a couple of point that might not be immediately obvious: (a) all discounts and taxes apply to the entire group of items, not just a single unit of item, (b) none of the amount fields inside OrderItem carry +/- sign because the sign is implied in the item status. E.g. discount would be -ive is item's status is ORDERED or FULFILLED and +ive if item's status is RETURNED.

Attributes

clientNotes
string
Any special instructions related to this order item.
fulfillmentInstruction
string, enum['NONE', 'PICKUP_INSTORE', 'SHIP_TO']
Instructions on how this set of items will be fulfilled. Only applicable on items that are in ORDERED state. If the fulfillmentInstruction is SHIP_TO, you can note down the address in the clientNotes field as we don't model delivery address yet.
serviceStartAt
string
ISO 8601 format YYYY-MM-DDThh:mm:ssZ
serviceEndAt
string
ISO 8601 format YYYY-MM-DDThh:mm:ssZ
taxExempted
boolean
quantity
float
[Required] Quantity purchased. Note this could be in decimals, e.g. 2.3 Kgs.
unitPrice
integer
[Required] Price for each unit.
status
string, enum['ORDERED', 'FULFILLED', 'RETURNED'] [Required] Status of the item.
id
integer
Every item gets an ID unique within the order. If not passed from outside, the server simple assigns IDs in ascending order starting from 1.
details
string
Item details.
tax
integer
Total tax amount applied on this group of items (not just 1 unit). If not specified, but the taxes array is present the server will automatically sum up the amounts in taxes array and populate this. If not specified and taxes array is empty, this will default to 0.
fee
integer
discount
integer
Total discount amount applied on this group of items (not just 1 unit). If not specified, but the discounts array is present the server will automatically sum up the amounts in discounts array and populate this. If not specified and discounts array is empty, this will default to 0.
selectedVariants
array [Variant]
fees
array [Fee]
discounts
array [Discount]
A break-down/details of the discount amount. Note that the discounts here in this array are for the entire group of items put together (not just 1 unit).
taxes
array [OrderItemTax]
A break-down/details of the tax amount. Note that the taxes here in this array are for the entire group of items put together (not just 1 unit).
productId
string
Not being used - will be removed.
sku
string
Sku of the item.
createdAt
string
The time (in ISO-8601 format) at which the order item was created. E.g. 2014-09-11T23:14:44Z.
updatedAt
string
The time (in ISO-8601 format) at which the order item was updated. E.g. 2014-09-11T23:14:44Z.
unitOfMeasure
string, enum['EACH', 'HOURS', 'DAYS', 'SECONDS', 'CRATE_OF_12', 'SIX_PACH', 'GALLON', 'LITRE', 'INCH', 'FOOT', 'MILLIMETER', 'CENTIMETER', 'METER', 'SQUARE_METER', 'CUBIC_METER', 'GRAM', 'KILOGRAM', 'POUND', 'ANNUAL', 'DEGREE_CELCIUS', 'DEGREE_FARENHEIT'] [Required] Unit of measure for the quantity.
name
string
[Required] Name of the item.

OrderItemTax

Attributes

amount
integer
type
string
id
string

OrderList

Attributes

orders
array [Order]
count
integer
links
array [Link]

OrderStatuses

Order status and item fulfillment status.

Attributes

status
string, enum['OPENED', 'CANCELLED', 'COMPLETED']
This is an input/output field. An order status is used for tracking which orders are being actively monitored vs which ones are archived. An order marked as COMPLETED or CANCELED is closed an hence is not being actively monitored by the merchant. A merchant focused on OPENED orders.
transactionStatusSummary
string, enum['NONE', 'EXTERNALLY_PROCESSED', 'PENDING', 'COMPLETED', 'REFUNDED', 'CANCELED']
This is a response only field. Show a summary view of all the transactions' statuses put together. NONE implies no transaction was ever processed for this order (note: cash is counted as processed). EXTERNALLY_PROCESSED implies that the the creator of the order instructed that the transactions was processed outside of Poynt. COMPLETED implies that something has been processed, and net funds received >= order's net total. CANCELED implies that something has been processed, but everything is voided at this point. REFUNDED implies that something has been processed, but everything is refunded at this point. PENDING implies that something has been processed, but net funds received < order's net total.
fulfillmentStatus
string, enum['NONE', 'PARTIAL', 'FULFILLED']
This is a response only field. Show a summary view of all the items' fulfillment statuses put together. If none of the items have been fulfilled, this status will be NONE. If all items have been fulfilled, this status will be FULFILLED. If some but not all items have been fulfilled, this will be PARTIAL.

Phone

Attributes

status
string, enum['ADDED', 'CONFIRMED']
areaCode
string
updatedAt
string
ISO 8601 format YYYY-MM-DDThh:mm:ssZ
ituCountryCode
string
localPhoneNumber
string
createdAt
string
ISO 8601 format YYYY-MM-DDThh:mm:ssZ
extensionNumber
string
id
integer
type
string, enum['HOME', 'WORK', 'BUSINESS', 'MOBILE', 'FAX', 'PAGER', 'RECEIPT', 'OTHER']

ProcessorResponse

Processor response fields.

Attributes

cvActualResult
string
statusCode
string
Will be 1 if status is Successful. If status is Failure, it will be whatever statusCode came from the acquirer.
status
string, enum['Successful', 'Failure']
Possible values are Successful or Failure.
remainingBalance
integer
The amount that is left on the prepaid card after an authorization.
retrievalRefNum
string
cardToken
string
emvTags
object
A name/value pair to list down all tags returned by the processor including the ones normalized in some of the other fields in ProcessorResponse. Both name and value are Strings.
providerVerification
ProviderVerification
Object that carries provider verification related fields.
batchId
string
The ID of the settlement batch that this transaction is assigned to.
cvResult
string, enum['MATCH', 'NO_MATCH', 'NOT_PROCESSED', 'NO_CODE_PRESENT', 'SHOULD_HAVE_BEEN_PRESENT', 'ISSUER_NOT_CERTIFIED', 'INVALID', 'NO_RESPONSE', 'NOT_APPLICABLE']
The card verification results.
avsResult
AVSResult
The address verification results.
transactionId
string
The transactionID that came back from the acquirer.
processor
string, enum['CHASE_PAYMENTECH', 'REDE', 'EVO', 'FIRST_DATA', 'GLOBAL_PAYMENTS', 'HEARTLAND_PAYMENT_SYSTEM', 'ELAVON', 'MERCURY', 'MONERIS', 'PAYPAL', 'STRIPE', 'TSYS', 'VANTIV', 'WORLDPAY', 'EPX', 'BRIDGEPAY', 'CREDITCALL', 'NA_BANCARD', 'MOCK']
acquirer
string, enum['CHASE_PAYMENTECH', 'REDE', 'EVO', 'FIRST_DATA', 'GLOBAL_PAYMENTS', 'HEARTLAND_PAYMENT_SYSTEM', 'ELAVON', 'MERCURY', 'MONERIS', 'PAYPAL', 'STRIPE', 'TSYS', 'VANTIV', 'WORLDPAY', 'EPX', 'BRIDGEPAY', 'CREDITCALL', 'NA_BANCARD', 'MOCK']
approvedAmount
integer
The amount that the authorization was approved for. This could be different from the transactionAmount requested.
statusMessage
string
Will be whatever message came back from the acquirer.
approvalCode
string
The approval code that came back from the acquirer (usually its 6 alpha-numeric characters).

Product

Attributes

description
string
status
string, enum['ACTIVE', 'RETIRED']
tags
string
unitOfMeasure
string, enum['EACH', 'HOURS', 'DAYS', 'SECONDS', 'CRATE_OF_12', 'SIX_PACH', 'GALLON', 'LITRE', 'INCH', 'FOOT', 'MILLIMETER', 'CENTIMETER', 'METER', 'SQUARE_METER', 'CUBIC_METER', 'GRAM', 'KILOGRAM', 'POUND', 'ANNUAL', 'DEGREE_CELCIUS', 'DEGREE_FARENHEIT']
taxes
array [Tax]
bundledProducts
array [ProductRelation]
relatedProducts
array [ProductRelation]
addonProducts
array [ProductRelation]
possibleVariations
array [Variation]
inventory
array [Inventory]
templateOverrides
array [string]
ean
string
upc
string
isbn
string
plu
string
asin
string
specification
string
brand
string
releaseDate
string
ISO 8601 format YYYY-MM-DDThh:mm:ssZ
msrp
CurrencyAmount
avgUnitCost
CurrencyAmount
imageUrl
array [string]
selectableVariants
array [Variant]
sku
string
shortCode
string
price
CurrencyAmount
businessId
string
UUID version 1, 2, 3, or 4. All server generated values are version 4.
updatedAt
string
ISO 8601 format YYYY-MM-DDThh:mm:ssZ
createdAt
string
ISO 8601 format YYYY-MM-DDThh:mm:ssZ
manufacturer
string
publisher
string
studio
string
designer
string
author
string
artist
string
productTemplateId
string
mpn
string
styleNumber
string
modelNumber
string
name
string
id
string
type
string, enum['SIMPLE', 'BUNDLE']
variants
array [Variant]

ProductList

Attributes

products
array [Product]
links
array [Link]

ProductRelation

Attributes

count
integer
relatedProductSku
array [string]
relatedProductId
string
price
CurrencyAmount
type
string, enum['BUNDLE', 'RELATED', 'ADDON']

ProductRelationList

Attributes

count
integer
relations
array [ProductRelation]

ProductSummary

Attributes

shortCode
string
price
CurrencyAmount
businessId
string
UUID version 1, 2, 3, or 4. All server generated values are version 4.
name
string
id
string

ProductSummaryList

Attributes

products
array [ProductSummary]
links
array [Link]

ProductUpload

Attributes

failedCount
integer
successCount
integer
status
string, enum['FAILED', 'PROCESSING', 'COMPLETED']
errors
array [string]
businessId
string
updatedAt
string
ISO 8601 format YYYY-MM-DDThh:mm:ssZ
createdAt
string
ISO 8601 format YYYY-MM-DDThh:mm:ssZ
id
string

ProductVariation

Attributes

attribute
string
value
string

SelectableVariation

Attributes

attribute
string
values
array [SelectableValue]
cardinality
string

Store

This is the base object for the businesses resource. Businesses resource represents a merchant business.

Attributes

gatewayStoreId
string
ID assigned to the store by the gateway (some gateways assign their own IDs). This field will typically not be available when the business is initially created in the Poynt system. Once that information is passed to the gateway, they will provide their ID.
storeTerminalIds
array [StoreTerminalId]
A list of terminal IDs that are allocated at this store.
currency
string
The primary transaction currency for this merchant.
latitude
float
Latitude of the terminal.
longitude
float
Longitude of the terminal.
status
string, enum['ACTIVE', 'DISABLED', 'REMOVED']
The status of the store.
processorData
object
catalogId
string
The default product catalog that devices at the store should use.
timezone
string
[Required] The timezone of the store.
processor
string, enum['CHASE_PAYMENTECH', 'REDE', 'EVO', 'FIRST_DATA', 'GLOBAL_PAYMENTS', 'HEARTLAND_PAYMENT_SYSTEM', 'ELAVON', 'MERCURY', 'MONERIS', 'PAYPAL', 'STRIPE', 'TSYS', 'VANTIV', 'WORLDPAY', 'EPX', 'BRIDGEPAY', 'CREDITCALL', 'NA_BANCARD', 'MOCK']
The processor for this merchant. If this field is left blank it is assumed that the processor is the acquirer itself or CreditCall that happens to be our primary gateway.
acquirer
string, enum['CHASE_PAYMENTECH', 'REDE', 'EVO', 'FIRST_DATA', 'GLOBAL_PAYMENTS', 'HEARTLAND_PAYMENT_SYSTEM', 'ELAVON', 'MERCURY', 'MONERIS', 'PAYPAL', 'STRIPE', 'TSYS', 'VANTIV', 'WORLDPAY', 'EPX', 'BRIDGEPAY', 'CREDITCALL', 'NA_BANCARD', 'MOCK']
The acquirer for this merchant.
storeDevices
array [StoreDevice]
See storeTerminalIds.
externalStoreId
string
[Required] MID (merchantId) assigned to the store by the acquirer.
phone
Phone
[Required] The store's phone. This may or may not be different from business phone.
address
Address
[Required] The store's address. This may or may not be different from business address.
id
string
The id of the store. This id is generated internally during create business.
attributes
object
A name/value pair list that could be persisted and later retreived.
displayName
string
[Required] The store name (used in various displays). It is recommended to pick a different name for each store in the business.

StoreDevice

This object represents devices in store. The most common store device represented in the Poynt system is a terminal. In the Poynt system a business can have 0 or more stores and each store can have 0 or more store devices. Note that a terminal when initially created will only have an externalTerminalId (aka TID assigned by the acquirer). It is only after the Poynt Smart Terminal arrives at the store and is activated that the deviceId is associated with the externalTerminalId to complete the terminal profile.

Attributes

lastSeenAt
string
The time (in ISO-8601 format) at which the storeDevice last had any activity. E.g. 2014-09-11T23:14:44Z.
kekDetails
array [DeviceKekData]
businessAgreements
array [Entry]
Business agreement type to business agreement object map.
publicKeyVerification
PublicKeyVerificationData
serialNumber
string
Required during activation. A manufacturer identifier for the terminal device. This is not available at the time of business onboarding as at that point a physical device has not been picked. It is assigned during terminal activation.
status
string, enum['CREATED', 'ACTIVATED', 'DEACTIVATED', 'REMOVED']
Status of device.
processorData
object
catalogId
string
The store level product catalog can be overriden at the terminal level using this field.
storeId
string
UUID version 1, 2, 3, or 4. All server generated values are version 4.
deviceId
string
Required during activation. A Poynt identifier for the terminal device. This is not available at the time of business onboarding as at that point a physical device has not been picked. It is assigned during terminal activation.
externalTerminalId
string
[Required] The TID (terminal ID) assigned to this terminal by the acquirer.
updatedAt
string
The time (in ISO-8601 format) at which the store device was updated. E.g. 2014-09-11T23:14:44Z.
createdAt
string
The time (in ISO-8601 format) at which the store device was created. E.g. 2014-09-11T23:14:44Z.
name
string
Name of the terminal assigned by the business user. It is recommended to use a different name for each terminal.
type
string, enum['TERMINAL', 'WIFI_SENSOR'] [Required] Type of device.
publicKey
string
PublicKey to verify all future JWT tokens coming from the terminal.

Tax

Attributes

description
string
rate
double
amount
integer
businessId
string
UUID version 1, 2, 3, or 4. All server generated values are version 4.
updatedAt
string
ISO 8601 format YYYY-MM-DDThh:mm:ssZ
createdAt
string
ISO 8601 format YYYY-MM-DDThh:mm:ssZ
name
string
id
string
type
string

TaxList

Attributes

taxes
array [Tax]
links
array [Link]

TokenResponse

Attributes

tokenType
string, enum['BEARER']
expiresIn
integer
scope
string
refreshToken
string
accessToken
string

Transaction

This is the base object for the transactions resource. Transactions resource represents a financial transaction. It can be used to save the transaction in the Poynt system as well as initiate interaction with the acquirer to move funds.

Attributes

action
string, enum['AUTHORIZE', 'CAPTURE', 'OFFLINE_AUTHORIZE', 'REFUND', 'SALE'] [Required] If funding source is CASH, only SALE and REFUND are the available options. If funding source is CREDIT_DEBIT, AUTHORIZE, SALE or REFUND are the possible request options. Note that even for VOID, the action is set to REFUND. OFFLINE_AUTHORIZE can only be used in a Record Transaction API to record an authorization that already happened offline.
reason
TransactionReason
status
string, enum['CREATED', 'SAVED', 'AUTHORIZED', 'PARTIALLY_CAPTURED', 'CAPTURED', 'DECLINED', 'PARTIALLY_CAPTURED_AND_PARTIALLY_REFUNDED', 'PARTIALLY_REFUNDED', 'REFUNDED', 'VOIDED']
If funding source is CASH, only CAPTURED and REFUNDED are the possible options. The SAVE feature is not applicable to CASH.
links
array [Link]
This is a response field. Hateos link pointing to all immediate parent and child transactions. E.g. a CAPTURE transaction that has been REFUNDED would have 2 links: one pointing to its parent AUTHORIZE transaction and the other to its child REFUND transaction.
fundingSource
FundingSource
[Required] The funding source used for funding this transaction.
parentId
string
In the request, if action = refund, parentId could carry the id of the transaction being refunded. Note that parentId could be empty for non-referenced refund. In the response, this will contain the parent transaction's Id (e.g. capture is the parent of refund and authorization is the parent of capture.
amounts
TransactionAmounts
[Required] All amounts requested for this transaction.
references
array [TransactionReference]
References to orders/invoices that this transaction is for.
customerUserId
integer
A Poynt generated customer id that is returned in the response. This id is only assigned only to a customer performing a card transaction.
stayType
string, enum['REGULAR_STAY', 'QUICK_STAY', 'NON_LODGING']
receiptPhone
Phone
Phone collected from the customer to SMS receipt.
receiptEmailAddress
string
Email address collected from the customer.
transactionNumber
string
A transaction number generated by the client and passed to the server. This could be anything; the server will just store it.
notes
string
Any special notes from the customer or merchant about the transaction could be recorded here.
updatedAt
string
This is a response field. The server time (in ISO-8601 format) at which this transaction was last updated. E.g. 2014-09-11T23:14:44Z.
createdAt
string
This is a response field. The server time (in ISO-8601 format) at which this transaction was initially created. E.g. 2014-09-11T23:14:44Z.
poyntLoyalty
PoyntLoyalty
processorResponse
ProcessorResponse
This is a response field. Some important response elements received from the processor.
approvalCode
string
An approval code received over the phone (in case of terminal going offline) can be passed here as part of a SALE transaction. This process in the industry is often referred to as forced post or forced sale.
context
ClientContext
[Required] Contains context about the transaction. TransmissionAtLocal must be provided. All other fields are optional.
id
string
The id of the transaction created. If provided in the request, it will be used as the transaction ID. If not provided, id will be generated internally.
signature
array [byte]
Signature collected from the customer.

TransactionAmounts

All amount related fields.

Attributes

currency
string
[Required] Currency following the ISO-4217 format (http://en.wikipedia.org/wiki/ISO_4217).
transactionAmount
integer
[Required] The total amount to be charged on the tender. This equals orderAmount + tipAmount + cashbackAmount.
orderAmount
integer
[Required] The portion of transactionAmount that went towards the item/service being purchased.
tipAmount
integer
The portion of transactionAmount that went towards tip. Defaults to 0 if not provided.
cashbackAmount
integer
The portion of transactionAmount that will be returned as cashback (mainly applicable for cash or debit-card tenders). Defaults to 0 if not provided.

TransactionList

Attributes

count
integer
links
array [Link]
transactions
array [Transaction]

TransactionReference

Reference to a document (e.g. order or invoice) that this transaction is for.

Attributes

customType
string
If type is set to CUSTOM, this must be populated. This is used to provide the name of the document being referenced.
id
string
The ID of the document.
type
string, enum['POYNT_ORDER', 'POYNT_STAY', 'CUSTOM']
The type of document. If it refers to an order maintained by Poynt, this should be set to POYNT_ORDER.

UserCredential

Attributes

publicCredentialValue
string
id
integer
privateCredentialValue
string
privateCredentialSalt
string
publicCredentialType
string, enum['USERNAME', 'EMAIL', 'JWT', 'PAYPAL']

Variant

Attributes

price
CurrencyAmount
defaultVariant
boolean
variations
array [ProductVariation]
selectableVariations
array [SelectableVariation]
inventory
array [Inventory]
sku
string
createdAt
string
ISO 8601 format YYYY-MM-DDThh:mm:ssZ
updatedAt
string
ISO 8601 format YYYY-MM-DDThh:mm:ssZ

Variation

Attributes

attribute
string
values
array [string]

VerificationData

All cardholder verification data.

Attributes

additionalIdType
string, enum['DRIVERS_LICENCE', 'EMAIL', 'PASSPORT', 'PHONE', 'NATIONAL_ID_CARD']
Type of additional ID collected.
additionalIdRefNumber
string
The additional ID collected.
cvSkipReason
string, enum['NOT_PRESENT', 'NOT_AVAILABLE', 'BYPASSED', 'ILLEGIBLE']
CVV skipped because of this reason.
cardHolderBillingAddress
Address
Address for AVS.
cvData
string
CVV information typically at the back of the card.
pin
string
The debit pin block.
keySerialNumber
string
The acquirer's KeySerialNumber (KSN) corresponding to the pin-block.