iFrame Checkout
Display your workflow's payment providers to your customers in your chosen format and use the Apaya iFrame to render the Apaya Checkout or Apaya Consent Setup page in your own website.
Pre-set the payment provider to be used in the iFrame or allow your customers to select their desired payment mechanism and complete their transaction. Handle post-back messages from the iFrame and utilise the standard Apaya asynchronous webhooks to keep your platform in sync. Apaya will manage all aspects of the payment for all users.
Breakdown of steps:
Return a list of Payment Providers associated with your product's workflow. Use this list if you wish to display these on your website, or just to get the IDs to pass into the defaultProviderId value for when generating your RequestToken API method.
Make a request to the GetProviders API method to return a list of your Payment Providers (Sandbox: GetProviders).
Note: The iFrame can display your payment providers within the iFrame display as part of the Checkout experience, or you can choose to display these yourself on your own display.
Generate a unique token to access the Apaya iFrame by calling the RequestToken API method (Sandbox: RequestToken).
Note: You must use the tokenTypeId for the type of flow you want to display in the iFrame:
tokenTypeId of 4 for the Apaya Checkout (single purchase transaction).
tokenTypeId of 6 for the Apaya Consent Setup (recurring transactions).Note: When making your RequestToken request for iFrame, ensure to provide:
1. defaultProviderId parameter if you want to pre-set a Payment Provider from your workflow.
You can get these IDs from the GetProviders API method.
2. showPaymentOptions parameter, set to 'False' if you don't want your end-user to be able to choose from your full list of payment providers within the iFrame, otherwise set to 'True' to display the full list of payment providers in the iFrame.Send your user to the iFrame URL by appending the token e.g.
Sandbox Checkout: https://sandbox-frame.apaya.io/WHrH7zOq2hnDbJcYUuSgUXLwZ9J0LEfqemRV2x12345Sandbox Consent Setup: https://sandbox-frame.apaya.io/setup/WHrH7zOq2hnDbJcYUuSgUXLwZ9J0LEfqemRV2x12345Production Checkout: https://frame.apaya.io/WHrH7zOq2hnDbJcYUuSgUXLwZ9J0LEfqemRV2x12345Production Consent Setup: https://frame.apaya.io/setup/WHrH7zOq2hnDbJcYUuSgUXLwZ9J0LEfqemRV2x12345The iFrame page can be shown in an iframe as detailed in this basic example:
<iframe id="checkoutFrame" src="https://sandbox-frame.apaya.io/
WHrH7zOq2hnDbJcYUuSgUXLwZ9J0LEfqemRV2x12345" height=450 width=300 style="border:none;" title="Iframe Example" allow="payment"></iframe>Click here to have a look at the example HTML code for a complete iFrame implementation including handling of postback messages and iFrame size manipulation. Make sure you change the token in the example HTML for one you have generated (as they expire after 10mins if unused, or 24 hours if used).
The iFrame will provide a number of postback messages to the parent window, which include the following:
CheckoutLoaded - when page loaded, allows for your own loader image overlay beforehand.
PaymentOptionNotShown - When you choose to load with no payment option shown, so you can resize frame accordingly (approx 100px less height).
ShowPaymentOptions_{nnn} - When dropdown list of options selected - ({nnn} is px height of dynamic payment options).
HidePaymentOptions - When payment options dropdown is closed.
PaymentOptionSelected - When a payment option is selected from the list within the iFrame.
Error_{status} - When flow ends in an error - {status} is the status of our error. See Status Values for details.
Success_{params} - When flow ends in a success, your Success URL endpoint (as configured in the Apaya Portal) will be returned in the {params}, along with the following populated parameters:
e.g.Success_http://www.example.com?token=A9IotQFdJBSYjth7h)hGWmFAgzVjxU6xeGGT)AaAbB=&pt=ExamplePTValue&status=SUCCESStoken - Populated with the original token passed in when starting the Apaya iFrame flow.
pt - The pass-through value provided in the Token
status - Contains a brief description of the status of the user during/after the acquisition flow. See Status Values for details.
ConsentSetupLoaded - when Consent Setup page has loaded, allows for your own loader image overlay beforehand.
Consent_Error_{status} - When Consent Setup flow ends in an error - {status} is the status of our error. See Status Values for details.
Consent_Success_{params} - When Consent Setup flow ends in a success, your Success URL endpoint (as configured in the Apaya Portal) will be returned in the {params}, along with the following populated parameters:
e.g.http://www.example.com/?token=A9IotQFdJBSYjth7h)hGWmFAgzVjxU6xeGGT)AaAbB=&success=1&pt=ExamplePTValue&status=SUCCESS&hashedIdentifer=XXXXXXXXXXXX6417&providerId=1003&userConsentToken=OVoDEZZiD0F4heWCg7yYm3oTRjC7yU4i)JGxxdswOglsA%3d__kOJ49PeAFlVjgDDh5Ocrh)KXXXE3edA64xbIotu94%3dtoken - Populated with the original token passed in when starting the Apaya Consent Setup flow.
pt - The pass-through value provided in the Token
success - '1' signifying that successful acquisition has taken place. '0' if not.
status - Contains a brief description of the status of the user after the consent setup flow. See Status Values for details, especially any 'SETUP_' statuses.
hashedIdentifier - Contains a 'hashed' user identifier (card number, mobile number, or other) which you can display on your UI after being decoded.
Card numbers will be hashed with an 'X' character except for the final 4 digits E.g. XXXXXXXXXXXX6417
providerId - The payment provider used when providing consent. See Providers for a full list.
userConsentToken - The encrypted consent token created by the Apaya platform. Store this in your platform for use in future interactions with Apaya APIs to trigger reserve/authorization and when capturing a charge. If the user abandons the flow or fails consent, this will be returned as an empty parameter.
Your user will perform their transaction within the iFrame, and upon successful completion or upon transaction failure, the iFrame will provide the relevant 'Error_' or 'Success_' response postback message to the parent window for you to handle accordingly.
Note: The iFrame will not redirect to the success or failure redirect URL configured in the Apaya Portal. You are free to handle the user's journey after processing the response postback message.
Click here to have a look at the example HTML code for a complete iFrame implementation including handling of postback messages and iFrame size manipulation.
Make sure you change the token in the example HTML for one you have generated (as they expire after 10mins if unused, or 24 hours if used).Log the details of the transaction in your platform and if successful, give the user access to their service.
The Apaya platform can also send asynchronous webhook notifications to your platform containing billing information. Click here for more details.
Apple Pay on iFrame:
If you have Apple Pay in your workflow then please be aware that you can only use Apple Pay via the iFrame integration for Safari 17 and newer. You must do the following steps to be able to correctly view the Apple Pay button and perform a transaction:
Add 'Apple's Root Certificate' to your own website:
Go to the following Apple link: https://www.apple.com/certificateauthority/.
Choose the 'Apple Inc Root' link to download the certificate and install on your web server.
Register and validate the merchant domain:
The following steps will need to be performed by the party managing the Apple Developer, either Apaya or the Merchant.
(NOTE: On the sandbox Apaya Portal, a Merchant may be using 'Apaya Test Credentials' for a Connector, and therefore using Apaya's Apple Developer account, however on the Production Apaya Portal the Merchant will be using their own Connector credentials, and likely your own Apple Developer account.If Apaya is managing the Apple Developer account:
The merchant must send the full URL of the iFrame's parent-page, including sub-domains to their Apaya Account Manager.
Apaya will register and validate your parent-page URL with Apple.
Apaya will be prompted to download a validation file which Apaya will send to the merchant.
The merchant must upload this file to their platform in the following location of your website (create if it doesn't exist):
wwwroot/.well-known/
Once uploaded, notify your Apaya Account Manager of the upload so we can verify the domain on the Apple Developer Portal.
NOTE: If the parent-page URL differs based upon your Apaya ProductID then ensure to provide each URL with the associated ProductID so they can all be configured on Apaya's platform.
If the merchant is managing their own Apple Developer account:
Merchant to utilise their own full URL domain of the parent-page, including sub-domains.
Apple Account owner to go to section ‘Register and validate your merchant domain’ on Apple Developer portal. please use the parent-page URL (inclusive of sub-domains).
During the domain validation process you will be prompted to download a validation file.
Once downloaded, upload this file to the following location of your website (create if it doesn't exist):
wwwroot/.well-known/
Once uploaded, verify the domain in the ‘Register and validate your merchant domain’ area on the Apple Developer portal.
Merchant to provide their Apaya Account Manager with the full URL of the parent-page hosting the iFrame. Apaya will then configure this for validation on the Apaya platform.
NOTE: If the parent-page URL differs based upon your Apaya ProductID then ensure to provide each URL with the associated ProductID so they can all be configured on Apaya's platform.
Get Production access:
Once you're happy with your Sandbox tests and you want Production access, sign in and go to Products and click on Production. Configure a 'subscription' just as you did for Sandbox. Give your subscription a relevant name, again you can change this later if required.
Your Production subscription will be sent to Apaya for approval. Once approved, you will have access to the production API. Click on the green 'Try It' button to test your request and see a response from any of the required production API methods. Note: Your API access key will only be pre-populated after your Production subscription request has been approved by Apaya.
If you require any assistance, contact us on support@apaya.io