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.

📘
CardCorp merchant account
The custom checkout is supported by the CardCorp merchant account. 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.

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.

Create your product in the BillPro UI. See Create your product catalogue.
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, add the product, customer, and so on, then set the following attributes.

Set the create_checkout attribute to true.
Set the invoice_id, which is your unique merchant identifier for the order. This should be around 10 alphanumeric characters.
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.

Here is an example 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}"
  }
}
'

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": "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"
        },
    ...
}

From the order response, you should also save the value of the id of the order. To display the payment iframe, you will need the value of the integrity parameter.

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 checkoutId and the integrity as part of the JavaScript to define the checkout.

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

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

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.
Request that Apple Pay be enabled in BillPro with CardCorp gateway.
Host the certificate at localhost.
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.

Apply for your Google Merchant ID for your website.
Request that Google Pay is enabled in BillPro with CardCorp gateway.
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
```
var wpwlOptions = {
    googlePay: {
        gatewayMerchantId: "8ac7a4ca73522ba8017353bdfb9b0639"
    }
}
```
3. In a production environment, in the JavaScript, add your merchant ID
```
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.