OmnyPay Platform REST API
This document provides a high level overview of OmnyPay’s Platform microservices architecture and the associated REST API.
OmnyPay’s Platform system offers the following key microservices that complement/augment cloud based retail checkout applications:
- Client Service - Session, Shopper, Basket and Receipts management API
- Identity Service - Shopper Account management and authentication API
- Management Service - Merchant onboarding, reporting, dashboards API
- PoS Service - Point of Sale network integration API
- LRO Service - Loyalty, Rewards and Offers services integration API
- eCommerce Service - integration API for various eCommerce engines
- Wallet Service - PCI compliant card vault and payment integration API
- Issuer Service - PCI compliant card issuer integration API
The following sections will provide an overview for each of these major service components.
This service provides the APIs that integrate with shopper facing mobile and web applications. Please refer to the Swagger documentation for further details.
The key resources managed by this API are:
The Shopper resource abstractly represents a shopper account in the context of a shopping session. The Shopper resource includes the following attributes:
Shopper {
id (string),
merchant-id (string),
merchant-shopper-id (string),
wallet-id (string),
default-payment-instrument-id (string, optional),
payment-instruments (Array[string], optional)
}The merchant-id and merchant-shopper-id attributes correlate this shopper resource within a merchant’s identity service.
The Session resource is a temporal container object, which associates a Device and/or a Shopper with a Merchant and Store. It offers a channel over which the Merchant can message the shopper and track their progress from an unauthenticated state, to authenticated state and subsequently through a checkout workflow.
The resource includes the following attributes:
Session {
merchant-id (string),
device-id (string),
created (string),
state (string) = ['new', 'reset', 'authenticated'],
merchant-auth-token (string, optional),
is-active (boolean),
token (string),
id (string),
shopper-id (string, optional)
}The Basket resource represents an active shopping session, which includes product line items, discount offers, payment instrument selections, split tender details and loyalty redemption status.
This resource includes the following attributes:
Basket {
id (string),
state (string) = ['new',
'initiate-payment',
'complete-scan',
'complete-transaction',
'cancel-transaction',
'ready-for-payment'],
loyalty-points (integer),
items (Array[Item]),
offers (Array[ProductOffer]),
reconciled-total (Array[ReconciledTotal])
}A Basket resource transitions through several state changes and may end in one of two terminal states complete-transaction or cancel-transaction.
This resource is created as a final step of the Basket’s transition to complete-transaction state. It represents a read-only snapshot of the line-items, payments, offers and final reconciled totals of a basket transaction.
This service provides a minimal implementation of a shopper account management and authentication API for merchants that don’t already have their own facility.
Please refer to the Swagger documentation for further details.
All you need to get started with OmnyPay Platform is the curl command.
All OmnyPay Platform REST end-points support the application/json content type for input and output content.
A typical API call can be performed as follows:
# to create a new shopper account
curl -i -H 'Content-Type: application/json' -XPOST http://${SERVER}/identity/account '{
"merchant-id" : "96078b8d-4911-4af7-b894-bc636255cd64",
"username" : "r2d2",
"password" : "secret"
}'
# and, the response would be something as follows:
#
# {
# "status" : 200,
# "body" : {
# "id" : "15267fd4-6426-4282-9c56-e60691c3f464",
# "merchant-id" : "96078b8d-4911-4af7-b894-bc636255cd64"
# }
# }All resource identifiers are version 4 UUIDs.
The Rich Checkout workflow showcases the API driven integration of three independent agents in an OmnyPay agumented physical retail shopping experience.
- A shopper’s mobile app (MobileApp)
- OmnyPay Platform services
- A point of sale terminal (PoS)
The following sections explain the coordinated interaction between these three agents from the time a shopper authenticates all the way to successfully completing a payment transaction. The abstract steps are as follows:
- Authenticate-Shopper (MobileApp)
- Create-Basket (MobileApp)
- Associate-POS (MobileApp)
- Update-Basket (PoS)
- Complete-Scan (PoS)
- Payment-Preview (MobileApp)
- Payment (MobileApp)
Some of the one-time setup API calls have been elided for brevity. The following sequence diagram outlines the required initialization prior to starting the transactional flow:
Prior to this step, the MobileApp needs to have created a session using the POST /client/session API and the POST /identity/authentication API. The session-id from that call are required for the following API calls.
This request will validate the shopper ID setup by the /identity/authentication with the merchant or the Omnway Identity Service and return the AUTH_TOKEN that should be also used for every following call.
curl -i \
-H "Content-Type: application/json" \
-XPOST http://${SERVER}/client/session/authenticate-shopper '{
"merchant-shopper-id" : "4048acd6-24d2-4dec-9511-880277893005",
"merchant-auth-token" : ${MERCHANT_AUTH_TOKEN},
"session-id" : "dc5ac492-266c-437a-bc1c-1db8e0a2376a"
}'resulting in the following JSON:
{
"merchant-id":"a3510174-183c-402c-8c4c-6c62cbfc2d96",
"device-id":"iphone123",
"created":"2016-11-17T06:35:49Z",
"state":"authenticated",
"merchant-auth-token":${MERCHANT_AUTH_TOKEN},
"is-active":true,
"token":${AUTH_TOKEN},
"id":"dc5ac492-266c-437a-bc1c-1db8e0a2376a",
"shopper-id":"7a12bdfe-86dd-4e1c-81b7-accb87ec98c4"
}Create-Basket prepares for the subsequent steps of scanning products and applying offers by creating a container resource within which the transactional state is stored.
curl -i \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ${AUTH_TOKEN}' \
-XPOST http://${SERVER}/client/basket '{
"session-id" : "dc5ac492-266c-437a-bc1c-1db8e0a2376a"
}'results in the following JSON:
{
"id":"eef75548-05d9-4a0c-b6c3-b87cb963dd5d",
"state":"new",
"loyalty-points":0,
"items":[],
"offers":[],
"reconciled-total":[]
}Associate-POS begins when a shopper brings her Basket of product items to a Point of Sale and scans a QR code image or placard at the PoS. This triggers the Associate-POS event.
As shown in the following sequence diagram, this event originates from the MobileApp to the ClientService, and is propagated by the OmnyPay Platform to the PoS network/terminal.
The following sample curl expression is an example of the associate-pos REST API call:
curl -i \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${AUTH_TOKEN}" \
-XPOST http://${SERVER}/client/basket/associate-pos '{
"basket-id" : "eef75548-05d9-4a0c-b6c3-b87cb963dd5d",
"merchant-pos-id" : "pos-id-123"
}'upon successful completion, the response body would be the following JSON:
{
"merchant-pos-id":"pos-id-123",
"merchant-pos-label":"store-001-pos-123"
}This originates from the PoS when the store employee begins scanning the product items. The PoSAdapter abstracts the transport between the PoS terminal or network.
The basket-update-notification messages keep the MobileApp updated with the state of the basket, including product items and associated offers.
This call originates from the PoS to signal that all product items have been scanned.
Upon receiving the complete-scan notification, the MobileApp presents the shopper with one or more payment instrument options. As the shopper switches between the available payment instruments, the payment-preview API call may be used to non-destructively apply payment instrument offers and recalculate the basket totals.
Sample curl expression:
curl -i \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${AUTH_TOKEN}" \
-XPOST http://${SERVER}/client/payment-preview '{
"basket-id" : "eef75548-05d9-4a0c-b6c3-b87cb963dd5d",
"payment-instrument-id" : "f84566c9-c8aa-448c-96e9-bc941898c2b0"
}'{"id":"eef75548-05d9-4a0c-b6c3-b87cb963dd5d",
"state":"complete-scan",
"payment-instrument-id":"f84566c9-c8aa-448c-96e9-bc941898c2b0",
"loyalty-points":20,
"items":[{"sku":"sku123",
"name":"gummybears",
"qty":1,
"price":10000},
{"sku":"sku456",
"name":"gummybears",
"qty":1,
"price":1000}],
"offers":[{"description":"Ultimate Toy for Toddlers",
"image-url":"http://get-my-image.com/sku123.png",
"merchant-id":"a3510174-183c-402c-8c4c-6c62cbfc2d96",
"redemptions-allowed":10,
"discount-cents":1000,
"created":"2016-11-17T06:35:49Z",
"title":"Blue Green Toy",
"sku":"sku123",
"is-active":true,
"id":"fb8e08ef-65b8-4163-8631-4a9789785e40",
"discount-pct":20},
{"description":"Breeze your way",
"image-url":"http://get-my-image.com/sku123.png",
"merchant-id":"a3510174-183c-402c-8c4c-6c62cbfc2d96",
"redemptions-allowed":10,
"discount-cents":2000,
"created":"2016-11-17T06:35:49Z",
"title":"Table Fan",
"sku":"sku456",
"is-active":true,
"id":"1056454c-0c0a-4ccf-868b-0f3252ab6635",
"discount-pct":10}],
"payment-type-offers":[{"description":"For Credit Card",
"image-url":"http://get-my-image.com/card.png",
"merchant-id":"a3510174-183c-402c-8c4c-6c62cbfc2d96",
"redemptions-allowed":10,
"discount-cents":1000,
"created":"2016-11-17T06:35:49Z",
"title":"Credit Card Offer",
"is-active":true,
"id":"e626f04a-51e0-4bd9-8eab-9fce905b598c",
"payment-type":"credit",
"discount-pct":20}],
"reconciled-total":[{"sku":"sku123",
"total":10000,
"discounted-total":9000,
"tax":800,
"discount-cents":1000,
"discount-pct":10},
{"sku":"sku456",
"total":1000,
"discounted-total":-1000,
"tax":80,
"discount-cents":2000,
"discount-pct":200}],
"total-summary":{"discounted-total":6800,
"product-offer-cents":3000,
"payment-offer-cents":1000,
"discount-cents":4200,
"tax":880,
"loyalty-cents":200,
"payment-total":7680,
"total":11000,
"discount-pct":38}}The payment API call is invoked by the MobileApp to confirm the final basket totals (after discounts etc.) and initiate payment.
Sample curl:
curl -i \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${AUTH_TOKEN}" \
-XPOST http://${SERVER}/client/payment '{
"basket-id" : "eef75548-05d9-4a0c-b6c3-b87cb963dd5d",
"payment-instrument-id" : "f84566c9-c8aa-448c-96e9-bc941898c2b0"
}'JSON response:
{
"basket-id":"eef75548-05d9-4a0c-b6c3-b87cb963dd5d",
"status":"ok"
}This call returns immediately and successful completion of the payment transaction will be sent back asynchronously via a notification.