Integrating Payment Bridge API
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:
- External System sends a Poynt Cloud Message with a payment request containing business id, store id and terminal id of the merchant
- Poynt Cloud authorizes the caller and forwards the message to the corresponding merchant terminal
- Poynt Payment Bridge receives the incoming message and starts the payment flow on the device.
Prerequites:
- Create a developer account and activate your developer terminal. (Note: if you don’t have a developer unit you can use emulator)
- Generate API credentials (i.e. appId and private key) by creating an app. Make sure it has “Cloud Messages” WRITE permission
- Use “Merchant Login Url” of your app to Authorize one of your test merchants
Payment Bridge Message Flow
Request Message Format
COMMON PARAMETERS FOR ALL MESSAGES
- storeId, businessId and deviceId determine which terminal receives the request
- ttl If the Poynt server was unable to deliver the message to the terminal, after TTL (in seconds) is reached the request will be discarded
- data contains payment request options
COMMON “data” PARAMETERS
- callbackUrl where you will receive a callback (HTTP POST) with Payment object. Payment objects acts as the container for transaction response. If the transaction only had 1 tender, the Payment object will have a list with a single Transaction object; in case of a split tender it will contain the list of 2 or ore transactions.
- custom-http-header: optional custom header name and value that will be set by Poynt in the callback HTTP request (e.g. you can use this to pass an authorization token)
Sale
“data” PARAMETERS
- payment serialized payment object. The payment object contains options to configure the payment session. For the list of supported options please refer to this article.
Refund
“data” PARAMETERS
- referenceId unique id returned in the postback response
- transactionId id of the SALE or CAPTURE to refund
- action should be set to “refund”
Callback
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):
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:
FAQ
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:
To reconnect you can double tap on the clock on the launcher:
After that you can confirm that the connection has been re-established:
