Hosted Payment Form

1. Initiate Session: Your backend server makes a POST request to our API (e.g., /payment-methods/virtual, /transactions/virtual-sale, etc.) with your transaction details. You can include a returnUrl parameter to control where customers are redirected after completing payment, tokenizing a card, etc. The returnUrl is typically used to direct customers to order confirmation pages, receipt pages, or to grant immediate access to purchased digital content after successful payment. You can also include a useJavaScriptCallback flag to have the iframe post a message to the parent page with the transaction response.

2. Receive Session URL: Our API returns a short-lived, unique iframe URL specific to this transaction, along with a session ID and expiration timestamp.

3. Embed HPF: You embed this iframe URL in your payment page. The iframe contains a fully-styled, responsive payment form.

4. Customer Enters Payment Info: The customer enters their payment information (card details, billing address) directly into our secure form, which is isolated from your website's environment.

5. Payment Processing: When the customer submits the form, we process the payment in our secure environment.

6. Flow Completion: The flow completes differently depending on which parameters were included in your initial request. See the Flow Completion section below.

7. Webhook Notification: Regardless of the flow, your system receives a webhook notification with complete transaction details.

Depending on the parameters in your initial request, the behavior at the end of the transaction flow will be different:

• useJavaScriptCallback set to true, and returnUrl provided: The iframe sends the transaction response using a JavaScript function to your parent page, and you can direct the rest of the customer experience based on the transaction outcome. The customer is redirected to the returnUrl provided, with transaction result parameters in the URL query string.
• useJavaScriptCallback set to true, and no returnUrl provided: The iframe sends the transaction response using a JavaScript function to your parent page, and you can direct the rest of the customer experience based on the transaction outcome. The customer is redirected to the default success or issue screen.
• useJavaScriptCallback omitted from the request or set to false, and returnUrl provided: No JavaScript function is called on the parent page. The customer is redirected to the returnUrl provided, with transaction result parameters in the URL query string.
• useJavaScriptCallback omitted from the request or set to false, and no returnUrl provided: No JavaScript function is called on the parent page. The customer is redirected to the default success or issue screen.

Our Hosted Payment Form provides a clean, professional payment interface that collects:

• Cardholder name
• Card number, expiration date, and security code
• Billing address details

The form is responsive and works on mobile, tablet, and desktop devices.

When no returnUrl is provided and the useJavaScriptCallback flag is not used, customers will see success or issue screens that provide immediate visual feedback about their transaction status.

If a payment session expires or becomes invalid, customers will see the following screen:

When using the returnUrl parameter, the following information is appended to your URL when the customer is redirected back to your site:

These parameters allow your application to respond appropriately to transaction outcomes, update your order systems, and provide relevant feedback to customers without requiring a separate API call to check transaction status.

When using the returnUrl approach, our system includes a cryptographic hash to validate the authenticity of the redirect. This protects against tampering of the query string parameters. The verification process uses HMAC-SHA256 hashing. When we redirect customers to your return URL, we include key transaction parameters, along with the lowercase hex-encoded hash included as a hash query parameter in the redirect URL.

• Hash input: The referenceId and resultCode values, concatenated with no spaces (referenceId + resultCode).
• Secret key: The paymentMethodId (e.g., pmt_vrt_...) used to create the hosted payment form session.
• Output format: Lowercase hex-encoded HMAC-SHA256 hash.

While similar to our webhook authentication method, the redirect hashing process has important differences:

To validate the authenticity of a redirect, follow these steps:

1. Extract the hash parameter from the returned URL parameters
2. Extract the referenceId and resultCode parameter values from the URL
3. Concatenate the two values with no spaces: referenceId + resultCode
4. Use the original paymentMethodId used when generating the hosted payment form session (the pmt_vrt_... value) as the HMAC secret key
5. Generate the HMAC-SHA256 hash and encode the result as a lowercase hex string
6. Compare your generated hash with the received hash parameter using an exact match comparison
7. Only accept the redirect if the hashes match exactly

Example

When a payment method with ID pmt_vrt_01JTNZ2Z2XBNMGMG9ENY41AKRG was used to create a hosted payment page session, and given the following returnUrl:

https://merchant.example.com/payment-complete?paymentMethodId=pmt_tkn_01JVGD11ZW2N8859Z9RSJKBPDB&resultCode=0&cardType=VISA&transactionId=trx_01JVGD0BD3D6SRW6A941CPWCJ5&referenceId=ref_238832ae&amount=1899&invoiceNumber=inv_7d7ab39d&orderNumber=ord_cead58aa&hash=7795ad43353004b2d8434af7ff5253d597ca290492eec43c714460a0d7ecdbce

Extract the referenceId and resultCode query string key/value pairs:

referenceId=ref_238832ae
resultCode=0

Concatenate the values only into a single string:

ref_238832ae0

Use the payment method ID used to create the hosted payment form session as the HMAC secret key:

pmt_vrt_01JTNZ2Z2XBNMGMG9ENY41AKRG

Generate the HMAC-SHA256 hash, and encode the result as a lowercase hex string:

7795ad43353004b2d8434af7ff5253d597ca290492eec43c714460a0d7ecdbce

The hash value from the query string must match 7795ad43353004b2d8434af7ff5253d597ca290492eec43c714460a0d7ecdbce.

Implementing this check on your server helps prevent tampering and spoofed redirect responses, and should be a standard part of your payment flow integration.

When using useJavaScriptCallback, the standard transaction response object is passed to the parent window when the transaction is complete. In addition to the response fields (refer to the various originalResponse objects of the related webhooks), a success flag is also present in the response to indicate whether the transaction was successful.

{
  "success": true,
  "id": "trx_01J2F0EKHC7HY2R93C8ENBD1FG",
  "type": "Sale",
  "referenceId": "ref_s192i49i",
  "orderNumber": "order_number_1234",
  "invoiceNumber": "inv_12345678",
  "requestedAmount": 1000,
  "approvedAmount": 1000,
  "balanceAmount": 0,
  "paymentMethod": {
    "id": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
    "type": "Virtual",
    "currency": "USD",
    "description": "Online Checkout Iframe"
  },
  "transactionResponses": [
    {
      "responseCode": 1,
      "amountApproved": 1000,
      "paymentMethod": {
        "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
        "type": "Token",
        "currency": "USD",
        "cardType": "VISA",
        "maskedCardNumber": "4****1111",
        "cardExpDate": "1225"
      },
      "cardType": "VISA",
      "accountType": "Credit",
      "hostResponseText": "APPROVED"
    }
  ],
  "resultCode": 0,
  "resultText": "Card successfully tokenized",
  "timestamp": "2025-06-02T23:56:18.2102020Z"
}

{
  "success": false,
  "id": "trx_01J2F0EKHC7HY2R93C8ENBD1FG",
  "referenceId": "ref_s192i49i",
  "orderNumber": "order_number_1234",
  "invoiceNumber": "inv_12345678",
  "type": "Sale",
  "resultCode": 9999,
  "resultText": "Transaction declined",
  "errorMessage": "Transaction declined",
  "errorCode": "-1"
}

{
  "success": false,
  "type": "Tokenize",
  "resultCode": 9999,
  "resultText": "Failed to retrieve session data",
  "errorMessage": "Failed to retrieve session data",
  "errorCode": "3201"
}

Your implementation should handle various response statuses, including:

• Successful payments (resultCode = 0)
• Declined transactions
• Expired sessions
• Processing errors

When processing errors occur or transaction status is uncertain, use the GET /transactions (List Transactions) endpoint to verify the final transaction outcome before retrying or taking corrective action.

Implement Proper Origin Validation

Always validate that postMessage events come from our trusted domain to prevent malicious scripts from sending fake transaction results.

Handle Timeouts Gracefully

Sessions expire after a short period, so provide clear messaging to users if this happens.

Test with Our Test Cards

Use our test cards during your integration development.

Responsive Design

Ensure your payment page layout accommodates the iframe appropriately on all devices.