Deep Link API
Please note that this API is only available for PhonePOS APP, not for PhonePOS SDK integrators.
To accommodate a wide variety of use cases we also support the triggering of transactions via our Deep Link API from a website
that is opened on the device that has PhonePOS installed.
To use this API PhonePOS has to be personalised and actively enabled (deepLinkApiEnabled = true) via the
Configuration API (recommended) or the low-level Personalisation API.
Please note the Deep Link API can not be used to personalise the terminal.
DeepLink API needs to be activated during the terminal Personalisation process. Otherwise, the feature will be blocked and no transaction will be possible. In case if you are using PhonePOS API please make sure you send activation of deeplink in PersoOptions. PersoOptions.deepLinkApiEnabled = true.
Overview
To enable our integrators the triggering of Transactions from Websites via the Deep Link API PhonePOS does register a deep link intent filter for incoming requests. Instead of the regular "https" scheme that is used for websites on the internet, we define a local "phonepos-api" scheme. Android will redirect all requests automatically to PhonePOS when a link with this scheme is called. PhonePOS will then perform the transaction and return the result back to the specified redirectUrl.
Making a transaction
We present you an example written in react here. You might want to adjust the approach based on the technology you intent to use. Nevertheless, the Deep Link API will work in a wide variety of approaches.
let paymentLink = `phonepos-api://transaction-api/transaction?data=${getPaymentDataJson()}&redirectUrl=${window.location.origin}`
"redirectUrl": An address where you want to receive the result of the payment. (e.g. "www.rubean.com")
"getPaymentDataJson": Json data containing all necessary information about the payment, please see the full json below:
const getPaymentDataJson = () => {
const additionalHostData = { // used only for reference refunds, otherwise please exclude
refNumber: // reference number of the payment
}
const paymentJson = {
transactionType: //one of the following { "PAYMENT", "REVERSAL", "REFUND"} ,
money: {
amount: // amount to pay
currency: // currency for the payment
},
tip:{ // please ignore if you do NOT support tip
amount: // tip amount, (tip is already included in the final amount)
currency: // currency for the tip
},
additionalHostData: `${JSON.stringify(additionalHostData, null, 2)}`, // additional host data is passed as stringified json
language: selectedLanguage // language to do the transaction on
}
return JSON.stringify(paymentJson, null, 2)
}
After specifying all the parameters you can open the link and our application will be opened and merchant will be able to make the payment.
window.location.href = paymentLink
When the payment process is finished, PhonePOS will open the "redirectUrl" passed to the app and will add parameter "result" with the result of the payment. The output looks like this:
https://your-redirect-url?result=eyJ0cmFuc2FjdGlvblJlc3VsdCI6eyJhY3F1aXJlcklkIjoiQ0NRIiwiYWN0aW9uQ29kZSI6IjYwMSIsImFtb3VudCI6eyJjdXJyZW5jeSI6IkVVUiIsInZhbHVlIjoxMS4wMH0sImFuc3dlckNvZGUiOiI2MDEiLCJhdXRob3Jpc2F0aW9uVHlwZSI6Ik9ubGluZSIsImNhcmQiOnsiY2FyZCI6Ik9USFIiLCJwYW5IYXNoIjoiIn0sInJlcXVlc3RJZCI6IjI1MzQ0OTEyMCIsInJldHVybkNvZGUiOiI2MDEiLCJ0aW1lc3RhbXAiOiIyMDI1LTAxLTAyVDE1OjE5OjI1LjAwMCswMTowMCIsInRyeFJlZmVyZW5jZU51bWJlciI6IiIsImNhcmRDaXJjdWl0cyI6W10sIm9hbVNlcnZlckFwcGxpY2F0aW9ucyI6W10sIm9wZW5QcmVBdXRob3Jpc2F0aW9ucyI6W10sInN0YXRlIjoiRkFJTFVSRSIsInRlcm1pbmFsSWQiOiJDQ1FBTU0wMCIsInRyYW5zYWN0aW9uT3ZlcnZpZXciOnsic2hpZnROdW1iZXIiOjB9fSwidHJhbnNhY3Rpb25TdGF0dXMiOiJGQUlMVVJFIn0=
Recover last payment
If you receive "UNKNOWN" as a transaction result from a transaction, you need to do the payment recovery operation, to ensure the state of last operation. To trigger a recovery operation please call "phonepos-api://transaction-api/recovery" and pass "redirectUrl" where you will receive the response.
let paymentLink = `phonepos-api://transaction-api/recovery?redirectUrl=${window.location.origin}`
window.location.href = paymentLink
Parse Result
The result will be encoded as a base64/us-ascii/Url-safe string.
The Result json:
{
"transactionResult":{},
"customerReceipt":{},
"merchantReceipt":{},
"transactionStatus":{}
}
Period closing
For closing period only redirect url is needed to be sent.
let paymentLink = `phonepos-api://transaction-api/period-closing?redirectUrl=${window.location.origin}`
window.location.href = paymentLink
After finishing closing the period, you will receive a json object. In the json object "transactionStatus" will be present which will represent if the closing was successful or not. In case of successful closing of the period, please review the schema below for more information about the data received.
JSON schema of period closing
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title" : "receiptCutover",
"type": "object",
"properties": {
"receiptMode": {
"enum": ["MERCHANT"],
"description": "Cutover receipts are just for the merchant"
},
"transactionId": {
"type": "string",
"description": "Unique number for the cutover transaction"
},
"merchantHeaders": {
"type": "array",
"items": { "type": "string" },
"maxItems": 5,
"description": "This data is configurable per merchant and is typically used to hold the merchant address information. The encoding is UTF-8"
},
"minorunits": {
"type": "string",
"description": "Number of amount digits. For 1€ represented as 100 the minorunits would be '2'. The value should be compliant with ISO 4217"
},
"currency": {
"type": "string",
"description": "The ISO 3-letter currency code according to ISO 4217"
},
"currencyNumeric": {
"type": "string",
"description": "The ISO numeric currency code according to ISO 4217"
},
"date": {
"type": "string",
"description": "Local date of this cutover in the terminals timezone using format yyyy-MM-dd"
},
"time": {
"type": "string",
"description": "Local time of this cutover in the terminals timezone using format HH:mm"
},
"tid": {
"type": "string",
"description": "Terminal id which is sent to the acquirer"
},
"internalTid": {
"type": "string",
"description": "Internal unique terminal id"
},
"receiptNumberFrom": {
"type": "string",
"description": "First receipt number which is part of the cutover period"
},
"receiptNumberTo": {
"type": "string",
"description": "Last receipt number which is part of the cutover period"
},
"traceNumber": {
"type": "string",
"description": "A number increased with every transaction for a specific terminal. This number is related to the acquirer protocol"
},
"answerCode": {
"type": "string",
"description": "Result of the cutover transaction, '00' for successful transactions"
},
"totals": {
"type": "array",
"items": { "type": "object" },
"required": [ "cardBrand", "count", "sum" ],
"properties": {
"cardBrand": {
"type": "string",
"description": "Card brand for which amounts are accumulated"
},
"count": {
"type": "string",
"description": "Number of transactions for this brand"
},
"sum": {
"type": "string",
"description": "Aggregated transaction amount for this brand"
}
},
"description": "Aggregation of transactions within this cutover period"
}
},
"required": [
"receiptMode",
"transactionId",
"merchantHeaders",
"minorunits",
"currency",
"currencyNumeric",
"date",
"time",
"tid",
"internalTid",
"answerCode"
]
}
Transaction Status
In the json result the field "transactionStatus" is a json object containing "status" and "failureReason" enum indicating final result of the transaction. The "status" enum contains the information about the outcome of the payment. Please take a look below:
| Name | Description |
|---|---|
| FAILURE | There are several cases why transaction fan fail. Please check the reason inside this object to identify the problem. |
| SUCCESS | Transaction went thought successfully and the card was deducted the specified amount. |
| UNKNOWN | Transaction result is unknown, and you need to recover payment to be able to get the result of last transaction. |
In case of "transactionStatus" is FAILURE, you can check "failureReason" inside the json object. There are several reasons why transaction can be failed, please check out the following explanations:
| Name | How to proceed |
|---|---|
| ANOTHER_OPERATION_IN_PROGRESS | Indicating that PhonePOS is processing another operation and until the one is finished any further actions will be blocked. |
| TERMINAL_NOT_OPERATIONAL | Indicating that PhonePOS is blocked and payments are NOT possible. Please contact to PhonePOS customer support in this scenario. |
| RECOVERY_REQUIRED | The last transaction failed with status UNKNOWN. It should be recovered before proceeding to the next transaction |
| INCORRECT_PAYMENT_DATA | Please double-check if the json sent for making payment has a correct format and if so please contact to PhonePOS support team. |
| FEATURE_DEACTIVATED | Please notify the merchant that DeepLink feature inside PhonePOS app is deactivated. It can only be activated with fresh personalisation process. |
| NONE | This indicates that the terminal itself is operational but the failure happened during the process of payment/recovery. Please check the "transactionResult" for further analyses. |
In case of SUCCESS or FAILURE with failureReason = NONE you can extract information from "transactionResult" and receipts:
"transactionResult":{},
"customerReceipt":{},
"merchantReceipt":{},
The json fields above contain information about how to parse and extract detailed information out the result.