#Direct Integration

#Creating a 'chippin'

When your merchant account is initially setup, it will only be able to create sandbox 'chippins' by redirecting or posting to the following URL.

https://chippin.co.uk/sandbox/new

When you want to create a 'chippin' in the live environment you simply follow the same procedure but redirect or post to:

https://chippin.co.uk/new

The following details must be passed to this endpoint. This can either be done via a GET redirect or a POST:

Query String Key Query String Value
merchant_id 100000
merchant_order_id As generated by merchant shopping system
total_amount The total amount of the order in pence
first_name First name of the customer
last_name Last name of the customer
email Email address of the customer
duration This is the number of hours you wish the 'chippin' to last before it times out.
grace_period This is the number of hours you wish to give the user to complete a chippin after the timeout period.
currency_code This is the currency code for payments and should typically be set to gbp. A list of currency codes you can pass can be found here https://support.stripe.com/questions/which-currencies-does-stripe-support - Chippin supports all of the currency codes Stripe does with the exception of Japanese Yen.
hmac A secure sha256 HMAC generated from merchant secret and query string data. This protects URL tampering. See details below for how to generate.

Note. Duration + grace_period should be less than 7 days (168 hours).

As per normal web behavior, the order of the query string parameters does not matter.

Note. If parameters are missed, or the HMAC is computed wrong, the sandbox will throw a 404 http code.

You can see an example 'chippin' in action at:

https://chippin.co.uk/debug/index

View the source of the page to see how it is constructed.

#Minimum Amounts

Your application should ensure the purchase meets minimum amounts before passing to Chippin.

The minimum order amounts should be twice (2x) the Stripe minimum payment amount. The Stripe minimums can be seen here https://support.stripe.com/questions/what-is-the-minimum-amount-i-can-charge-with-stripe

If you pass an order to Chippin less than the minimum amount a 500 error will be returned. As such, you should trap this condition prior to redirecting. In practice, it is unlikely that a basket amount would be so low to cause a problem.

If a user tries to split a payment below the minimum amount, they will be alerted to the issue and will not be able to proceed.

#Passing Product Details

As well as the primary 'chippin' details, you are also required to pass details of the product(s). Product details are passed as an array consisting of the following parameters:

Query String Key Query String Value
products Name of the product e.g. 'Samsung Flat Screen Television'
products Url to image of the product
products Amount in pence for the product

You can pass as many products as you wish by simply repeating these parameters. The first item passed is considered to be the primary product, so consideration should be give to what determines this at the merchant end, possibly the product with the highest amount but this is down to the merchant to decide.

Note. Product details are not part of HMAC signing and do not impact the amount of money collected in any way, amounts passed with products are for display purposes only.

#Generating Redirect Signing HMAC

The HMAC that is passed in the initial redirect is computed by generating a sha256 of the following:

merchant_secret
merchant_id + merchant_order_id + total_amount + duration + grace_period + currency_code

Depending on the library, you might need to append the merchant_secret to the string as well. In ruby, you pass it as the second parameter and then the concatenated string as follows:

An example of this, generated in ruby looks like:

OpenSSL::HMAC.hexdigest('sha256', '5ba3e1caf655f11b65c2bcef3ec55299a174072a','100000'+'123'+'50000'+'72'+'8'+'gbp')

In PHP, you pass merchant_secret as the third parameter:

An example of this, generated in php looks like this (http://php.net/manual/en/function.hash-hmac.php):

hash_hmac('sha256','100000'.'123'.'50000'.'72'.'8'.'gbp', '564b6774653a9d9687aa0a09b73d3c1b91ccf6772d761239c0da45ad3b345169')

The resulting HMAC will be:

8fad70db638bd2e5f72ef87e7c5b66708f1f1559e528bb6db489f3e5e8fcd8f6

If, when computing an HMAC in your language with same input as above does not yield the same result, check the library and settings being used.

An example form integration can be seen at https://chippin.co.uk/debug/index.

#Callbacks and Callback Validation HMAC

Callbacks are your method as the merchant to know what is going on with the 'chippin' process. Some of the callbacks that are sent happen in the background with a POST, some of them are simple redirects at the end of a process with a GET.

Each callback is signed using a validation HMAC and should be validated to ensure integrity and prevent spoofed callbacks.

Each callback will receive a merchant_order_id which is your original order reference, this is passed back to each callback with the computed validation HMAC.

The merchant should compute their own HMAC using the incoming merchant_order_id based on the following:

callback_key + merchant_secret + merchant_id + merchant_order_id

An example of this generated in ruby looks like:

OpenSSL::HMAC.hexdigest('sha256', '5ba3e1caf655f11b65c2bcef3ec55299a174072a', 'completed'+'100000'+'123')

An example of this generated in PHP looks like:

hash_hmac('sha256', 'completed'.'100000'.'123', '5ba3e1caf655f11b65c2bcef3ec55299a174072a')

For the 'contributed' callback Chippin also passes back the details of the contributor. For this callback the merchant should compute their own HMAC using the following parameters:

callback_key + merchant_secret + merchant_id + merchant_order\_id + first_name + last_name + email

An example of this generated in ruby looks like:

OpenSSL::HMAC.hexdigest('sha256', '5ba3e1caf655f11b65c2bcef3ec55299a174072a', 'completed'+'100000'+'123'+'Joe'+'Bloggs'+'joe@newcustomer.com')

Once the HMAC has been computed, it should be compared to the incoming HMAC passed in on the callback. If the two HMACs are not the same, the URL should be considered bogus (spoofed) and a relevant error shown to the user.

Note. It is vital you do compare a computed HMAC against the one Chippin sends you for integrity. Failing to do this could cause orders to be completed that have not received payment or invalid data being persisted to your database.

The following details each callback:

Callback Key Purpose / Trigger Point Type Parameters passed back Triggered by
invited Happens one time at the point first invite(s) to contributors are sent. This is likely point you might wish to reserve stock. Background merchant_order_id, hmac Instigator
contributed Occurs after each contributor pages. This is the point to say thank you to the contributor and upsell. Contributor payment has been pre-authed at this point but not collected. Foreground redirect merchant_order_id, hmac, first_name, last_name, email Contributor
rejected Occurs if a contributor rejects an invitation to contribute. Foreground redirect merchant_order_id, hmac Contributor
completed Occurs when instigator manually completes a chippin. This does not mean the money has been taken yet. Corresponding merchant page should say something along the lines of "Thank you for completing your chippin, we will email you order completion details shortly." Foreground redirect merchant_order_id, hmac Instigator
paid All payments have been taken, the order is complete and merchant should email user details of their order. Background merchant_order_id, hmac n/a
failed Occurs if there is an error that can not be recovered. All payments/pre-auths are refunded by Chippin. This should rarely happen, but if it does you should update user about order status and probably provide them an alternative payment method or suggest re-placing the order. Background merchant_order_id, hmac n/a
cancelled Occurs if the instigator chooses to cancel the 'chippin'. At this point you should probably indicate order has not been completed and probably provide them an alternative payment method or suggest re-placing the order. Foreground redirect merchant_order_id, hmac instigator
timed_out Occurs if the 'chippin' times out (the duration of time allowed to complete has passed). At this point, you should probably release stock and email the customer to inform them to re-place the order. Background merchant_order_id, hmac n/a