How to create an order with the BillPro API

This guide 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, create a user for the integration and get the Api Token.
In the BillPro UI, create a product. Get the ID of the product from the UI.
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.

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. 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 createCheckout 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://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": {
    "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://test.bill.pro/api/v1/orders/create_single_order
Check the response code, which should be 200 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": "[email protected]",
      "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://test.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.
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.