Integrate with custom checkout and payment iframe

When you create an order with the BillPro API, we recommend you use the BillPro checkout. When you have a CardCorp merchant account, you can also send your customer to your own checkout and integrate the payment iframe in your website. You can also add Apple Pay and Google Pay to your custom checkout and the instructions for this are in a separate section at the end of the page.

📘
CardCorp merchant account
The custom checkout is supported for CardCorp merchant accounts only. With Stripe merchant accounts 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.

To integrate with the payment iframe, do the steps described below.

flowchart TB 
 CreateProduct[Create a product
in the UI] 
 CreateCustomer[Create a customer]
 CreateOrderAPI[Create an order
with checkout
request]
 CreateCheckout[Create checkout
on your website]
 AcceptPayment[Accept payment]
 CustomerRedirected[Customer redirected]
 CreateProduct --> CreateCustomer
 CreateCustomer --> CreateOrderAPI
 CreateOrderAPI --> CreateCheckout
 CreateCheckout --> AcceptPayment
 AcceptPayment --> CustomerRedirected

Create an order with the API

Before you create an order for the integration, create at least one product and at least one customer.

In the BillPro UI, create a product. Get the ID of the product from the UI. See Create your product catalogue .
Create a customer with the UI, API, or CSV upload in the UI. Get the customer ID from the UI or the customer id from the API. See Create customer, or in the UI.

Use the BillPro API to create an order. For the full BillPro API documentation, see Orders.

See the documentation for your order type, eg. Create single order. In the order object, add the product and customer, as described in the documentation.
Then, in the order object, set the attributes to integrate with the checkout:
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.
From the API response, save the following values:
1. the id of the order.
2. the id of the checkout.
3. the form_action parameter.
4. the integrity parameter.

Here is an example of a basic request to create an order with a checkout.

curl --request POST \
     --url https://test.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}"
  }
}
'

Here is an 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://test.bill.pro/checkout/1538/C2vNRYZAQFCkQ7ZkBadxpoQv"
        },
    ...
}

Display the payment iframe

To display the payment iframe in your website, you will need to run a script to include the gateway checkout widget. Enter the BillPro checkout attributes as described here.

As part of the JavaScript to define the checkout, enter the checkout checkoutId and the integrity .

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

In the HTML definition of the iframe, for the form_action, set the BillPro link from the checkout form_action. This will update the order in BillPro.
```
<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

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 use the payment gateway webhook, you can identify the transaction by the BillPro merchant order_id and merchant customer_id. The merchant customer ID is part of a customer object with more attributes. BillPro also uses its own unique system identifier for the order, called the ZUID, which is sent as the merchant transaction ID.

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

For more details, see BillPro payment gateway webhook.

Configure Apple Pay and Google Pay in the custom checkout

If the acquirer of your CardCorp merchant account supports Google Pay and Apple Pay, you can configure these wallets in the custom checkout.

Apple Pay

To configure Apple Pay do these steps.

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.
Ask BillPro Support to enable Apple Pay in BillPro with CardCorp gateway.
Host the certificate at localhost.
Enable Apple Pay in the checkout HTML as part of the data-brands by adding the APPLEPAY option.

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

Google Pay

To configure Google Pay do these steps.

Apply for your Google Merchant ID at the Google Developers merchant integration site.
Ask BillPro Support to enable Google Pay in BillPro with CardCorp gateway.
Enable Google Pay in the checkout
1. In the HTML as part of data-brands by adding the GOOGLEPAY option.
2. In the JavaScript by adding your merchant ID.
```
var wpwlOptions = {
    googlePay: {
        gatewayMerchantId: "8ac7a4ca73522ba8017353bdfb9b0639"
    }
}
```

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