Hosted Payments

Accepting Payments

This is the default operation when building your button or iframe without explicitly defining an operation type e.g data-operation='create.payment'. When a user enters their credit card information, a payment is created for the amount specified.

You can configure either a callback or a redirect URL to handle the payment response. Optionally, you can do nothing at all.

Card Tokenization

This configuration option e.g.data-operation='create.token' is used to tokenize the credit card details entered by a user on the hosted payment form. This operation provides you with greater control over the payment experience. However, you need to download one of Simplify Commerce's SDKs and complete the payment on the server.

A JavaScript callback function needs to be specified to handle the token value. This token can then be used with our API to charge the card.

Data Attributes

The HTML data attributes must be prefixed with data, e.g. data-sc-key

<button data-sc-key="YOUR_HOSTED_PAYMENTS_ENABLED_PUBLIC_KEY"
        data-amount="3000">
        Buy Now
</button>

JavaScript

A global variable called SimplifyCommerce is exposed from which you can configure your hosted payments.

The available functions include:

Options set using the JavaScript API apply to all the buttons on your page. JavaScript options must be camel case, e.g., scKey.

<script>
    SimplifyCommerce.hostedPayments(
        function(response) {
            // response handler
        },
        {
            scKey: "YOUR_HOSTED_PAYMENTS_ENABLED_PUBLIC_KEY",
            color: "#12B830"
        }
    );
</script>

<button data-amount="3000">Buy Now $30</button>
<button data-amount="5000">Buy Now $50</button>

Options

JavaScript Callback

The JavaScript callback can only be used on websites that use HTTPS.

<script>
    SimplifyCommerce.hostedPayments(
        function(response) {
            console.log(response);
            // add your custom handler code here
        }
    ).closeOnCompletion();
</script>

<script>
    /**
     * Configure hosted payments callback.
     */
    var hostedPayments = SimplifyCommerce.hostedPayments(
        function(response) {
            var cardToken = response.cardToken;
            console.log(cardToken);

            // TODO: Pass token to the server & use Simplify's API to make a payment
        },
        {
            operation: 'create.token'
        }
    );

    /**
     * Handle the error response from the server call that
     * failed to make a payment from the card token.
     */
    function apiPaymentErrorHandler() {
        // re-enable the payment button, so the user can try again.
        hostedPayments.enablePayBtn();

        // TODO: Handle error
    }
</script>

A JSON object with the response parameters will be returned to the callback function.

Create Payment Response

For more detail on the response parameters see the payment API documentation.

Success response:

{
    "data":{
        "paymentDate":1420648846866,
        "authCode":"wKQuyx",
        "feeEstimated":false,
        "feeCurrency":"USD",
        "settlementAmount":3000,
        "paymentStatus":"APPROVED",
        "settlementCurrency":"USD",
        "reference":"99999",
        "amountRemaining":3000,
        "currency":"USD",
        "fee":116,
        "id":"oTGokc",
        "amount":3000,
        "amountEstimated":false,
        "refundedFees":0,
        "refunded":false,
        "source":"HOSTED_PAYMENTS",
        "description":"Jasmine Green Tea",
        "dateCreated":1420648846875,
        "disputed":false,
        "card":{
            "id":"MTqzLc",
            "expMonth":10,
            "expYear":99,
            "name":"Jane Doe",
            "dateCreated":1420648846516,
            "last4":"4444",
            "type":"MASTERCARD"
        },
    },
    "signature":"83962C160484C3A6D2CE5CBC4EBC80C0"
}

Error response:

{
   "field":"amount",
   "code":"nullable",
   "message":"amount cannot be null"
}

Create Token Response

For more detail on the response parameters see the card token API documentation.

{
    "card":{
         "id":"4TkGMc",
         "expMonth":10,
         "expYear":99,
         "dateCreated":1415276012360,
         "last4":"4444",
         "type":"MASTERCARD",
         "name":"Jane Doe"
    },
    "cardToken":"7d53dde5-ddc0-488a-ae33-5e43f1a",
    "amount":"3000",
    "reference":"REF123"
}

Modal Redirect URL

Use the redirect URL to return your customers back to your website with the response parameters returned in the query string. This option is ideal for websites that do not use HTTPS.

<script type="text/javascript" src="https://www.simplify.com/commerce/simplify.pay.js"></script>
<button data-sc-key="YOUR_HOSTED_PAYMENTS_ENABLED_PUBLIC_KEY"
        data-name="Jasmine Green Tea"
        data-description="Smooth tea with a rich jasmine bouquet"
        data-reference="99999"
        data-amount="3000"
        data-color="#12B830"
        data-redirect-url="https://www.example.com/checkout.html">
        Buy Now
</button>

Create Payment Response

For more detail on the response parameters see the payment API documentation.

Create Token Response

For more detail on the response parameters see the card token API documentation.

HTTP vs HTTPS

There are some security considerations to bear in mind when choosing which option of hosted payments to choose. Either option may be chosen and work as expected when using a sandbox key or in test mode.
However, when you switch to using a live key and begin to use hosted payments for real on your website, each have different requirements:

If your website is accessible over HTTPS, clicking the Simplify hosted payment button will display the payment form in a modal dialog on your website, offering a fluid, simple user experience for your customers. We recommend HTTPS as the best way to use Simplify Commerce's hosted payment button.

If your website is only accessible over HTTP, clicking the Simplify hosted payments button will redirect to a secure (HTTPS) page on Simplify.com. You can specify a redirect URL to return your customers back to your website once the transaction is complete.

Your website must be accessible over HTTPS only. The iframe will not load if your website is only accessible over HTTP. Your only option is to use the Modal option.

Domain Restrictions

When used for live payments (e.g. when configured with a live API key), the hosted payment button will only work on the website you registered when onboarding to a live Simplify Commerce account. This restriction is disabled when using a sandbox key for testing.

API Keys

If you specify create.payment or omit an operation type, you must create a new API Key pair with the 'Enable hosted payments' option selected (see screenshot below). Use the public key from this new key pair when configuring your hosted payment button.

After logging into your account, your API keys can be located at: Settings -> API Keys

Response Validation

The response will contain a hash signature that can be used to validate the response. The hash is made up of the query string parameters or the data object in the JSON response, plus your private API key.

You can recreate the signature on your server to validate that the response parameters were not tampered with.

The signature is created as follows: UPPERCASE(MD5_ENCODE("amount + reference + paymentId + paymentDate + paymentStatus + privateKey”))

Below is an example in PHP

$amount = '5000'; // The amount you supplied for this payment
$reference = 'order 123'; // The reference you supplied for this payment
$paymentId = $_REQUEST['paymentId']; // The simplify payment id
$paymentDate = $_REQUEST['paymentDate']; // The simplify payment date
$paymentStatus = $_REQUEST['paymentStatus']; // The simplify payment status
$privateKey = 'YOUR_PRIVATE_KEY'; // Your hosted payments enabled private API key

$signature = $_REQUEST['signature'];

$recreatedSignature = strtoupper(md5($amount . $reference . $paymentId . $paymentDate . $paymentStatus . $privateKey));

if ($recreatedSignature != $signature) {
    $result = 'Fail - signatures so not match';
} else {
    $result = 'Success - signatures matched';
}

echo $result;

Remember to keep your private key safe and only recreate the signature on your server.