Overview
Instead of redirecting to the Hosted Gateway, it is also possible to display it in an iframe.
*Important Note: If you are going to display invoices within an iframe, DO NOT include a the parameter `"redirect_url"` when creating the invoice.*
Usage
Insert an iframe with the following syntax into your checkout page.
```
<iframe src="https://gateway.gocoin.com/invoices/:id" style="width: 640px; height: 600px; border: none; box-shadow: 1px 1px 3px #333;" allowtransparency="true" frameborder="0"></iframe>
```
Demo:
<iframe src="https://gateway.gocoin.com/demo/invoice" style="width: 640px; height: 600px; border: none; box-shadow: 1px 1px 3px #333;" allowtransparency="true" frameborder="0"></iframe>
Iframe Notifications via JavaScript PostMessage
The GoCoin Gateway enables your page to perform an action when a payment is received. The Gateway publishes the following events via postMessage:
| Event | Trigger | Invoice status | Indended Action |
| --- | ---- | ---- | ----|
| invoice_expired | 15 minute payment window expires. | unpaid | Redirect your customer back to the shopping cart and ask them if they still want to pay, or to contact support if they paid and the transaction was delayed. |
| invoice_underpaid | A payment is received but does not cover the invoice balance. | underpaid |Do nothing, the page instructs the customer to pay the remainder. |
| invoice_paid | Payment was received and the balance was met or exceeded | paid | Redirect your user to a thank you page, or alert them that their order is being processed. |
**Best practice on "invoice_paid" (invoice.status is 'paid') is to redirect your user to a 'success' or 'thank you' page, and process their order after the invoice state changes to `"ready_to_ship"`.**
*Note: The invoice is not considered valid until it has reached 2 confirmations on the Blockchain, which is the invoice state `"ready_to_ship"`. Our [webhook system](http://help.gocoin.com/kb/api-notifications/invoice-event-webhooks) sends this event, but the Gateway does not, as it will take 10-20 minutes for 2 confirmations to occur.*
Usage
Add the following JS to the page containing the iframe:
@@@
<script type="text/javascript">
// Define the message handler function
function gocoinMessage(event) {
"use strict";
// Make sure the message posted to this window is from GoCoin
if (event.origin === 'https://gateway.gocoin.com') {
var event_name = event.data.split('|')[0], invoice_id = event.data.split('|')[1];
//Act on event notification
switch (event_name) {
case 'invoice_expired':
// do something with expired invoice
case 'invoice_underpaid':
// do something with underpaid invoice
case 'invoice_paid':
// do something with paid invoice
alert(event_name);
break;
}
}
}
</script>
window.addEventListener('message', gocoinMessage, false);
@@@
^^ You can edit each of the case blocks to perform whichever actions you prefer.