Mobile Payments

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

Payment Flow

The following diagram illustrates the simplified mobile payment flow:

The mobile payment flow consists of these steps:

1. Retrieve Check - The third party sends a request to retrieve a check by order number
2. Check List Response - The third party receives a list of checks matching the provided order number
3. Execute Payment - The third 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. Payment Success - The third party receives payment data upon a successful sale
5. Register Payment - The third party registers the payment data for the specific check
6. Confirm Registration - The third party receives the payment identifier and the remaining amount due, if applicable

Retrieve checks for a location

curl -X GET \
  'https://conecto-api.shift4payments.com/api/pos/v2/244/checks?filter[orderNumber]=ORDER-123' \
  -H 'x-access-key: YOUR_CLIENT_ID' \
  -H 'x-timestamp: 1709251200' \
  -H 'x-signature: YOUR_SIGNATURE'

{
  "results": [
    {
      "guid": "check_abc123",
      "posRef": "CHK-1001",
      "orderNumber": "ORDER-123",
      "tableName": "Table 5",
      "employeeName": "John Doe",
      "totalAmount": 4850,
      "totalPaid": 0,
      "totalDue": 4850,
      "status": "open",
      "createdAt": "2024-03-15T18:30:00Z",
      "items": [
        {
          "name": "Burger",
          "quantity": 2,
          "unitPrice": 1299,
          "totalPrice": 2598
        },
        {
          "name": "Fries",
          "quantity": 2,
          "unitPrice": 499,
          "totalPrice": 998
        }
      ],
      "taxes": [
        {
          "name": "Sales Tax",
          "amount": 254
        }
      ]
    }
  ],
  "meta": {
    "total": 1,
    "offset": 0,
    "limit": 100
  }
}

Retrieve a check for a location

curl -X GET \
  'https://conecto-api.shift4payments.com/api/pos/v2/244/checks/CHK-1001' \
  -H 'x-access-key: YOUR_CLIENT_ID' \
  -H 'x-timestamp: 1709251200' \
  -H 'x-signature: YOUR_SIGNATURE'

{
  "guid": "check_abc123",
  "posRef": "CHK-1001",
  "orderNumber": "ORDER-123",
  "tableName": "Table 5",
  "employeeName": "John Doe",
  "employeeRef": "emp_123",
  "totalAmount": 4850,
  "totalItems": 3596,
  "totalTax": 254,
  "totalPaid": 0,
  "totalDue": 4850,
  "status": "open",
  "guestCount": 2,
  "createdAt": "2024-03-15T18:30:00Z",
  "updatedAt": "2024-03-15T18:35:00Z",
  "items": [
    {
      "guid": "item_001",
      "posRef": "item_burger",
      "name": "Burger",
      "quantity": 2,
      "unitPrice": 1299,
      "totalPrice": 2598,
      "modifiers": [
        {
          "name": "Extra Cheese",
          "quantity": 2,
          "unitPrice": 100,
          "totalPrice": 200
        }
      ]
    },
    {
      "guid": "item_002",
      "posRef": "item_fries",
      "name": "Fries",
      "quantity": 2,
      "unitPrice": 499,
      "totalPrice": 998
    }
  ],
  "payments": [],
  "taxes": [
    {
      "name": "Sales Tax",
      "rate": {
        "type": "percent",
        "percent": 82500
      },
      "amount": 254
    }
  ]
}

Pay for a specific check

curl -X POST \
  'https://conecto-api.shift4payments.com/api/pos/v2/244/checks/CHK-1001/pay' \
  -H 'Content-Type: application/json' \
  -H 'x-access-key: YOUR_CLIENT_ID' \
  -H 'x-timestamp: 1709251200' \
  -H 'x-signature: YOUR_SIGNATURE' \
  -d '{
    "amount": 4850,
    "transactionId": "txn_abc123xyz",
    "paymentMethod": "credit_card",
    "last4": "4242",
    "cardBrand": "visa",
    "tipAmount": 750
  }'

{
  "paymentId": "pay_xyz789",
  "checkGuid": "check_abc123",
  "posRef": "CHK-1001",
  "amount": 4850,
  "tipAmount": 750,
  "totalPaid": 5600,
  "remainingDue": 0,
  "status": "paid",
  "processedAt": "2024-03-15T19:45:00Z"
}

Check Object

The Check object represents a POS check (also known as a ticket) and contains comprehensive information about the transaction.

Check Item

Check Payment

Best practices

Query by order number

When retrieving checks for mobile payment, always filter by order number to find the specific check associated with the customer's order. This avoids confusion with other open checks at the location.

Verify amounts

Before processing a payment, verify the totalDue amount on the check matches what the customer expects to pay. This prevents overpayment or underpayment issues.

Handle partial payments

The API supports partial payments. Check the remainingDue field in the response to determine if additional payment is needed.

Process payments atomically

1. First, process the payment through the i4go gateway
2. Only if successful, register the payment with the check using the /pay endpoint
3. If registration fails, consider reversing the gateway transaction

Currency handling

All amounts are in US cents:

• Display: Divide by 100 (4850 cents = $48.50)
• Always use integer arithmetic to avoid rounding errors

Error handling

Implement proper error handling:

• Check not found (404): Order number may be incorrect or check already closed
• Payment failed (400): Check amount mismatch or validation error
• Server error (500): Retry with exponential backoff

Security

• Never expose access tokens in client-side code
• Store transaction IDs securely for reconciliation
• Implement request timeouts to prevent hanging connections
• Always use HTTPS for all API communications