Integrate with custom checkout and payment iframe

When you create an order with the BillPro API, we recommend you use BillPro's checkout. But you can also send your customer to your own checkout and integrate the payment iframe in your website.

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

To integrate with the payment iframe do the following steps.

Create an order with the API

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

1. Create your product in the BillPro UI. See Create your product catalogue.
2. You can create the customer with the API, see Create customer, or in the UI. When you create a customer, in the API:
   1. BillPro assigns a unique system identifier to your customer, which is the id attribute you must use to identify the customer in the order.
   2. BillPro also assigns a unique merchant customer_id to identify the customer. To create and modify the merchant customer_id, use the BillPro UI.

Use BillPro's API to create an order. In the order object, in addition to the product, customer, and so on, 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 that you use 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.

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

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

From the API response, get the checkout id and the form_action values.

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": "8854a5c81bde316486906c37de7e1bd18297382d@2022-05-13 13:55:50 +0000",
           "timestamp": "2022-05-19 07:46:32+0000",
           "ndc": "A587E14EAC826B6063FBB294693891DF.uat01-vm-tx02",
           "id": "A587E14EAC826B6063FBB294693891DF.uat01-vm-tx02",
           "form_action": "https://test.billing.gg/checkout/174/mXCJ25FsxLaMwJjmVCjZ5rWd"
    ...
}

From the order response, you should also save the id of the order.

For the full API documentation, see Orders.

Display the payment iframe

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

Enter the checkout id as part of the JavaScript to define the checkout.

<script src="https://eu-test.oppwa.com/v1/paymentWidgets.js?checkoutId={id}"></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 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.