Mobile Payments

A set of endpoints dedicated for mobile payment solution providers integrating with POS

Simplified Mobile Payment Flow sequence diagram

  1. The 3rd Party sends a request to retrieve a check by order number.
  2. The 3rd Party receives a list of checks matching the provided order number.
  3. The 3rd Party sends a request to execute a payment transaction using an access token obtained via the Auth Token process, as described in Access Token Exchange Flow.
  4. The 3rd Party receives payment data upon a successful sale.
  5. The 3rd Party registers the payment data for the specific check.
  6. The 3rd Party receives the payment identifier and the remaining amount due, if applicable.

Methods

Retrieve Checks for a location

Retrieve Checks for a specified location.

GET /pos/v2/{locationId}/checks

Path Parameters

Name Type Description
locationId* integer The unique identifier of the location.

Query Parameters

Name Type Description
filter object Set of search parameters. They can be defined as URI parameters or a JSON object.
filter.status array Filterable check statuses. Only 'OPEN' is supported at this time. Reserved for future use.
filter.orderNumber string A number to filter the checks by.

Response 200

A list of Checks

{
  "results": [
    {
      "posRef": "string",
      "orderNumber": "string",
      "tableName": "string",
      "guestCount": 0,
      "status": "OPEN",
      "openedAt": "2025-12-03T13:20:31.662Z",
      "ownedByEmployeeRef": "string",
      "ownedByEmployee": "string",
      "subtotal": 0,
      "dualPricing": {
        "cashTotal": 0,
        "cashAmountDue": 0
      },
      "supplementalFee": {
        "name": "string",
        "amount": 0
      },
      "taxes": 0,
      "otherTaxes": 0,
      "taxList": [
        {
          "name": "string",
          "amount": 0
        }
      ],
      "hiddenTaxList": [
        {
          "name": "string",
          "amount": 0
        }
      ],
      "gratuity": 0,
      "total": 0,
      "paymentAmountDue": 0,
      "paymentAmountPaid": 0,
      "isLocked": true,
      "items": [
        {
          "posRef": "string",
          "name": "string",
          "quantity": 0,
          "modifiersAsText": "string",
          "price": 0
        }
      ]
    }
  ],
  "meta": {}
}

Response 400

Bad Request – validation error

{
  "status": 400,
  "timestamp": "2025-12-03T13:20:31.662Z",
  "message": "Validation error",
  "details": [
    "string"
  ]
}

Response 401

Unauthorized – missing or invalid authentication

{
  "status": 401,
  "timestamp": "2025-12-03T13:20:31.662Z",
  "message": "Unauthorized",
  "details": [
    "string"
  ]
}

Response 500

Internal Server Error – unexpected server error

{
  "status": 500,
  "timestamp": "2025-12-03T13:20:31.662Z",
  "message": "Internal Server Error",
  "details": [
    "string"
  ]
}

Retrieve a Check for a location

Retrieve a Check for a specified location.

GET /pos/v2/{locationId}/checks/{posRef}

Path Parameters

Name Type Description
locationId* integer The unique identifier of the location.
posRef* string The unique identifier of the check.

Response 200

A uniquely identified Check

{
  "posRef": "string",
  "orderNumber": "string",
  "tableName": "string",
  "guestCount": 0,
  "status": "OPEN",
  "openedAt": "2025-12-03T13:20:31.663Z",
  "ownedByEmployeeRef": "string",
  "ownedByEmployee": "string",
  "subtotal": 0,
  "dualPricing": {
    "cashTotal": 0,
    "cashAmountDue": 0
  },
  "supplementalFee": {
    "name": "string",
    "amount": 0
  },
  "taxes": 0,
  "otherTaxes": 0,
  "taxList": [
    {
      "name": "string",
      "amount": 0
    }
  ],
  "hiddenTaxList": [
    {
      "name": "string",
      "amount": 0
    }
  ],
  "gratuity": 0,
  "total": 0,
  "paymentAmountDue": 0,
  "paymentAmountPaid": 0,
  "isLocked": true,
  "items": [
    {
      "posRef": "string",
      "name": "string",
      "quantity": 0,
      "modifiersAsText": "string",
      "price": 0
    }
  ]
}

Response 400

Bad Request – validation error

{
  "status": 400,
  "timestamp": "2025-12-03T13:20:31.663Z",
  "message": "Validation error",
  "details": [
    "string"
  ]
}

Response 401

Unauthorized – missing or invalid authentication

{
  "status": 401,
  "timestamp": "2025-12-03T13:20:31.663Z",
  "message": "Unauthorized",
  "details": [
    "string"
  ]
}

Response 404

Check not found

{
  "status": 404,
  "timestamp": "2025-08-13T11:56:09.807Z",
  "message": "Check not found",
  "details": []
}

Response 500

Internal Server Error – unexpected server error

{
  "status": 500,
  "timestamp": "2025-12-03T13:20:31.663Z",
  "message": "Internal Server Error",
  "details": [
    "string"
  ]
}

Pay for a specific check

Pay for a specific check.

POST /pos/v2/{locationId}/checks/{posRef}/pay

Path Parameters

Name Type Description
locationId* integer The unique identifier of the location.
posRef* string The unique identifier of the check.

Request Body (required)

Content-Type: application/json

Name Type Description
amount* integer Payment amount in cents.
tip integer Optional tip amount in cents.
universalToken string Optional processor universal token.
card* object Card details used for the payment.
card.type* string Card type code: AX - American Express YC - IT’S YOUR CARD (gift card hosted by shift4) WP - WeChat Pay VS - Visa SC - Sears Canada PL - Private Label NS - Discover/JCB/Novus MC - Mastercard JC - JCB GC - Gift Card (POSDK ref: EDCType) DB - Debit Card (POSDK ref: EDCType) CI - Citgo BC - Backed Card AP - Alipay
card.last4Digits* string Last four digits of the card number.
card.expirationDate* string Card expiration date in MMYY format (e.g., 0126 for Jan 2026).
card.holderName string Cardholder name.
card.token* string Processor token for the card.
transaction* object Transaction details from the processor.
transaction.authorizationCode* string Authorization code returned by the processor.
transaction.invoice* string Invoice or transaction identifier.

Example body:

{
  "amount": 0,
  "card": {
    "type": "AX",
    "last4Digits": "string",
    "expirationDate": "string",
    "token": "string"
  },
  "transaction": {
    "authorizationCode": "string",
    "invoice": "string"
  }
}

Response 200

Payment successful

{
  "paymentRef": "string",
  "remainingAmount": "string"
}

Response 400

Bad Request – validation error

{
  "status": 400,
  "timestamp": "2025-12-03T13:20:31.664Z",
  "message": "Validation error",
  "details": [
    "string"
  ]
}

Response 401

Unauthorized – missing or invalid authentication

{
  "status": 401,
  "timestamp": "2025-12-03T13:20:31.664Z",
  "message": "Unauthorized",
  "details": [
    "string"
  ]
}

Response 500

Internal Server Error – unexpected server error

{
  "status": 500,
  "timestamp": "2025-12-03T13:20:31.664Z",
  "message": "Internal Server Error",
  "details": [
    "string"
  ]
}

Definitions

Check

A check retrieved from POS

Name Type Description
posRef* string Unique identifier for the check within a given location.
orderNumber* string Human-readable order number displayed to staff or customers.
tableName string Name or number of the table associated with the check.
guestCount integer Number of guests associated with the check.
status* string Current lifecycle status of the check. Possible values:
  • OPEN
openedAt* string Timestamp of when the check was opened.
ownedByEmployeeRef* string The employee reference responsible for this check.
ownedByEmployee* string The employee name responsible for this check.
subtotal* integer Subtotal of the check, in cents, excluding taxes, gratuity, and fees
dualPricing object Breakdown of pricing if Dual Pricing is in effect.
supplementalFee object Additional fee (e.g., service fee or surcharge) added to the check.
taxes* integer Total tax amount applied to the check, in cents.
otherTaxes* integer Additional or non-standard taxes applied to the check, in cents.
taxList array Itemized list of all applied taxes on the check.
hiddenTaxList array Itemized list of hidden taxes (e.g., embedded taxes) applied to the check.
gratuity* integer Gratuity or tip amount applied to the check, in cents.
total* integer Total amount of the check including all charges, in cents.
paymentAmountDue* integer Remaining amount to be paid for the check, in cents.
paymentAmountPaid* integer Amount already paid towards this check, in cents
isLocked* boolean If true, the check is locked and cannot be paid or modified.
items* array -

Dual Pricing

Breakdown of pricing if Dual Pricing is in effect.

Name Type Description
cashTotal* integer Total check amount when paid in cash, in cents.
cashAmountDue* integer Remaining amount due if paying with cash, in cents.

Supplemental Fee

Additional fee (e.g., service fee or surcharge) added to the check.

Name Type Description
name* string Supplemental fee name.
amount* integer Supplemental fee amount in cents.

Tax

Name Type Description
name string Name of the tax.
amount integer Amount of this specific tax, in cents.

Hidden Tax

Name Type Description
name string Name of the hidden tax.
amount integer Amount of the hidden tax, in cents.

Item

List of items included in this check.

Name Type Description
posRef string Unique identifier for the item within the location.
name string Display name of the item.
quantity number Number of units sold for this item.
modifiersAsText string Comma-separated list of modifiers applied to the item.
price integer Total price of the item, including modifiers, in cents.

results matching ""

    No results matching ""