API

Poynt

The world's first smart payment terminal.
Sign in
DocumentationAPI reference
  • Poynt API
  • introduction
  • Standards
  • Oauth
  • token
  • payments
  • Orders
  • Get all orders
  • Record order
  • Update order
  • Get an order
  • Cancel order
  • Transactions
  • Get all transactions
  • Update transaction
  • Get a transaction
  • Record transaction
  • Customers
  • Create a customer
  • Search customers
  • Lookup by card
  • Get By Id
  • merchants
  • Businesses
  • Get by device Id
  • Get by businessId
  • Business Users
  • Get All Users
  • Get User
  • products
  • Products
  • Batch Create
  • Get List
  • Create
  • Get Multiple Id
  • Get Summary
  • Get ProductUpload By Id
  • Deactivate
  • Get By Id
  • Update By Id
  • Remove relation
  • Get relations
  • Add relation
  • Upsert variant
  • Get all variants
  • Delete variant
  • Catalogs
  • Create
  • Get List
  • Create Full
  • Search Catalog
  • Update catalog
  • Delete catalog
  • Get By Id
  • Create category
  • Get Multiple Id
  • Get category by id
  • Delete category
  • Update category
  • Get Full Catalog By Id
  • Taxes
  • Get List
  • Create
  • Delete tax
  • Get
  • Update
  • notifications
  • Cloudmessages
  • Send cloud message
  • Hooks
  • Get List
  • Create
  • Delete hook
  • Get By Id
  • Delivery
  • Get List
  • Redeliver By Time
  • Redeliver Event
  • Models
  • AVSResult
  • ActiveTime
  • Address
  • AvailableDiscount
  • Business
  • BusinessUser
  • Card
  • CardKeyData
  • Catalog
  • CatalogItem
  • CatalogItemWithProduct
  • CatalogList
  • CatalogWithProduct
  • Category
  • CategoryList
  • CategoryWithProduct
  • ClientContext
  • CloudMessage
  • ComponentName
  • CurrencyAmount
  • Customer
  • CustomerBusinessPreferences
  • CustomerInsights
  • CustomerList
  • CustomerScore
  • CustomerTopItem
  • Delivery
  • DeliveryList
  • Device
  • DeviceMacAddress
  • Discount
  • EMVData
  • EmploymentDetails
  • FundingSource
  • FundingSourceEntryDetails
  • Hook
  • HookList
  • Inventory
  • JsonPatch
  • Link
  • Order
  • OrderAmounts
  • OrderItem
  • OrderItemTax
  • OrderList
  • OrderStatuses
  • Phone
  • ProcessorResponse
  • Product
  • ProductList
  • ProductRelation
  • ProductRelationList
  • ProductSummary
  • ProductSummaryList
  • ProductUpload
  • ProductVariation
  • SelectableVariation
  • Store
  • StoreDevice
  • Tax
  • TaxList
  • TokenResponse
  • Transaction
  • TransactionAmounts
  • TransactionList
  • TransactionReference
  • UserCredential
  • Variant
  • Variation
  • VerificationData

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:

  • Api-Version - Must be 1.2
  • Authorization - Bearer <poynt-issued-access-token>
  • Content-Type - Usually application/json
  • POYNT-REQUEST-ID - a unique request id to enforce idempotency where ever appropriate (usually for POST requests)

HTTP Status Code

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

  • 200 - OK, the operation was successful.
  • 201 - Created, when a new resource is created.
  • 204 - No Content, usually returned after deleting a resource.
  • 400 - Bad Request
  • 401 - Unauthorized, due to invalid access token or authorization needed.
  • 403 - Forbidden
  • 404 - Not Found
  • 500 - Internal Server Error

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:

  • BUSINESS_USER_CREATED - published when a business (terminal) user is created
  • BUSINESS_USER_UPDATED - published when a business (terminal) user is updated
  • CATALOG_CREATED - published when a catalog is created
  • CATALOG_UPDATED - published when a catalog is updated
  • CATALOG_DELETED - published when a catalog is deleted
  • CATEGORY_CREATED - published when a category is created
  • CATEGORY_UPDATED - published when a category is updated
  • CATEGORY_DELETED - published when a category is deleted
  • INVENTORY_UPDATED - published when inventory is updated
  • ORDER_OPENED - published when a new order is OPENED
  • ORDER_CANCELLED - published when an order is CANCELLED
  • ORDER_COMPLETED - published when an order is COMPLETED
  • ORDER_UPDATED - published when anything other than status changes in the order
  • ORDER_ITEM_ORDERED - published when a new item is ORDERED
  • ORDER_ITEM_FULFILLED - published when an item is FULFILLED
  • ORDER_ITEM_RETURNED - published when an item is RETURNED
  • ORDER_ITEM_DELETED - published when an item is DELETED
  • ORDER_ITEM_UPDATED - published when anything other than status changes in the item
  • PRODUCT_CREATED - published when a new product is created
  • PRODUCT_UPDATED - published when product is updated
  • PRODUCT_DELETED - published when product is deleted
  • STORE_CREATED - published when a store is created
  • STORE_UPDATED - published when a store is updated
  • TAX_CREATED - published when a new tax is created
  • TAX_UPDATED - published when a tax is updated
  • TAX_DELETED - published when a tax is deleted
  • TRANSACTION_AUTHORIZED - published when a transaction is authorized
  • TRANSACTION_CAPTURED - published when a transaction is captured
  • TRANSACTION_REFUNDED - published when a captured transaction is refunded
  • TRANSACTION_UPDATED - published when a transaction is updated
  • TRANSACTION_VOIDED - published when a transaction is voided
  • USER_CREATED - published when a web/HQ user is created
  • USER_JOIN_ORG - published when a web/HQ user joins a developer organization
  • USER_LEAVE_ORG - published when a web/HQ user leaves a developer organization
  • USER_JOIN_BIZ - published when a web/HQ user joins a business
  • USER_LEAVE_BIZ - published when a web/HQ user leaves a business
  • USER_UPDATED - published when a web/HQ user is updated

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 'BAD_FORMAT'] 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'] 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'] 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'] 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'] 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'] actualResult string 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']

ActiveTime

Attributes

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

Address

Attributes

postalCodeExtension string status string, enum['ADDED'] countryCode string postalCodeExtension string 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 createdAt string
The time (in ISO-8601 format) at which the address was updated. E.g. 2014-09-11T23:14:44Z. createdAt created. E.g. 2014-09-11T23:14:44Z. updatedAt string
The time (in ISO-8601 format) at which the address was created. E.g. 2014-09-11T23:14:44Z. updated. E.g. 2014-09-11T23:14:44Z. line1 string line2 string city string territory string postalCode string status string, enum['ADDED'] 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'] fixed integer id string code string scope string, enum['ITEM', 'ORDER']

Business

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

Attributes

timezone string
[Required] The timezone that the headquarters belong to.
emailAddress string
The main business email address.
externalMerchantId string
This is the unique identifier assigned by the acquirer to the business. It is a business level MID.
legalName string
[Required] The legal name of the business.
businessUrl string
The url of the business' website. doingBusinessAs string
[Required] The name the business likes to be known as.
industryType string
The industry type that this business belongs to. sic string
[Required] The standard industry code of the business.
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
phone Phone Link: #model-phone
[Required] The main business phone.
stores array [Store Link: #model-store ]
The list of stores within this
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'] attributes object Link: #model-object
A name/value pair list that could be persisted and later retreived.
type string, enum['MERCHANT', 'TEST_MERCHANT', 'DEVELOPER', 'DISTRIBUTOR', 'ORGANIZATION'] [Required] The type of business. 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.
createdAt string
ISO 8601 format YYYY-MM-DDThh:mm:ssZ
updatedAt string
ISO 8601 format YYYY-MM-DDThh:mm:ssZ
mcc string
[Required] The merchant category code of the business.
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 Link: #model-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 Link: #model-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.
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'] 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 Link: #model-object
A name/value pair list that could be persisted and later retreived.

BusinessUser

Attributes

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.

BusinessUser

Attributes

middleName string middleInitial string email string userId integer
employmentDetails EmploymentDetails credentials array [UserCredential Link: #model-usercredential ] status string, enum['EMPLOYED', 'TERMINATED'] email string cards array [Card] emailSignupCode string middleInitial string middleName string userId integer credentials array [UserCredential Link: #model-usercredential ] emailSignupCode string 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. endDate integer startDate integer status string, enum['EMPLOYED', 'TERMINATED']

Card

Object to carry credit/debit card information.

Attributes

serviceCode string 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).
expirationYear integer
The year from expiration.
track1data string
In some use-cases (like airlines) Track1 is required. Track1 contains some extra information over Track2 (like cardholder's name). track2data string
Required for swiped transactions. Track2 read from the card contains PAN, expiration, etc.
track3data string
Track3 for future use. Carries track from custom funding sources.
numberHashed string keySerialNumber string
KeySerialNumber of the Poynt P2PE DUKPT key. If encrypted is true, only one of key and keySerialNumber can be populated (not both).
numberFirst6 string
This is a response field. The first6 numbers of the PAN.
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.
cardHolderFullName string
Card holder's full name usually picked from track1.
status string, enum['ACTIVE', 'REMOVED']
Status of the card.
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'] 'VISA']
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 Link: #model-catalogitem ] availableDiscounts array [AvailableDiscount] taxes array [Tax Link: #model-tax ] products array [CatalogItem Link: #model-catalogitem ] priceBookId string businessId string
UUID version 1, 2, 3, or 4. All server generated values are version 4. updatedAt createdAt string
The time (in ISO-8601 format) at which the Catalog was updated. E.g. 2014-09-11T23:14:44Z. createdAt created. E.g. 2014-09-11T23:14:44Z. updatedAt string
The time (in ISO-8601 format) at which the Catalog was created. E.g. 2014-09-11T23:14:44Z. updated. E.g. 2014-09-11T23:14:44Z. taxes array [Tax Link: #model-tax ] 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 Link: #model-catalogitemwithproduct taxes array [Tax Link: #model-tax ] availableDiscounts array [AvailableDiscount] taxes array [Tax Link: #model-tax ] products array [CatalogItemWithProduct Link: #model-catalogitemwithproduct ] categories array [CategoryWithProduct Link: #model-categorywithproduct ] id string createdAt string
The time (in ISO-8601 format) at which the Catalog was created. E.g. 2014-09-11T23:14:44Z.
updatedAt string
The time (in ISO-8601 format) at which the Catalog was updated. E.g. 2014-09-11T23:14:44Z.
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 Link: #model-categorywithproduct ] name string id name string

Category

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

Attributes

availableDiscounts array [AvailableDiscount Link: #model-availablediscount ] products array [CatalogItem ] parentCategoryId string shortCode string taxes array [Tax Link: #model-tax ] displayOrder integer color string name string id string

CategoryList

Attributes

categories array [Category Link: #model-category ] links array [Link Link: #model-link ]

CategoryWithProduct

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

Attributes

taxes array [Tax Link: #model-tax ] availableDiscounts array [AvailableDiscount]
taxes array [Tax Link: #model-tax ] parentCategoryId string shortCode string displayOrder integer color string name string id string

CategoryList

Attributes

links array [Link Link: #model-link ] categories array [Category Link: #model-category ]

CategoryWithProduct

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

Attributes

products array [CatalogItemWithProduct] availableDiscounts array [AvailableDiscount Link: #model-availablediscount ] taxes array [Tax Link: #model-tax ] parentCategoryId string shortCode id string shortCode string parentCategoryId 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'] transmissionAtLocal string
This is required if ClientContext is inside Order. The source where the transaction was initiated. 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. 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. source string, enum['INSTORE', 'WEB', 'MOBILE', 'CALLIN', 'CATALOG']
This is required if ClientContext is inside Order. The source where the transaction was initiated.
businessId string
This is optional as it can always be picked from the JWT token used for authentication.
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 mid string
The acquirer assigned merchant ID (aka MID) for this store.
tid string
The acquirer assigned terminal ID (aka TID) for the terminal.
storeId string
This is optional as it can always be picked from the JWT token used for authentication.
sourceApp string

CloudMessage

Attributes

collapseKey string storeDeviceId string
This is optional as it can always be picked from the JWT token used for authentication.
sourceApp string employeeUserId integer
This is optional as it can always be picked from the JWT token used for authentication.

CloudMessage

Attributes

sender string data string ttl integer serialNum string collapseKey string id string recipient ComponentName deviceId string businessId string storeId string

ComponentName

Attributes

packageName string className string

CurrencyAmount

Attributes

currency string amount integer

Customer

Attributes

middleName string middleInitial string nickName string cards array [Card Link: #model-card ] businessPreferences CustomerBusinessPreferences Link: #model-customerbusinesspreferences insights CustomerInsights Link: #model-customerinsights devices array [Device Link: #model-device ] loyaltyCustomers array [LoyaltyCustomer Link: #model-loyaltycustomer ] emails array [Entry Link: #model-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.
phones array [Entry Link: #model-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.
addresses array [Entry Link: #model-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.
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 Link: #model-device ] addresses array [Entry Link: #model-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 Link: #model-customerinsights loyaltyCustomers array [LoyaltyCustomer Link: #model-loyaltycustomer ] nickName string businessPreferences CustomerBusinessPreferences Link: #model-customerbusinesspreferences cards array [Card Link: #model-card ] middleName string middleInitial string businessId string
UUID version 1, 2, 3, or 4. All server generated values are version 4.
phones array [Entry Link: #model-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 Link: #model-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
createdAt string
The time (in ISO-8601 format) at which the Customer was updated. E.g. 2014-09-11T23:14:44Z. createdAt created. E.g. 2014-09-11T23:14:44Z. updatedAt string
The time (in ISO-8601 format) at which the Customer was created. updated. E.g. 2014-09-11T23:14:44Z. firstName string lastName string id integer attributes object

CustomerBusinessPreferences

Attributes

preferredCardId integer

CustomerInsights

Attributes

topItems array [CustomerTopItem Link: #model-customertopitem ] totalOrders integer poyntLoyalty PoyntLoyalty Link: #model-poyntloyalty lifetimeSpend array [CurrencyAmount Link: #model-currencyamount ] scores array [CustomerScore Link: #model-customerscore ] 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 Link: #model-poyntloyalty scores array [CustomerScore Link: #model-customerscore ] topItems array [CustomerTopItem Link: #model-customertopitem ] totalOrders integer lifetimeSpend array [CurrencyAmount Link: #model-currencyamount ]

CustomerList

Attributes

count integer

CustomerList

Attributes

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

CustomerScore

Attributes

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

CustomerTopItem

Attributes

variationId integer lastPurchasedAt integer count double productId integer 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 variationId integer firstPurchasedAt integer lastPurchasedAt integer count double 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 Link: #model-link ] resourceId string hookId string 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 createdAt string
The time (in ISO-8601 format) at which the Delivery was updated. E.g. 2014-09-11T23:14:44Z. createdAt created. E.g. 2014-09-11T23:14:44Z. updatedAt string
The time (in ISO-8601 format) at which the Delivery was created. E.g. 2014-09-11T23:14:44Z. hookId string updated. E.g. 2014-09-11T23:14:44Z. deviceId string attempt integer applicationId string deliveryUrl string secret string links array [Link Link: #model-link ] eventType string status string, enum['SCHEDULED', 'RESCHEDULED', 'ERRORED_RETRYING', 'DELIVERED', 'ERRORED'] resource string id string

DeliveryList

Attributes

deliveries array [Delivery] links array [Link]

Device

Attributes

deviceType string, enum['MOBILE', 'UNKNOWN'] 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. amount integer
[Required] Amount of discount.
processor string processorResponse ProcessorResponse Link: #model-processorresponse provider string 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 Link: #model-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

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

FundingSource

The funding source used for funding transactions.

Attributes

debitEBTReEntryDetails DebitEBTReEntry card Card Link: #model-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 Link: #model-ebtdetails entryDetails FundingSourceEntryDetails Link: #model-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. ebtDetails EBTDetails Link: #model-ebtdetails card Card Link: #model-card
If type is CREDIT_DEBIT, this is required. This carries details about the card.
entryDetails FundingSourceEntryDetails Link: #model-fundingsourceentrydetails
If type is CREDIT_DEBIT, this is required. This carries details about how the funding source data was collected on the terminal.
customFundingSource CustomFundingSource Link: #model-customfundingsource
If type is CUSTOM_FUNDING_SOURCE, this is required. This carries details about the custom funding source.
verificationData VerificationData
If type is CREDIT_DEBIT, this will carry any data needed to verify the card. customFundingSource CustomFundingSource Link: #model-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 createdAt string
The time (in ISO-8601 format) at which the Hook was updated. E.g. 2014-09-11T23:14:44Z. createdAt created. E.g. 2014-09-11T23:14:44Z. updatedAt string
The time (in ISO-8601 format) at which the Hook was created. E.g. 2014-09-11T23:14:44Z. updated. E.g. 2014-09-11T23:14:44Z. applicationId string
ApplicationId e.g. urn:aid:c5aaffaf-ee8c-41bc-82fa-88882222ddde.
deliveryUrl string
The Url at which to deliver the webhook event.
secret string
Used for signing the webhook event.
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. stockCount float
The actual physical count of the product the business has.
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 createdAt string
The time (in ISO-8601 format) at which the Inventory was created. E.g. 2014-09-11T23:14:44Z. updatedAt string
The time (in ISO-8601 format) at which the Inventory was
updated. E.g. 2014-09-11T23:14:44Z. reOrderPoint float
When the stockCount reach this value, inventory should be reordered.

JsonPatch

Attributes


Link

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 Link: #model-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 Link: #model-link ]
This is a response only field. It will include HATEOS links to any related orders.
transactions array [Transaction Link: #model-transaction ]
A list of transactions being performed to pay for this order.
items array [OrderItem Link: #model-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 Link: #model-orderamounts
[Required] A summary of all amounts represented in the items, discounts and transactions objects.
transactions array [Transaction Link: #model-transaction ]
A list of transactions being performed to pay for this order.
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'] orderNumber string
Stores often use a human readable order number to hand out to customers. Such numbers could be passed here.
notes string
Any special notes from the customer or merchant about the order could be recorded here. updatedAt parentId string
When creating a return order, the original order's ID can be specified here.
amounts OrderAmounts Link: #model-orderamounts
[Required] A summary of all amounts represented in the items, discounts and transactions objects.
statuses OrderStatuses Link: #model-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.
createdAt 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 created. E.g. 2014-09-11T23:14:44Z. updatedAt 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. updated. E.g. 2014-09-11T23:14:44Z. items array [OrderItem Link: #model-orderitem ]
A list of items (or services) being purchased.
links array [Link Link: #model-link ]
This is a response only field. It will include HATEOS links to any related orders.
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). currency string
[Required] Currency of the order.
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. discountTotal integer
[Required] Sum of all order and item level discounts. Negative amount for purchases, positive amount for returns.
feeTotal integer 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.
productId string
Not being used - will be removed.
details string
Item details.
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 discounts array [Discount Link: #model-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).
fees array [Fee Link: #model-fee ] 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.
clientNotes string
Any special instructions related to this order item.
unitPrice integer
[Required] Price for each unit.
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.
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.
fee integer 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 Link: #model-variant ] fees array [Fee Link: #model-fee ] discounts array [Discount Link: #model-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 Link: #model-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. selectedVariants array [Variant Link: #model-variant ] taxes array [OrderItemTax Link: #model-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).
status string, enum['ORDERED', 'FULFILLED', 'RETURNED'] [Required] Status of the item. name string
[Required] Name 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.

OrderItemTax

Attributes

amount integer type string id id string type string

OrderList

Attributes

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

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 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.

Phone

Attributes

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

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. cardToken string retrievalRefNum string transactionId string
The transactionID that came back from the acquirer.
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 Link: #model-avsresult
The address verification results.
transactionId string
The transactionID that came back from the acquirer.
remainingBalance integer
The amount that is left on the prepaid card after an authorization.
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 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 Link: #model-avsresult
The address verification results.
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.

Product

Attributes

avgUnitCost CurrencyAmount Link: #model-currencyamount releaseDate string
ISO 8601 format YYYY-MM-DDThh:mm:ssZ
msrp CurrencyAmount Link: #model-currencyamount inventory array [Inventory Link: #model-inventory ] bundledProducts array [ProductRelation Link: #model-productrelation ] addonProducts array [ProductRelation Link: #model-productrelation ] relatedProducts array [ProductRelation Link: #model-productrelation ] templateOverrides array [string] possibleVariations array [Variation Link: #model-variation ] ean string upc string isbn string plu string asin string specification string brand string manufacturer string publisher string studio string designer string author string artist string productTemplateId string mpn string styleNumber string modelNumber string description string tags string businessId string
UUID version 1, 2, 3, or 4. All server generated values are version 4.
shortCode string price CurrencyAmount Link: #model-currencyamount sku string selectableVariants array [Variant Link: #model-variant ] createdAt string
ISO 8601 format YYYY-MM-DDThh:mm:ssZ
updatedAt string
ISO 8601 format YYYY-MM-DDThh:mm:ssZ
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 Link: #model-productrelation ] relatedProducts array [ProductRelation Link: #model-productrelation ] addonProducts array [ProductRelation Link: #model-productrelation ] possibleVariations array [Variation Link: #model-variation ] inventory array [Inventory Link: #model-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 Link: #model-currencyamount avgUnitCost CurrencyAmount Link: #model-currencyamount imageUrl array [string] selectableVariants array [Variant Link: #model-variant ] sku string shortCode string price CurrencyAmount Link: #model-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 status string, enum['ACTIVE', 'RETIRED'] 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 count integer type string, enum['BUNDLE', 'RELATED', 'ADDON']

ProductRelationList

Attributes

count integer relations array [ProductRelation]

ProductSummary

Attributes

shortCode string price CurrencyAmount Link: #model-currencyamount count integer

ProductSummary

Attributes

businessId string
UUID version 1, 2, 3, or 4. All server generated values are version 4. shortCode string price CurrencyAmount Link: #model-currencyamount name string id string

ProductSummaryList

Attributes

products array [ProductSummary] links array [Link]

ProductUpload

Attributes

failedCount integer successCount integer successCount integer failedCount integer errors array [string] businessId string createdAt string
ISO 8601 format YYYY-MM-DDThh:mm:ssZ
updatedAt string
ISO 8601 format YYYY-MM-DDThh:mm:ssZ
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 cardinality string values array [SelectableValue] cardinality attribute string

Store

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

Attributes

catalogId string
The default product catalog that devices at the store should use.
externalStoreId string
[Required] MID (merchantId) assigned to the store by the acquirer.
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 Link: #model-storeterminalid ]
A list of terminal IDs that are allocated at this store.
longitude float
Longitude of the terminal.
latitude float
Latitude of the terminal.
timezone string
[Required] The timezone of the store.
phone Phone Link: #model-phone
[Required] The store's phone. This may or may not be different from business phone.
processorData object Link: #model-object fixedLocation boolean storeDevices array [StoreDevice Link: #model-storedevice ]
List of terminals that this store has.
attributes object Link: #model-object
A name/value pair list that could be persisted and later retreived.
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
id string
The id
of the store. processorData object Link: #model-object catalogId string
The default product catalog that devices at the store should use.
timezone string
[Required] The timezone of the store.
This id is generated internally during create business. 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.
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 Link: #model-storedevice ]
See storeTerminalIds.
externalStoreId string
[Required] MID (merchantId) assigned to the store by the acquirer.
phone Phone Link: #model-phone
[Required] The store's phone. This may or may not be different from business phone.
timeZone string
[Required] The timezone of the store. Please use timezone.
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 Link: #model-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. status string, enum['ACTIVE', 'DISABLED', 'REMOVED']
The status of the store.

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 Link: #model-devicekekdata ] businessAgreements array [Entry Link: #model-entry ]
Business agreement type to business agreement object map.
publicKeyVerification PublicKeyVerificationData Link: #model-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 Link: #model-object publicKey string
PublicKey to verify all future JWT tokens coming from the terminal.
catalogId string
The store level product catalog can be overriden at the terminal level using this field. lastSeenAt string
The time (in ISO-8601 format) at which the storeDevice last had any activity. E.g. 2014-09-11T23:14:44Z.
externalTerminalId string
[Required] The TID (terminal ID) assigned to this terminal by the acquirer.
processorData object Link: #model-object kekDetails array [DeviceKekData Link: #model-devicekekdata ] publicKeyVerification PublicKeyVerificationData Link: #model-publickeyverificationdata type string, enum['TERMINAL', 'WIFI_SENSOR'] [Required] Type of device. createdAt string
The time (in ISO-8601 format) at which the store device was created. E.g. 2014-09-11T23:14:44Z.
updatedAt string
The time (in ISO-8601 format) at which the store device was updated. E.g. 2014-09-11T23:14:44Z.
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.
storeId string
UUID version 1, 2, 3, or 4. All server generated values are version 4. deviceId serialNumber string
Required during activation. A Poynt 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. 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.
status string, enum['CREATED', 'ACTIVATED', 'DEACTIVATED', 'REMOVED']
Status of device.
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

Tax

Attributes

rate double description string businessId string
UUID version 1, 2, 3, or 4. All server generated values are version 4. updatedAt amount integer createdAt string
ISO 8601 format YYYY-MM-DDThh:mm:ssZ createdAt updatedAt 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 tokenType string, enum['BEARER'] 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

poyntLoyalty PoyntLoyalty Link: #model-poyntloyalty 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 Link: #model-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 Link: #model-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.
receiptEmailAddress string
Email address collected from the customer.
fundingSource FundingSource
[Required] The funding source used for funding this transaction. transactionNumber string
A transaction number generated by the client and passed to the server. This could be anything; the server will just store it.
processorResponse ProcessorResponse Link: #model-processorresponse
This is a response field. Some important response elements received from the processor.
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.
notes string
Any special notes from the customer or merchant about the transaction could be recorded here.
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 Link: #model-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 Link: #model-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 Link: #model-poyntloyalty processorResponse ProcessorResponse Link: #model-processorresponse updatedAt string
This is a response field. Some important response elements received from the processor. The server time (in ISO-8601 format) at which this transaction was last updated. E.g. 2014-09-11T23:14:44Z. 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. references array [TransactionReference Link: #model-transactionreference ]
References to orders/invoices that this transaction is for.
links array [Link Link: #model-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.
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.
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

customerOptedNoTip boolean 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 Link: #model-link ] tipAmount integer
The portion of transactionAmount that went towards tip. Defaults to 0 if not provided.
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.

TransactionList

Attributes

transactions array [Transaction] links array [Link Link: #model-link ] count integer

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 Link: #model-currencyamount defaultVariant boolean variations array [ProductVariation Link: #model-productvariation ] selectableVariations array [SelectableVariation Link: #model-selectablevariation ] publicCredentialValue string id integer

Variant

Attributes

inventory array [Inventory] variations array [ProductVariation Link: #model-productvariation ] price CurrencyAmount Link: #model-currencyamount 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 selectableVariations array [SelectableVariation Link: #model-selectablevariation ]

Variation

Attributes

values array [string] attribute 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.
keySerialNumber string
The acquirer's KeySerialNumber (KSN) corresponding to the pin-block.
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.
cvData string
CVV information typically at the back of the card.