Integrate with custom checkout and payment iframe

With a CardCorp merchant account, you can send your customer to your own checkout and integrate the payment iframe in your website. You can also add Apple Pay and Google Pay.

📘

CardCorp merchant account required

You cannot use a BillPro custom checkout for Stripe. Instead, you can Integrate with payment links.

The BillPro payment iframe checkout is an SAQ-A-compliant payment-form solution that is both secure and simple to integrate. The payment widget receives sensitive card data from the customer's browser and sends it directly to the payment gateway.

Diagram of BillPro payment with custom checkout

Diagram of how to process a payment with the custom checkout.

flowchart TD 
	 CreateOrder[Create an order with the BillPro API]
   GetCheckout[Get checkout details]
   DisplayIframe[Display gateway iframe checkout on your website]
   CustomerPays[Customer pays in payment gateway]
   CheckoutUpdatesBillPro[Checkout updates BillPro]
   TransactionApproved{Transaction approved?}
   RedirectUrl[Redirect to Redirect URL]
   FailedRedirectUrl[Redirect to Failed Redirect URL]
   GetResult[Get result from redirect]
 
   CreateOrder -- create_checkout redirect_url --> GetCheckout
   GetCheckout -- id form_action integrity --> DisplayIframe
   DisplayIframe --> CustomerPays
   CustomerPays --> CheckoutUpdatesBillPro
   CheckoutUpdatesBillPro --> TransactionApproved
   TransactionApproved -->|Yes|RedirectUrl
   TransactionApproved -->|No|FailedRedirectUrl
   RedirectUrl --> GetResult
   FailedRedirectUrl --> GetResult

Before you begin

Before you create an order to process a payment, create at least one product and at least one customer.

1. Create your product in the BillPro UI. See Create your product catalogue. Get the product's id to use as the product_id in the order.
2. You can create a customer with the API, see Create customer, or in the UI. Get the customer's id to use as the customer_id in the order.

Create an order with the BillPro API

Use BillPro's API to create an order. For more details, see Tutorial - Create an order with the BillPro API. In the order object, add the product, customer, and so on. Then set the following attributes.

1. Set the create_checkout attribute to true.
2. Set the invoice_id, which is your unique merchant identifier for the order. This should be around 10 alphanumeric characters.
3. Set a redirect_url for an approved payment or card registration and a failed_redirect_url for a declined payment or card registration. We recommend using two different URLs because then you can detect from the redirect if a transaction was approved or not. If you do not send these URLs, BillPro displays its own checkout success message or failure message and stays on the same page so that the customer can retry a failed transaction.
4. From the API response:
   1. Save the value of the id of the order.
   2. Get the checkout id, form_action, and integrity values.

Example request

Example request to create an order with a checkout. This example request contains the URL for the staging environment, which is https://staging.bill.pro/api/v1/. For the production environment, use https://app.bill.pro/api/v1.

curl --request POST \
     --url https://staging.bill.pro/api/v1/orders/create_single_order \
     --header 'Authorization: Bearer {api_token}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "order": {
    "currency": "EUR",
    "customer_id": 361,
    "invoice_id": "ABCD123123",
    "create_checkout": true,
    "order_products": [
      {
        "product_id": 74
      }
    ],
    "redirect_url": "https://{approved_message_url}",
    "failed_redirect_url": "https://{denied_message_url}"
  }
}
'

Example checkout attribute

Example checkout attribute, which is part of the API response when you create an order.

{
   ...
        "checkout": {
            "result": {
                "code": "000.200.100",
                "description": "successfully created checkout"
            },
            "buildNumber": "806b4fe643a0cc426b427750aa19a2d38aa82462@2024-10-18 00:43:27 +0000",
            "timestamp": "2024-10-18 10:08:06+0000",
            "ndc": "760D262C5E1AA43BB34E53D4A3281A14.uat01-vm-tx01",
            "id": "760D262C5E1AA43BB34E53D4A3281A14.uat01-vm-tx01",
            "integrity": "sha384-ZUpvtVLMInfhrHwNcUyqddyY2/blEMtWl/HC/inm8gVn2aJXCXtcfnaj4jBee8le",
            "form_action": "https://staging.bill.pro/checkout/1538/C2vNRYZAQFCkQ7ZkBadxpoQv"
        },
    ...
}

For the full API documentation, see Orders.

Display the payment iframe

On your website, to display the payment iframe, run a script to include the gateway's checkout. This script uses the widget from the gateway's test environment. The test environment URL is https://eu-test.oppwa.com/v1/. The production environment is https://eu-prod.oppwa.com/v1/.

1. On your website, use JavaScript to define the checkout. Enter the checkout checkoutId and the integrity as part of the JavaScript to define the checkout.

   JavaScript to define the checkout

   <script src="https://eu-test.oppwa.com/v1/paymentWidgets.js?checkoutId={checkoutId}" integrity="{integrity}" crossorigin="anonymous">
   </script>

   
   

2. In the HTML definition of the iframe, for the form_action, set the BillPro link from the checkout form_action. This updates the order in BillPro using a very fast redirect (without loading the BillPro page) and then it redirects to your BillPro redirect URLs.

<form action="{form_action}" class="paymentWidgets" data-brands="VISA MASTER"></form>

You can also configure and style the iframe with your own branding. The default iframe lets you define the card brand and requires 3DS verification.

To customise the payment widget to match the look of your own site, see this customisation guide and the advanced options guide. To display some sample customisations, go to demo checkouts. You can obtain the code for the demo checkouts at Demo checkouts on GitHub.

📘

Checkout expiry

The checkout is valid for 25 minutes. If it expires, use the Renew Checkout request of the BillPro API to renew it and replace the id in the payment iframe.

Get the result of the transaction

1. To get the result of the transaction, you can check where BillPro redirects the user after their transaction (to the redirect_url or failed_redirect_url). Or you can use the BillPro payment gateway webhook.

If you subscribe to the payment gateway webhook, you can identify the transaction by BillPro's merchant order_id and merchant customer_id. The merchant customer ID is part of a customer object that has more attributes. BillPro also uses its own unique system identifier for the order, called the ZUID, which is sent as the merchant transaction ID.

1. “merchantInvoiceId”:“ABCD123123”
2. "customer: {... "merchantCustomerId":"DC12341234" ...}
3. "merchantTransactionId”:“ZUID-123”

For more details, see BillPro payment gateway webhook.

Configure Apple Pay and Google Pay in the custom checkout

If you have a CardCorp merchant account, you can configure Google Pay and Apple Pay in the custom checkout.

Apple Pay

To use Apple Pay do these steps.

1. Obtain a certificate with one of these steps.
   1. Obtain the gateway certificate from BillPro Merchant Support
   2. Apply for your own Apple Developer account and obtain the keys and CSR from BillPro Merchant Support. Then obtain your certificate from Apple and send your certificate to CardCorp Merchant Support.
2. Request that Apple Pay be enabled in BillPro with CardCorp gateway.
3. Host the certificate at localhost in the test environment. In your production environment, host it at /.well-known/apple-developer-merchantid-domain-association.
4. Enable Apple Pay in the checkout HTML as part of the data-brands using the APPLEPAY option.

For all Apple Pay options in the CardCorp gateway, see Apple Pay options for custom checkout.

Google Pay

To use Google Pay do these steps.

1. Apply for your Google Merchant ID for your website.
2. Request that Google Pay is enabled in BillPro with CardCorp gateway.
3. Enable Google Pay in the checkout.
   1. In the HTML as part of data-brands using the GOOGLEPAY option.
   2. In the test environment, in the JavaScript, do not add your merchant ID
      JavaScript test environment

      var wpwlOptions = {
          googlePay: {
              gatewayMerchantId: "8ac7a4ca73522ba8017353bdfb9b0639"
          }
      }

   3. In a production environment, in the JavaScript, add your merchant ID
      JavaScript Test

      var wpwlOptions = {
          googlePay: {
              gatewayMerchantId: "8ac7a4ca73522ba8017353bdfb9b0639",
              merchantId: "your_merchantId"
          }
      }

📘

Google Merchant ID per URL

The Google Merchant ID is approved for your website only. If you use it on another URL, then Google Pay will display with a "Something went wrong" message and an OR_BIBED_11 error. And you will not be able to process payments.

For all Google Pay options in the CardCorp gateway, see Google Pay options for custom checkout.

How to go live

After you test your integration thoroughly in the test environment, to go live do the following steps.

1. Replace the test URLs and credentials with production ones.
2. Perform at least one test with a live card. For this test, you can use a product with a low price.

📘

Test cards

Do not use test cards in the live environment or live cards in the test environment