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:

  1. 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.

  2. 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.

  3. Send your user to the iFrame URL by appending the token e.g.
    Sandbox Checkout: https://sandbox-frame.apaya.io/WHrH7zOq2hnDbJcYUuSgUXLwZ9J0LEfqemRV2x12345
    Sandbox Consent Setup: https://sandbox-frame.apaya.io/setup/WHrH7zOq2hnDbJcYUuSgUXLwZ9J0LEfqemRV2x12345

    Production Checkout: https://frame.apaya.io/WHrH7zOq2hnDbJcYUuSgUXLwZ9J0LEfqemRV2x12345
    Production Consent Setup: https://frame.apaya.io/setup/WHrH7zOq2hnDbJcYUuSgUXLwZ9J0LEfqemRV2x12345

  4. The 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"></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).

  5. 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=SUCCESS

      • token - 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%3d

      • token - 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.

  6. 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.

  7. 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).

  8. Log the details of the transaction in your platform and if successful, give the user access to their service.

  9. The Apaya platform can also send asynchronous webhook notifications to your platform containing billing information. Click here for more details.

Get Production access:

  1. 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.

  2. 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.

  3. If you require any assistance, contact us on support@apaya.io