X-Payments:Communication between X-Payments iframe and the store

X-Payments API

1. API versions supported
2. Samples
3. API requests
   • Request/Response encryption
   • Encryption and communication
   • cURL as a means of sending requests
   • Data types
4. API Requests from the store to X-Payments
   1. Admin area/X-Payments configuration
      • Test connection request
      • Payment configurations list request
   2. Payment creation (Regular payment and tokenization)
      • Payment initialisation request
      • Charge again transaction request (Tokenization)
   3. Payment information
      • Payment information request
      • Detailed payment and transaction information request
   4. Actions on payments (secondary actions)
      • Capture authorized transaction request
      • Void authorized transaction request
      • Refund captured transaction request
      • Accept potentially fraudulent transaction request
      • Decline potentially fraudulent transaction request
5. Callback requests (web-hooks) from X-Payments to the store
   • Callback request with service payment information
   • Check cart callback request
6. Browser-related
   • Redirecting a customer to the cardholder data entering page
   • Communication between X-Payments iframe and the store
7. Appendix A. Status codes.
   • Payment status codes
   • Operation status codes
8. 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 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 payment initialization request needs to be sent, and the customer needs to be 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
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: {}

}

---