View source for X-Payments:Communication between X-Payments iframe and the store

<noinclude>{{XP_API_TOC}}</noinclude>
===Communication structure===
Communication between the online store (parent frame) and X-Payments (iframe) is implemented with the help of the javascript Window.postMessage method. Notifictions to both the sides represent stringified JSON formatted texts that consist of a service message (string) and an optional list of parameters:
:* '''height''': height of the iframe
:* '''error''': human readable message
:* '''type''': message type indicating which actions should be taken by the store:
::* 0: No actions are necessary.
::* 1: Due to some error, X-Payments cannot process payments until the merchant intervenes (This may be the case if, for example, the payment configuration is configured incorrectly, or X-Payments has detected a change in the template files). In this case, the store will have to provide an alternative payment method to the customer.
::* 2: The store should re-initialize the payment; i.e. a new [[X-Payments:Payment_initialisation_request | payment initialization]] request needs to be sent, and the customer needs to be [[X-Payments:Redirecting_a_customer_to_the_cardholder_data_entering_page | redirected to the payment form]] with the new token.
::* 3: The received error message should be shown to the customer. The alert-alike (modal) way is recommended.
::* 4: The received error message should be shown to the customer. It's recommended to show it as a regular top message/information hint.

===Messages sent from the online store to X-Payments===
'''Submit payment form'''<br />
X-Payments' iframe does not have a Submit button, so instead of it the payment form should be submitted from the parent window by any kind of "Submit order" or "Place order" button at checkout. At the same time, the special message '''submitPaymentForm''' with no parameters should be sent.
-----------------------------------------------------------
{
:::message: 'submitPaymentForm',
:::params:  {}
}
-----------------------------------------------------------

<br /><br />
===Messages sent from X-Payments to the online store===
'''Iframe is loaded and ready'''<br />
The message ready notifies the parent window that the payment form is ready. The actual height of the iframe is included in the parameters, so the parent window (checkout page) can perform the necessary adjustments.
-----------------------------------------------------------
{
:::message: 'ready',
:::params: {
::::::height: $(document).height()
:::}
}
-----------------------------------------------------------
<br />
'''Payment form submitted with an error'''<br />
The message '''paymentFormSubmitError''' with no parameters is sent in the case of any validation error. This may be the case, for example, if  the customer's credit card expiration date is in the past, or the credit card number does not match the card type (e.g. VISA, MasterCard), or when a required field has not been submitted (e.g. CVV2). Once the message '''paymentFormSubmitError''' with no parameters has been received, the store should not proceed to the next step of the checkout process, but should expect the payment form to be submitted again.
-----------------------------------------------------------
{
:::message: 'paymentFormSubmitError',
:::params: {}
}
-----------------------------------------------------------
<br />
'''Internal error'''<br />
The '''paymentFormSubmitError''' message with a special set of parameters is used to notify the store if something is wrong outside X-Payments, and X-Payments cannot do anything about it (for example, if the payment gateway has sent an unknown/unexpected piece of data).
-----------------------------------------------------------
{
:::message: 'paymentFormSubmitError',
:::params: {
::::::height: $(document).height(),
::::::error: 'Internal error',
::::::type: '2'
:::}
}
-----------------------------------------------------------
<br />
'''Session is expired'''<br />
For security reasons the length of the session is limited to 15 minutes. After this period the store has to re-initialize the payment. In this case X-Payments sends the '''paymentFormSubmitError''' message with the "Payment session expired" error.
-----------------------------------------------------------
{
:::message: 'paymentFormSubmitError',
:::params: {
::::::height: $(document).height(),
::::::error: 'Payment session expired',
::::::type: '2'
:::}
}
-----------------------------------------------------------
<br />
'''Payment form in Iframe is submitted''' (supported by API v1.4 and later)<br />
The message '''paymentFormSubmit''' notifies the parent window that the payment form has been submitted from the X-Payments side; for example, if a customer clicks the Enter key inside the iframe. Once the store receives this message, it should operate in the same way as though the customer has clicked the Place order button at checkout.
-----------------------------------------------------------
{
:::message: 'paymentFormSubmit',
:::params: {}
}

-----------------------------------------------------------
<br /><br />