X-Payments:Communication between X-Payments iframe and the store
- API versions supported
- Samples
- API requests
- API Requests from the store to X-Payments
- Callback requests (web-hooks) from X-Payments to the store
- Browser-related
- Appendix A. Status codes.
- See also
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. X-Payments sends it as 2, which indicates that the online store should re-initialize the payment. In API v1.3 no other values are supported.
Messages sent from the online store to X-Payments
Submit payment form
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: {}
}
Messages sent from X-Payments to the online store
Iframe is loaded and ready
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()
- }
}
Payment form submitted with an error
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: {}
}
Internal error
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'
- }
}
Session is expired
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'
- }
}
Payment form in Iframe is submitted (supported by API v1.4 and later)
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: {}
}
