Overview
Embed a secure iframe so card data never touches your environment.
The Doura Payments API offers a secure Hosted Payment Form (HPF) solution that simplifies payment collection while maintaining strong security and compliance standards.
The customer enters their card details into the form, which is hosted outside your environment. Your servers never see or store card data.
How it works
Initiate the session
Your backend server makes a POST request to the API (for example /payment-methods/virtual, /transactions/virtual-sale) with your transaction details.
You can include a returnUrl parameter to control where customers are redirected after completing payment or tokenizing a card. 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.
Receive the session URL
The API returns a short-lived, unique iframe URL specific to this transaction, along with a session ID and expiration timestamp.
Embed the form
You embed this iframe URL in your payment page. The iframe contains a fully-styled, responsive payment form.
The customer enters payment info
The customer enters their payment information (card details, billing address) directly into the secure form, which is isolated from your website's environment.
The API processes the payment
When the customer submits the form, the API processes the payment outside your environment.
The flow completes
The flow completes differently depending on which parameters were included in your initial request. See Flow completion below.
Your system receives a webhook
Configured endpoints receive webhook notifications for transaction outcomes. A local form error or abandoned session does not guarantee a transaction webhook.
Configured webhooks report transaction outcomes independently of the customer's browser. A session or local validation error might not produce a transaction webhook. Use verified webhooks and authenticated transaction retrieval for your records, and use redirects and callbacks to update the customer's experience.
Flow completion
Depending on the parameters in your initial request, the behaviour at the end of the transaction flow will be different:
useJavaScriptCallback |
returnUrl |
What happens |
|---|---|---|
true |
Provided | The iframe sends the transaction response to your parent page via a JavaScript function, so you can direct the rest of the customer experience based on the outcome. The customer is then redirected to the returnUrl, with transaction result parameters in the URL query string. |
true |
Not provided | The iframe sends the transaction response to your parent page via a JavaScript function. The customer is redirected to the default success or issue screen. |
Omitted or false |
Provided | No JavaScript function is called on the parent page. The customer is redirected to the returnUrl, with transaction result parameters in the URL query string. |
Omitted or false |
Not provided | No JavaScript function is called on the parent page. The customer is redirected to the default success or issue screen. |
Next steps
| Form configuration | Control how much billing information the form collects. | Form configuration |
| Verifying the redirect | Validate the HMAC hash before trusting a redirect. Do not skip this. | Verifying the redirect |
| JavaScript callbacks | Handle the postMessage payload in your parent page. | JavaScript callbacks |
| Best practices | Origin validation, session timeouts, and responsive layout. | Implementation best practices |
If you need Apple Pay or Google Pay, use the Payment SDK instead. It wraps the same sessions in a web component and adds wallet buttons.