How to create an order with the BillPro API

In this tutorial we will create a single-payment order with the BillPro API.

1. In the BillPro UI, create an integration user and get the Api Token.
2. In the BillPro UI, create a product. Get the ID of the product from the UI.
3. 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.
4. Copy a sample order data object and modify it with your data, and make sure to do these steps.
   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. The redirect result will also enable you to determine the transaction result.
5. In the request, remember to replace {api_token} with your API Token
6. 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.billing.gg/api/v1/orders/create_single_order
7. Here is an example to create a minimal request for a single payment order.
   Minimal order request

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

   
   
8. And here is an example to create a standard request for a single payment order with a checkout.
   Standard order request

   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": 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
         }
       ]
     }
   }
   '

9. Check the response code, which should be 200 for a successful request. Here is an example of response 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.billing.gg/checkout/586/78GxXmqaV7gtH44PWQSeG3fL",
       "redirect_url": null,
       "register_card": false
     },
     "status": 201
   }

Display the checkout and receive the payment

Follow these steps after you create an order.

1. From the order response, get the payment link from the order and send it to your customer, or get the checkout ID and display the checkout on your website.
2. 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.
3. The customer enters their payment details in BillPro's secure payment iframe that is connected directly to the payment gateway.
4. 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 subscription orders, and cancel all types of orders.