Prepare a purchase

Preparing a purchase involves telling us the amount to collect for the purchase and a bit about the customer so that we can streamline the customer's registration on our system.

A successful request will return a purchase_id and payment_url. The purchase_id is for your record keeping and the payment_url must be provided to the customer. If you are unsure how to use the provided payment_url to complete the purchase please get in touch with Boodle.

Request Interface

interface PreparePurchase {
    amount: number; // min 100, max 20000
    customer_reference?: string; // optional, max length 10

    first_name?: string; // optional
    last_name?: string; // optional
    id_number?: string; // optional, if provided must be a valid SA ID Number
    cellphone?: string; // optional, if provided must be a valid SA Phone Number (remove country code (+27) for best results)
    email?: string; // optional, if provided must be a valid Email Address

    street_and_number?: string; // optional
    complex?: string; // optional
    suburb?: string; // optional
    city?: string; // optional
    province?: string; // optional
    postal_code?: number; // optional

    custom_field_1?: string; // optional
    custom_field_2?: string; // optional
    custom_field_3?: string; // optional
    custom_field_4?: string; // optional
    custom_field_5?: string; // optional
}

info

The customer_reference should not be your unique purchase reference. We format the reference to conform to our reference format automatically and the formatted reference will be returned to you in the response. If you require a unique reference to consolidate the purchase please use one of the custom fields. These will not be shown to the customer and will be returned to you in all correspondence.

Example Request

var axios = require('axios');
var data = JSON.stringify({
  "amount": 150,
  "customer_reference": "REFERENCE",

  "first_name": "Jane",
  "last_name": "Doe",
  "id_number": "3708014800085",
  "cellphone": "0834050182",
  "email": "user@boodle.co.za",
  "street_and_number": "Street 54",
  "complex": "The Complex",
  "suburb": "Suburb",
  "city": "Johannesburg",
  "province": "Gauteng",
  "postal_code": "2101",

  "custom_field_1": "CUSTOM",
  "custom_field_2": "CUSTOM",
  "custom_field_3": "CUSTOM",
  "custom_field_4": "CUSTOM",
  "custom_field_5": "CUSTOM"
});

var config = {
  method: 'post',
  url: 'http://localhost:8080/api/v1/merchant-purchase/prepare',
  headers: {
    'Authorization': 'Bearer {{secret}}',
    'Content-Type': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Example Response

{
    "message": "Successfully prepared purchase",
    "success": true,
    "data": {
        "payment_url": "https://bnpl.boodle.co.za/p/XucFwStT",
        "purchase_id": 10151256,
        "echo_back": {
            "amount": 150,
            "customer_reference": "REFERENCE",
            "first_name": "Jane",
            "last_name": "Doe",
            "id_number": "3708014800085",
            "cellphone": "0834050182",
            "email": "user@boodle.co.za",
            "street_and_number": "Street 54",
            "complex": "The Complex",
            "suburb": "Suburb",
            "city": "Johannesburg",
            "province": "Gauteng",
            "postal_code": "2101",
            "custom_field_1": "CUSTOM",
            "custom_field_2": "CUSTOM",
            "custom_field_3": "CUSTOM",
            "custom_field_4": "CUSTOM",
            "custom_field_5": "CUSTOM"
        }
    }
}

We recommend that you store the purchase_id on your system for recon purposes. Present the payment_url page to your customer in a way that suits your application and specific requirements.