Note: While this API is currently availalbe at no charge, Poynt reserves the right to introduce an API usage fee in the future.


Payment Bridge API provides a way for external systems (e.g. web-based point-of-sale systems) to start a transaction flow on Poynt Terminal using Poynt cloud APIs.

Here is how it works:

  1. External System sends a Poynt Cloud Message with a payment request containing business id, store id and terminal id of the merchant
  2. Poynt Cloud authorizes the caller and forwards the message to the corresponding merchant terminal
  3. Poynt Payment Bridge receives the incoming message and starts the payment flow on the device.


  1. Create a developer account and activate your developer terminal. (Note: if you don’t have a developer unit you can use emulator)
  2. Generate API credentials (i.e. appId and private key) by creating an app. Make sure it has “Cloud Messages” WRITE permission
  3. Use “Merchant Login Url” of your app to Authorize one of your test merchants

Payment Bridge Message Flow


Request Message Format









Callback allows the external system to get notified when the payment transaction requested is processed. The terminal will use the callback url provided in the request to send the response via HTTP POST:

{"referenceId”:”<your-reference-id>","status":”CANCELED or PROCESSED”, “transactions”:[{<processed-transaction>}]}

Example of a canceled payment:

Example response for a processed transaction (could be either success/approval or failure/decline):

POSTBACK RETRY LOGIC The terminal waits 3 seconds to get HTTP 200 from the postback listener. If your listener fails to repond within that timeframe the terminal will attempt to re-deliver 5 and 10 seconds later.


IMPORTANT! Since the postback payload is a serialized version of the Payment object and from time to time we may add new parameters, it is important that you do not use strict validation while parsing the payload, which means ignoring unknown parameters.


Terminal Connectivity

Terminals maintain a persistent connection to the Poynt cloud but from time to time the connection may get dropped. By default, terminals send a ping message to check if the connection is active every 5 minutes. However you should set a more aggressive connectivity profile to ensure that the connection does not get dropped by sending the following message to the terminal:

The message does not use a callback url as it does not require a postback. If you are testing this on a developer terminal, you can confirm that the profile has been applied by checking the logcat:


Q: The body in the callback request is gzip compressed. How can I disable the compression?
A: Go to Developer Preferences > Poynt API. Toggle the switch for ENABLE HTTP COMPRESSION and tap SAVE. Check Dev FAQ page for instructions on accessing Developer Preferences.

Q: My request fails with HTTP 401
A: This indicates that your appId does not have permission to send cloud messages to the merchant’s terminals. Please refer to Step 3 of Prerequires.

Q: My API request returns HTTP 202 however the payment fragment does not come up on the terminal
A: First check the logcat to see if the message even makes it to the terminal adb logcat -v time | grep -i pcm. If you don’t see the messages being logged it’s likely because the connection between the terminal and the cloud was terminated. You can verify that by checking Poynt Settings:
Live Stream Disconnected
To reconnect you can double tap on the clock on the launcher:
Reset live stream connection
After that you can confirm that the connection has been re-established:
Live Stream Connected

Note: Please note that if you are using an emulator you need to check that the co.poynt.cloudmessaging package has been installed.