This tutorial describes the process to create a single-payment order with the BillPro API. We assume you have already worked through Get started with the BillPro API.

In the BillPro UI
1. Create a user for the integration and get the Api Token.
2. If your user has access to more than one profile (which is not recommended), then obtain the identifier of the profile you will use. If you have more than one profile, you must supply the profile_id as a query parameter in each request.
3. Create a product. Get the ID of the product from the UI.
Create a customer with the UI or CSV upload in the UI (or see Tutorial - Create a customer with the BillPro API. Get the customer ID from the UI or the customer id from the API.

There is a different data object for each of the BillPro Purchase types. Here is an example of a minimal data object to create a single payment order.

{
  "order": {
    "create_checkout": false,
    "invoice_id": "W58XGHF",
    "currency": "EUR",
    "customer_id": 42,
    "order_products": [
      {
        "product_id": 7
      }
    ]
  }
}

And here is another example of data objects to create a single payment order with two products and a custom checkout (available for CardCorp merchants only). For more details , see Integrate with custom checkout and payment iframe.

{
  "order": {
    "currency": "EUR",
    "customer_id": 42,
    "invoice_id": "W58XGHF",
    "create_registration": true,
    "redirect_url": "https://billing.example/success",
    "failed_redirect_url": "https://billing.example.com/failed",
    "note": "This is a test order",
    "create_checkout": true,
    "order_products": [
      {
        "product_id": 7,
        "qty": 2,
        "amount": "20.00",
        "discount_amount": "10",
        "fee_amount": "20"
      },
      {
        "product_id": 6,
        "qty": 1,
        "amount": 20,
        "discount_amount": 0,
        "fee_amount": 0
      }
    ]
  }
}

For more examples, see the reference pages for each order type.

Copy an example data object to create an order and modify it with your data.
1. You must enter a currency.
2. For the customer_id, enter the id of the customer.
3. A single payment order can have more than one product. The order_products array can contain multiple single-payment product objects. For the product_id, enter the id of the product.
4. We recommend that you enter your own merchant invoice_id to identify the order.
5. You should enter a value for create_checkout, which can be true or false.
  1. If you have a CardCorp merchant account and you want to integrate with a custom checkout, set create_checkout to true. Otherwise, set it to false.
  2. If you are creating a custom checkout, for redirect_url and failed_redirect_url, enter redirect links for approved or declined transactions. You can also get the transaction result from the redirect. Or you can use the payment gateway webhook.

Here is an example of a minimal request to create a single payment order.

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": {
    "create_checkout": false,
    "invoice_id": "W58XGHF",
    "currency": "EUR",
    "customer_id": 42,
    "order_products": [
      {
        "product_id": 7
      }
    ]
  }
}
'

Copy a request and replace {api_token} with your API Token
Send your request to the endpoint URL for the type of order you want to create. For example, for a single payment order in the test system, use https://staging.bill.pro/api/v1/orders/create_single_order.
1. If your API user has access to more than one profile (which is not recommended), you must send the profile_id as a query parameter with your request. For example, https://staging.bill.pro/api/v1/orders/create_single_order?profile_id=156.
Check the response code, which should be 201 for a successful request. Here is an example of response data from a successful request. If there is an error in the body object, the response code will be 422.

{
  "payload": {
    "order": {
      "id": 586,
      "invoice_id": "ABCDEF123456789",
      "customer_id": "DC19894EB7",
      "initial_amount": "0.0",
      "note": null,
      "total_discount_amount": "0.0",
      "total_fee_amount": "0.0",
      "total_tax_amount": "0.0"
    },
    "customer": {
      "id": 42,
      "first_name": "Vernon",
      "last_name": "Smiley",
      "email": "damon@00web.com",
      "date_of_birth": "1981-08-31",
      "phone": "+447444705044",
      "billing_address": {
        "street": "4 Glenn Close",
        "city": "Manchester",
        "postal_code": "M1 8GG",
        "state": "",
        "country": "GB"
      }
    },
    "product": [
      {
        "id": 599,
        "order_id": 586,
        "product_id": 7,
        "name": "Insurance Plan",
        "description": null,
        "qty": 1,
        "amount": "0.0",
        "created_at": "2024-05-14T15:17:57.282Z",
        "updated_at": "2024-05-14T15:17:57.282Z",
        "product_discount_id": null,
        "product_fee_id": null,
        "product_tax_id": null,
        "discount_amount": "0.0",
        "fee_amount": "0.0",
        "tax_amount": "0.0",
        "subtotal_amount": "0.0"
      }
    ],
    "checkout": {},
    "payment_link": "https://staging.bill.pro/checkout/586/78GxXmqaV7gtH44PWQSeG3fL",
    "redirect_url": null,
    "register_card": false
  },
  "status": 201
}

Send a payment link or display a checkout and receive the payment

Follow these steps after you create an order.

From the order response, get the payment link from the order and send it to your customer. Or if you have a CardCorp merchant account, you could Integrate with custom checkout and payment iframe.
If you are using the custom checkout and the user doesn't complete their transaction within 25 minutes, the checkout expires, so renew it with the Renew Checkout request. If you are using the BillPro payment link integration, the checkout automatically renews when the customer clicks on the payment link.
The customer enters their payment details in the BillPro secure payment iframe that is connected directly to the payment gateway. The customer can then access the order portal to view their order and billing history, manage cards for recurring payments, and download invoices, receipts, and credit notes.
You can now manage the order in the BillPro UI or using the API. For example, for orders with recurring payments, you can manage billing events in the API, and you can also pause and resume subscription orders, and cancel all types of orders.