Skip to main content

Pay at Counter

info

This page is about the new Dojo-only Pay at Counter Websockets API. If you're unsure which API is best for your integration, contact your Partnership Development Manager (PDM).

The Pay at Counter (PAC) API is designed specifically for use in retail shops, bars, hairdressers, cafés, and other businesses that take payments at the sales counter. The new, Dojo-only PAC API is based on:

Upgrading your implementation​

The table below highlights the key functionality and messaging changes when upgrading from V2 to V3 of the PAC Websockets API. The other changes are:

  • Authentication uses standard basic auth, rather than auth parameters in the query string.
  • A new epos-id header has been added to help resume in progress transactions after disconnections.
V1 PAC functionalityV2 PAC functionality
Create a standard sale request by sending a PerformTransaction using the sale method.Create a standard sale request by sending a CreatePayment request with the captureMode set to AUTO.
You cannot create a pre-authorized payment.Create a pre-authorized payment request by sending a CreatePayment request with the captureMode set to MANUAL.
You cannot manually capture a payment.Capture a payment manually by sending a CapturePayment request. This is only possible where the captureMode on the payment was set to MANUAL.
You cannot update the amount of a payment.Update the amount held for a payment by sending an UpdatePayment request. This is only possible where the captureMode on the payment was set to MANUAL, and the payment hasn't yet been captured.
Create a refund request by sending a PerformTransaction request using the refund method.Create a refund request by sending a CreateRefund request.
Cancel a payment by sending a CancelTransaction request.Cancel a payment by sending a CancelPayment request.
Cancel a refund by sending a CancelTransaction request.Cancel a refund by sending a CancelPayment request.
Respond to a signatureVerificationRequest using the tid to match the request to the payment or refund.Respond to a signatureVerificationRequest using the paymentId to match the request to the payment or refund.
Record a payment or refund on your EPOS on receiving a response from the PerformTransaction method.Record a payment or refund on your EPOS on receiving a RecordPayment or RecordRefund message using the paymentId to match the request to the payment or refund.

The new CreatePayment and CreateRefund methods share a lot of fields with the previous PerformTransaction, but do have some differences. The most significant change is the addition of an EPOS-generated PaymentId. These fields are used to correlate actions and updates with the original request from your EPOS.

Messaging​

The API uses the JSON RPC 2.0 specification as the protocol for its messaging. This remains unchanged from the previous version.

Connecting with WebSockets​

The connection URI takes the format:

wss://api.dojo.tech/ws/v2/pac/epos

With current development being done against our staging environment here using:

wss://staging-api.dojo.dev/ws/v2/pac/epos

Authenticating​

Inject your pre-existing AccountName and an APIKey into the WebSocket connection header. As username and password respectively. These values are encoded in base64 using the Basic HTTP authentication scheme (BasicAuth).

Using the epos-id header​

The epos-id is a new, mandatory header. The header allows you to ensure:

  • If you disconnect during a transaction, you can reconnect and your EPOS will be recognized. You will receive any pending RecordPayment requests.
  • A new connection from the same account with an identical epos-id will disconnect any other connections associated with that ID.
  • You may have multiple EPOSs connected for the same account, provided they all have unique epos-id headers.

The epos-id header should be unique for each EPOS.

Other connection headers​

  • Authorization:This is used to authenticate your requests to the API. The authToken is formed from base64 encoding your accountName (first string in the URL for existing integrations) and your apiKey. The two values should be seperated by a colon with no spaces e.g. base64("abcdef0000000:7d4773f2-367f-406c-881a-b4cb854971f3"). The values will be provided by Dojo.
  • software-house-id: This is a mandatory field showing the EPOS company whose software is generating the request. This value should not be configurable as it will remain the same for all customers using particular EPOS software.
  • reseller-id: This identifies the reseller of the EPOS. This may be the same as the software-house-id if they are also the seller.

API reference Discover the full WebSockets API reference for the Dojo-only PAC API.

Changelog Detailed information on recent changes to the API.

Pre-authorization Learn how to use the API to reserve funds in a cardholder's account.

Support Our support team is always happy to help with any questions you have.

Last updated on