Custom URL

To initiate an Express client transaction from your application, you have to open a URL with the following format: handpoint://express/v1/?data=<url_encoded_data>

• For web apps, you can open this URL just as you would any other URL on a webpage.
• For native iOS apps, you use the openURL: method of UIApplication. The query parameter in the URL, data, is a percent-encoded JSON object that contains information the Express client needs to process the transaction request.

For example, a valid unencoded JSON object looks like this (replace CLIENT_ID with your application's ID, and SHARED_SECRET_KEY with the device activation key you received from the Handpoint support team): If you're opening this URL from a native app, you can use your own app custom scheme as a callback: "myapp-url-scheme://payment-complete"

{
    "action": {
        "type": "sale",
        "parameters": {
            "amount": 1500,
            "currency": "USD"
        },
        "extraParameters": {
            "your custom field" : "custom value"
        }
    },
    "client": {
        "clientId": "CLIENT_ID",
        "ssk": "SHARED_SECRET_KEY",
        "autoReturn": true,
        "autoReturnTimeout": 0
    },
    "callbackUrl": "http://yourbackend.com/payment-result"
}

If you're developing a web application, this Javascript sample demonstrates encoding a Register API URL and directing the merchant's browser to open it:

<script>
var dataParameter = {
    "action": {
        "type": "sale",
        "parameters": {
            "amount": 1500,
            "currency": "USD"
        },
        "extraParameters": {
            "your custom field" : "custom value"
        }
    },
    "client": {
        "clientId": "CLIENT_ID",
        "ssk": "SHARED_SECRET_KEY",
        "autoReturn": true,
        "autoReturnTimeout": 0
    },
    "callbackUrl": "http://yourbackend.com/payment-result"
};
window.location = "handpoint://express/v1/?data=" + encodeURIComponent(JSON.stringify(dataParameter));
</script>