Basic Integration with the STEP platform as a PoS or other Transaction Provider

View Categories

Basic Integration with the STEP platform as a PoS or other Transaction Provider

13 min read

How to send a transaction to WPS via the API. #

This page shows the most basic form of a transaction, and uses three endpoints, prepare_transactionprepare_payments, and finalize_payments. As always, full documentation on available fields and the ability to test queries can be found at https://stagingapi.watchmanpaymentsystems.com/docs/#/?urls.primaryName=Cart%20Transaction#/. You can test these endpoints using the data found here.

Note: The most important thing to remember is that you will send the first packet to WPS and then keep the response. Modify that response by adding to it (and sometimes making changes, though that is rare) and then send it back in your next call. You should never rebuild the packet from scratch. You are welcome to ignore fields that you don’t need, but they must be included when you make your next call. Disappearing fields – even if you don’t have a use for them – may create errors and will, at some point, cause issues with the calculations or running rules on the WPS side. If fields are disappearing, or changing when they shouldn’t, our engineering team will ask you to solve that issue before we can help you with other questions or concerns.

Each transaction created via STEP follows the same general workflow:

  1. A request or requests are sent to the prepare_transaction endpoint. The response may include information that has been calculated, such as any adjustments that have been automatically configured to apply using the promo system or tax rates, as well as the total balance due. This may often be called multiple times as the cart changes – or a single time once you know everything that is in the cart. Jump to the prepare_transaction section here.
  2. Once all of the charge items have been sent to the prepare_transaction endpoint, one or more calls are made to the prepare_payments endpoint. The response will show if the payments have succeeded or failed, and any uncovered charges. You will make one call for each payment type, so in the case of a split payment, multiple calls will be made. Jump to the prepare_payments section here.
  3. Once the transaction is fully covered, that is, there is no remaining balance due, submit to the finalize_payments to complete the transaction. Jump to the finalize_payments section here.

prepare_transaction #

There are numerous fields that can be used when creating a transaction depending on the information available and the relevant fields that need to be captured. While, strictly speaking, the only required field is the price for the item being charged – though most payment types do require saleCategory as well, we recommend including a few other fields in most cases:

  • scancode: A scan code or sku is a user supplied identifier for the item. 
  • description: Description is the item description.
  • quantity: quantity defaults to 1, but if it’s supplied, this allows WPS to calculate the total easily, and group any items that have the same scan code and price together. If there is a case where two items with the same scancode have different prices (not due to a promo), then they would need to be separate charges.
  • unitPrice: Unit Price is a required field in all cases. A positive number here will result in a charge to the customer, while a negative number will result in a refund. See Refund Options for more information.
  • saleCategory: The PoS or other transaction source should send in whatever their customer is used to seeing in their system for a category. This might be a financial reporting code, DCC, or some other product category designation. Please do not map this to a set of categories specifically for WPS. WPS has that capability, internally, and customers rely on the ability to make changes to that mapping for tax modifications and other rules. Many payors, including the MOCK payor attached to the sample keys you can use to test the endpoint, will reject any sale that does not have a saleCategory attached. Sales Categories can be used both for reporting purposes and as part of the promo system. Some users may also tie their sales categories to tax codes, so that tax can be automatically calculated based on the sales category. Some payment methods may be configured to restrict sales based on the saleCategory of the item. For a list of available sales categories that work with the MOCK keys, see the MOCK Categories page.

A Note on Tax

There are a number of ways that WPS can help you calculate your tax. You can either rely on our TaxJar integration, or you can provide a variety of overrides.  If you are not using Sales Categories (or do not use Sales Categories that have been mapped to tax codes), you will need to provide a tax override in the transaction block. See Tax Options under Transactions for more information. Please note that STEP does not calculate taxes – although we may notify your system of exemptions and partial exemptions. We use your tax info from the transaction block or TaxJar, exclusively.

In the sample below, you can see two items are being sent to the prepare_transaction endpoint

prepare_transaction Request

{
  "transaction": {
    "charges": [
      {
        "scancode": "9780590353403",
        "description": "Harry Potter And The Sorcerers Stone",
        "quantity": 1,
        "unitPrice": 19.89,
        "saleCategory": "BOOKS"
      },
      {
        "scancode": "9780385365925",
        "description": "The Ultimate Hitchhikers Guide to the Galaxy",
        "quantity": 1,
        "unitPrice": 39.95,
        "saleCategory": "BOOKS"
      }
    ]
  }
}

prepare_transaction Response

{
  "timestamp": "2019-05-03T19:20:44.366Z",
  "transactionId": "b6235da6-13d3-48a6-8f89-cb30c56c0100",
  "transaction": {
    "charges": [
      {
        "uid": "59457793-4f27-4e45-8a7e-2a088b7cc7cf",
        "description": "Harry Potter And The Sorcerers Stone",
        "saleCategory": "BOOKS",
        "quantity": 1,
        "unitPrice": 19.89,
        "scancode": "9780590353403",
        "taxExempt": false,
        "taxRate": 0.062,
        "overrideTax": false,
        "signature": "cd6b4707e50a4173a007de77b47ff0cc",
        "remainingAmount": 19.89,
        "remainingTax": 1.23,
        "taxAmount": 1.23,
        "subTotalAmount": 19.89,
        "adjustments": []
      },
      {
        "uid": "0c0f5f82-7dc6-4ff9-b61d-d7e04a9a158e",
        "description": "The Ultimate Hitchhikers Guide to the Galaxy",
        "saleCategory": "BOOKS",
        "quantity": 1,
        "unitPrice": 39.95,
        "scancode": "9780385365925",
        "taxExempt": false,
        "taxRate": 0.062,
        "overrideTax": false,
        "signature": "6501bffedfd64a7a93761ed1b82f1c15",
        "remainingAmount": 39.95,
        "remainingTax": 2.48,
        "taxAmount": 2.48,
        "subTotalAmount": 39.95,
        "adjustments": []
      }
    ],
    "adjustments": []
  },
  "uncoveredCharges": []
}

prepare_payments #

Once you have made as many calls as necessary to prepare_transaction, you will call prepare_payments to add payments to the transaction. You can make multiple calls to prepare_payments. For example, you may need to make multiple calls if a payment is declined, or if you have multiple payment types and want to authorize each before adding the next, as you would if you were splitting between two credit cards.

The information required for a payment varies somewhat depending on the payment type and situation:

  • apiKey: required. This field is always required. When you sign up with WPS, you will be provided individual keys for each payment type used on your account. This must be a key for a payment method authorized on the same account as the current logged-in user, which is important if you have multiple store locations.
  • account or prevAuthId: One of these two fields is required.
    • account: The account field will vary depending on what payment method is used by the API key. For example, it may be the student ID for bursar payments, the folio id for charge-to-room, the card number for gift cards, the account id for in-store credit or campus card, etc. This is the most common field type for a basic transaction.
    • prevAuthId: This field is used in two scenarios:
      1.  When a transaction is being refunded using the original payment type, the prevAuthId field links the refund payment to the original payment type and transaction. See Refunds for more information.
      2. In place of ‘account’ for recharge transactions, where the customer is being charged against an account on file. For example, this is used when a credit card kept as collateral and is the authId returned when completing the previous transaction.
  • amount: Amount is not a required field if there is only one payment on the transaction. This will default to the total amount of the transaction. See Payment Options for more information on advanced cases, such as split payments and overages.

In the example below, you can see that a payment block has been added to the transaction from prepare_transaction above and sent into prepare_payments. Amount has not been included, so WPS will default to covering the entire transaction. In the response, you can see that the payment was authorized for the full amount of the transaction (‘uncoveredCharges’ is empty), so the transaction can successfully be sent to finalize_payments. Additionally, you can see that the response has included the authId, which would be used in the prevAuthId field for a recharge or refund to the original payment method (See Payment Options for more information).

prepare_payments Request

{
  "timestamp": "2019-05-03T19:20:44.366Z",
  "transactionId": "b6235da6-13d3-48a6-8f89-cb30c56c0100",
  "transaction": {
    "charges": [
      {
        "uid": "59457793-4f27-4e45-8a7e-2a088b7cc7cf",
        "description": "Harry Potter And The Sorcerers Stone",
        "saleCategory": "BOOKS",
        "quantity": 1,
        "unitPrice": 19.89,
        "scancode": "9780590353403",
        "taxExempt": false,
        "taxRate": 0.062,
        "overrideTax": false,
        "signature": "cd6b4707e50a4173a007de77b47ff0cc",
        "remainingAmount": 19.89,
        "remainingTax": 1.23,
        "taxAmount": 1.23,
        "subTotalAmount": 19.89,
        "adjustments": []
      },
      {
        "uid": "0c0f5f82-7dc6-4ff9-b61d-d7e04a9a158e",
        "description": "The Ultimate Hitchhikers Guide to the Galaxy",
        "saleCategory": "BOOKS",
        "quantity": 1,
        "unitPrice": 39.95,
        "scancode": "9780385365925",
        "taxExempt": false,
        "taxRate": 0.062,
        "overrideTax": false,
        "signature": "6501bffedfd64a7a93761ed1b82f1c15",
        "remainingAmount": 39.95,
        "remainingTax": 2.48,
        "taxAmount": 2.48,
        "subTotalAmount": 39.95,
        "adjustments": []
      }
    ],
    "adjustments": []
  },
  "uncoveredCharges": [],
  "payments": [
    {
      "apiKey": "d4224678-da27-4aba-98ae-b328ccbe1c26",
      "account": "45678901"
    }
  ]
}

prepare_payments Response

{
  "timestamp": "2019-05-03T19:20:44.366Z",
  "transactionId": "b6235da6-13d3-48a6-8f89-cb30c56c0100",
  "transaction": {
    "charges": [
      {
        "uid": "59457793-4f27-4e45-8a7e-2a088b7cc7cf",
        "description": "Harry Potter And The Sorcerers Stone",
        "saleCategory": "BOOKS",
        "quantity": 1,
        "unitPrice": 19.89,
        "scancode": "9780590353403",
        "taxExempt": false,
        "taxRate": 0.062,
        "overrideTax": false,
        "signature": "cd6b4707e50a4173a007de77b47ff0cc",
        "remainingAmount": 19.89,
        "remainingTax": 1.23,
        "taxAmount": 1.23,
        "subTotalAmount": 19.89,
        "adjustments": []
      },
      {
        "uid": "0c0f5f82-7dc6-4ff9-b61d-d7e04a9a158e",
        "description": "The Ultimate Hitchhikers Guide to the Galaxy",
        "saleCategory": "BOOKS",
        "quantity": 1,
        "unitPrice": 39.95,
        "scancode": "9780385365925",
        "taxExempt": false,
        "taxRate": 0.062,
        "overrideTax": false,
        "signature": "6501bffedfd64a7a93761ed1b82f1c15",
        "remainingAmount": 39.95,
        "remainingTax": 2.48,
        "taxAmount": 2.48,
        "subTotalAmount": 39.95,
        "adjustments": []
      }
    ],
    "adjustments": []
  },
  "totalAttemptedAmount": 63.55,
  "totalCoveredAmount": 59.84,
  "totalCoveredTaxAmount": 3.71,
  "totalOverage": 0,
  "payments": [
    {
      "apiKey": "d4224678-da27-4aba-98ae-b328ccbe1c26",
      "account": "45678901",
      "authId": "MOCK:20190503075655:b6235da6-13d3-48a6-8f89-cb30c56c0100",
      "forcedCapture": false,
      "voidPayment": false,
      "mustAllowRecharge": false,
      "storableRechargeToken": "MOCK:20190503075655:b6235da6-13d3-48a6-8f89-cb30c56c0100",
      "totalRequestedAmount": 63.55,
      "totalAuthorizedAmount": 63.55,
      "totalCoveredAmount": 63.55,
      "payableOverage": 0,
      "authorizedCharges": [
        {
          "uid": "59457793-4f27-4e45-8a7e-2a088b7cc7cf",
          "description": "Harry Potter And The Sorcerers Stone",
          "saleCategory": "BOOKS",
          "quantity": 1,
          "unitPrice": 19.89,
          "scancode": "9780590353403",
          "taxExempt": false,
          "taxRate": 0.062,
          "overrideTax": false,
          "signature": "cd6b4707e50a4173a007de77b47ff0cc",
          "remainingAmount": 19.89,
          "remainingTax": 1.23,
          "result": "COMPLETELY_COVERED",
          "taxResult": "COMPLETELY_COVERED",
          "humanReadableMessage": "Success",
          "coveredAmount": 19.89,
          "coveredTaxAmount": 1.23,
          "taxAmount": 1.23,
          "subTotalAmount": 19.89,
          "adjustments": []
        },
        {
          "uid": "0c0f5f82-7dc6-4ff9-b61d-d7e04a9a158e",
          "description": "The Ultimate Hitchhikers Guide to the Galaxy",
          "saleCategory": "BOOKS",
          "quantity": 1,
          "unitPrice": 39.95,
          "scancode": "9780385365925",
          "taxExempt": false,
          "taxRate": 0.062,
          "overrideTax": false,
          "signature": "6501bffedfd64a7a93761ed1b82f1c15",
          "remainingAmount": 39.95,
          "remainingTax": 2.48,
          "result": "COMPLETELY_COVERED",
          "taxResult": "COMPLETELY_COVERED",
          "humanReadableMessage": "Success",
          "coveredAmount": 39.95,
          "coveredTaxAmount": 2.48,
          "taxAmount": 2.48,
          "subTotalAmount": 39.95,
          "adjustments": []
        }
      ]
    }
  ],
  "uncoveredCharges": []
}

finalize_payments #

Once you have made as many calls as necessary to prepare_transaction, you will call finalize_payments to complete the transaction.

Optional Additional Fields:

  • transactionId: While WPS will always generate a unique ID for the transaction, you can also pass in an optional ‘finalTransactionId’ in the query for the call if you are generating a transaction ID in your point of sale.

In the example below, you can see that the response includes a ‘capturedCharges’ block, along with a ‘SUCCESS’ message. If the charges are not captured for any reason, a reason will also be displayed, as sent by the payment processor.

prepare_payments Request

{
  "timestamp": "2019-05-03T19:20:44.366Z",
  "transactionId": "b6235da6-13d3-48a6-8f89-cb30c56c0100",
  "transaction": {
    "charges": [
      {
        "uid": "59457793-4f27-4e45-8a7e-2a088b7cc7cf",
        "description": "Harry Potter And The Sorcerers Stone",
        "saleCategory": "BOOKS",
        "quantity": 1,
        "unitPrice": 19.89,
        "scancode": "9780590353403",
        "taxExempt": false,
        "taxRate": 0.062,
        "overrideTax": false,
        "signature": "cd6b4707e50a4173a007de77b47ff0cc",
        "remainingAmount": 19.89,
        "remainingTax": 1.23,
        "taxAmount": 1.23,
        "subTotalAmount": 19.89,
        "adjustments": []
      },
      {
        "uid": "0c0f5f82-7dc6-4ff9-b61d-d7e04a9a158e",
        "description": "The Ultimate Hitchhikers Guide to the Galaxy",
        "saleCategory": "BOOKS",
        "quantity": 1,
        "unitPrice": 39.95,
        "scancode": "9780385365925",
        "taxExempt": false,
        "taxRate": 0.062,
        "overrideTax": false,
        "signature": "6501bffedfd64a7a93761ed1b82f1c15",
        "remainingAmount": 39.95,
        "remainingTax": 2.48,
        "taxAmount": 2.48,
        "subTotalAmount": 39.95,
        "adjustments": []
      }
    ],
    "adjustments": []
  },
  "totalAttemptedAmount": 63.55,
  "totalCoveredAmount": 59.84,
  "totalCoveredTaxAmount": 3.71,
  "totalOverage": 0,
  "payments": [
    {
      "apiKey": "d4224678-da27-4aba-98ae-b328ccbe1c26",
      "account": "45678901",
      "authId": "MOCK:20190503075655:b6235da6-13d3-48a6-8f89-cb30c56c0100",
      "forcedCapture": false,
      "voidPayment": false,
      "mustAllowRecharge": false,
      "storableRechargeToken": "MOCK:20190503075655:b6235da6-13d3-48a6-8f89-cb30c56c0100",
      "totalRequestedAmount": 63.55,
      "totalAuthorizedAmount": 63.55,
      "totalCoveredAmount": 63.55,
      "payableOverage": 0,
      "authorizedCharges": [
        {
          "uid": "59457793-4f27-4e45-8a7e-2a088b7cc7cf",
          "description": "Harry Potter And The Sorcerers Stone",
          "saleCategory": "BOOKS",
          "quantity": 1,
          "unitPrice": 19.89,
          "scancode": "9780590353403",
          "taxExempt": false,
          "taxRate": 0.062,
          "overrideTax": false,
          "signature": "cd6b4707e50a4173a007de77b47ff0cc",
          "remainingAmount": 19.89,
          "remainingTax": 1.23,
          "result": "COMPLETELY_COVERED",
          "taxResult": "COMPLETELY_COVERED",
          "humanReadableMessage": "Success",
          "coveredAmount": 19.89,
          "coveredTaxAmount": 1.23,
          "taxAmount": 1.23,
          "subTotalAmount": 19.89,
          "adjustments": []
        },
        {
          "uid": "0c0f5f82-7dc6-4ff9-b61d-d7e04a9a158e",
          "description": "The Ultimate Hitchhikers Guide to the Galaxy",
          "saleCategory": "BOOKS",
          "quantity": 1,
          "unitPrice": 39.95,
          "scancode": "9780385365925",
          "taxExempt": false,
          "taxRate": 0.062,
          "overrideTax": false,
          "signature": "6501bffedfd64a7a93761ed1b82f1c15",
          "remainingAmount": 39.95,
          "remainingTax": 2.48,
          "result": "COMPLETELY_COVERED",
          "taxResult": "COMPLETELY_COVERED",
          "humanReadableMessage": "Success",
          "coveredAmount": 39.95,
          "coveredTaxAmount": 2.48,
          "taxAmount": 2.48,
          "subTotalAmount": 39.95,
          "adjustments": []
        }
      ]
    }
  ],
  "uncoveredCharges": []
}

finalize_payments Response

{
  "timestamp": "2019-05-03T19:20:44.366Z",
  "transactionId": "b6235da6-13d3-48a6-8f89-cb30c56c0100",
  "transaction": {
    "charges": [
      {
        "uid": "59457793-4f27-4e45-8a7e-2a088b7cc7cf",
        "description": "Harry Potter And The Sorcerers Stone",
        "saleCategory": "BOOKS",
        "quantity": 1,
        "unitPrice": 19.89,
        "scancode": "9780590353403",
        "taxExempt": false,
        "taxRate": 0.062,
        "overrideTax": false,
        "signature": "cd6b4707e50a4173a007de77b47ff0cc",
        "remainingAmount": 19.89,
        "remainingTax": 1.23,
        "taxAmount": 1.23,
        "subTotalAmount": 19.89,
        "adjustments": []
      },
      {
        "uid": "0c0f5f82-7dc6-4ff9-b61d-d7e04a9a158e",
        "description": "The Ultimate Hitchhikers Guide to the Galaxy",
        "saleCategory": "BOOKS",
        "quantity": 1,
        "unitPrice": 39.95,
        "scancode": "9780385365925",
        "taxExempt": false,
        "taxRate": 0.062,
        "overrideTax": false,
        "signature": "6501bffedfd64a7a93761ed1b82f1c15",
        "remainingAmount": 39.95,
        "remainingTax": 2.48,
        "taxAmount": 2.48,
        "subTotalAmount": 39.95,
        "adjustments": []
      }
    ],
    "adjustments": []
  },
  "totalAttemptedAmount": 63.55,
  "totalCoveredAmount": 59.84,
  "totalCoveredTaxAmount": 3.71,
  "totalOverage": 0,
  "payments": [
    {
      "apiKey": "d4224678-da27-4aba-98ae-b328ccbe1c26",
      "account": "45678901",
      "authId": "MOCK:20190503075655:b6235da6-13d3-48a6-8f89-cb30c56c0100",
      "forcedCapture": false,
      "voidPayment": false,
      "mustAllowRecharge": false,
      "storableRechargeToken": "MOCK:20190503075655:b6235da6-13d3-48a6-8f89-cb30c56c0100",
      "totalRequestedAmount": 63.55,
      "totalAuthorizedAmount": 63.55,
      "totalCapturedAmount": 63.55,
      "totalCoveredAmount": 63.55,
      "payableOverage": 0,
      "authorizedCharges": [
        {
          "uid": "59457793-4f27-4e45-8a7e-2a088b7cc7cf",
          "description": "Harry Potter And The Sorcerers Stone",
          "saleCategory": "BOOKS",
          "quantity": 1,
          "unitPrice": 19.89,
          "scancode": "9780590353403",
          "taxExempt": false,
          "taxRate": 0.062,
          "overrideTax": false,
          "signature": "cd6b4707e50a4173a007de77b47ff0cc",
          "remainingAmount": 19.89,
          "remainingTax": 1.23,
          "result": "COMPLETELY_COVERED",
          "taxResult": "COMPLETELY_COVERED",
          "humanReadableMessage": "Success",
          "coveredAmount": 19.89,
          "coveredTaxAmount": 1.23,
          "taxAmount": 1.23,
          "subTotalAmount": 19.89,
          "adjustments": []
        },
        {
          "uid": "0c0f5f82-7dc6-4ff9-b61d-d7e04a9a158e",
          "description": "The Ultimate Hitchhikers Guide to the Galaxy",
          "saleCategory": "BOOKS",
          "quantity": 1,
          "unitPrice": 39.95,
          "scancode": "9780385365925",
          "taxExempt": false,
          "taxRate": 0.062,
          "overrideTax": false,
          "signature": "6501bffedfd64a7a93761ed1b82f1c15",
          "remainingAmount": 39.95,
          "remainingTax": 2.48,
          "result": "COMPLETELY_COVERED",
          "taxResult": "COMPLETELY_COVERED",
          "humanReadableMessage": "Success",
          "coveredAmount": 39.95,
          "coveredTaxAmount": 2.48,
          "taxAmount": 2.48,
          "subTotalAmount": 39.95,
          "adjustments": []
        }
      ],
      "capturedCharges": [
        {
          "uid": "59457793-4f27-4e45-8a7e-2a088b7cc7cf",
          "description": "Harry Potter And The Sorcerers Stone",
          "saleCategory": "BOOKS",
          "quantity": 1,
          "unitPrice": 19.89,
          "scancode": "9780590353403",
          "taxExempt": false,
          "taxRate": 0.062,
          "overrideTax": false,
          "signature": "cd6b4707e50a4173a007de77b47ff0cc",
          "remainingAmount": 19.89,
          "remainingTax": 1.23,
          "result": "COMPLETELY_COVERED",
          "taxResult": "COMPLETELY_COVERED",
          "humanReadableMessage": "Success",
          "coveredAmount": 19.89,
          "coveredTaxAmount": 1.23,
          "forcedCapture": false,
          "taxAmount": 1.23,
          "subTotalAmount": 19.89,
          "adjustments": []
        },
        {
          "uid": "0c0f5f82-7dc6-4ff9-b61d-d7e04a9a158e",
          "description": "The Ultimate Hitchhikers Guide to the Galaxy",
          "saleCategory": "BOOKS",
          "quantity": 1,
          "unitPrice": 39.95,
          "scancode": "9780385365925",
          "taxExempt": false,
          "taxRate": 0.062,
          "overrideTax": false,
          "signature": "6501bffedfd64a7a93761ed1b82f1c15",
          "remainingAmount": 39.95,
          "remainingTax": 2.48,
          "result": "COMPLETELY_COVERED",
          "taxResult": "COMPLETELY_COVERED",
          "humanReadableMessage": "Success",
          "coveredAmount": 39.95,
          "coveredTaxAmount": 2.48,
          "forcedCapture": false,
          "taxAmount": 2.48,
          "subTotalAmount": 39.95,
          "adjustments": []
        }
      ]
    }
  ],
  "uncoveredCharges": []
}

Powered by BetterDocs

Leave a Reply

Your email address will not be published. Required fields are marked *