Electricity Purchase

You can integrate electricity bill payment purchase in these easy steps:

List the electricity providers
List the disco's products
Validate the customer details
Make payment

1. Get the List of Electricity Providers

Verb	URL
`GET`	`{{baseUrl}}/api/v1/bills/billers?category=electricity`

To start electricity bill payment, make an API call to the list billers endpoint to fetch all the electricity providers’ details on Anchor. If this is successful, you will receive a list of all electricity providers on Anchor:

curl --request GET \
     --url 'https://api.sandbox.getanchor.co/api/v1/bills/billers?category=electricity' \
     --header 'accept: application/json' \
     --header 'x-anchor-key: <API Key>'

{
  "data": [
    {
      "id": "168322497264225-anc_blr",
      "type": "Provider",
      "attributes": {
        "name": "Port-Harcourt Electricity PostPaid",
        "category": "electricity",
        "slug": "port_harcourt_electricity_postpaid"
      }
    },
    {
      "id": "168322497255823-anc_blr",
      "type": "Provider",
      "attributes": {
        "name": "Kano Electricity PostPaid",
        "category": "electricity",
        "slug": "kano_electricity_postpaid"
      }
    },
    {
      "id": "168322497246821-anc_blr",
      "type": "Provider",
      "attributes": {
        "name": "Kaduna Electricity PostPaid",
        "category": "electricity",
        "slug": "kaduna_electricity_postpaid"
      }
    },
    {
      "id": "168322497234820-anc_blr",
      "type": "Provider",
      "attributes": {
        "name": "Jos Electricity PostPaid",
        "category": "electricity",
        "slug": "jos_electricity_postpaid"
      }
    },
    {
      "id": "168322497225619-anc_blr",
      "type": "Provider",
      "attributes": {
        "name": "Ikeja Electricity PostPaid",
        "category": "electricity",
        "slug": "ikeja_electricity_postpaid"
      }
    },
    {
      "id": "168322497213917-anc_blr",
      "type": "Provider",
      "attributes": {
        "name": "Ibadan Electricity PostPaid",
        "category": "electricity",
        "slug": "ibadan_electricity_postpaid"
      }
    },
    {
      "id": "168322497202915-anc_blr",
      "type": "Provider",
      "attributes": {
        "name": "Enugu Electricity PostPaid",
        "category": "electricity",
        "slug": "enugu_electricity_postpaid"
      }
    },
    {
      "id": "168322497182614-anc_blr",
      "type": "Provider",
      "attributes": {
        "name": "Eko Electricity PostPaid",
        "category": "electricity",
        "slug": "eko_electricity_postpaid"
      }
    },
    {
      "id": "168322497169512-anc_blr",
      "type": "Provider",
      "attributes": {
        "name": "Abuja Electricity PostPaid",
        "category": "electricity",
        "slug": "abuja_electricity_postpaid"
      }
    },
    {
      "id": "168322497153511-anc_blr",
      "type": "Provider",
      "attributes": {
        "name": "Kano Electricity PrePaid",
        "category": "electricity",
        "slug": "kano_electricity_prepaid"
      }
    },
    {
      "id": "168322497139710-anc_blr",
      "type": "Provider",
      "attributes": {
        "name": "Kaduna Elec Prepaid",
        "category": "electricity",
        "slug": "kaduna_elec_prepaid"
      }
    },
    {
      "id": "16832249712719-anc_blr",
      "type": "Provider",
      "attributes": {
        "name": "Jos Electric Prepaid",
        "category": "electricity",
        "slug": "jos_electric_prepaid"
      }
    },
    {
      "id": "16832249711338-anc_blr",
      "type": "Provider",
      "attributes": {
        "name": "Ikeja Electric Prepaid",
        "category": "electricity",
        "slug": "ikeja_electric_prepaid"
      }
    },
    {
      "id": "16832249710137-anc_blr",
      "type": "Provider",
      "attributes": {
        "name": "Ibadan Electric Prepaid",
        "category": "electricity",
        "slug": "ibadan_electric_prepaid"
      }
    },
    {
      "id": "16832249708726-anc_blr",
      "type": "Provider",
      "attributes": {
        "name": "Harcourt Elec. Prepaid",
        "category": "electricity",
        "slug": "harcourt_elec_prepaid"
      }
    },
    {
      "id": "16832249707245-anc_blr",
      "type": "Provider",
      "attributes": {
        "name": "Enugu Electric Prepaid",
        "category": "electricity",
        "slug": "enugu_electric_prepaid"
      }
    },
    {
      "id": "16832249705614-anc_blr",
      "type": "Provider",
      "attributes": {
        "name": "Eko Electric Prepaid",
        "category": "electricity",
        "slug": "eko_electric_prepaid"
      }
    },
    {
      "id": "16832249694681-anc_blr",
      "type": "Provider",
      "attributes": {
        "name": "Abuja Electric Prepaid",
        "category": "electricity",
        "slug": "abuja_electric_prepaid"
      }
    }
  ],
  "meta": {
    "pagination": {
      "totalPages": 1,
      "number": 0,
      "size": 20,
      "total": 18
    }
  }
}

2. Get the Disco's Products

Verb	URL
`GET`	`{{baseUrl}}/api/v1/bills/billers/{billerId}/products`

Make the call to the list biller product endpoint and pass the billerId to fetch all the products of that provider. In the sample below, the id for Ikeja Electric Prepaid: 16832249705614-anc_blr has been passed.

When you list the biller product, note the slug and priceof the electricity product you want to purchase as you will use this in creating the electricity bill payment.

price - price of the of the electricity specified in the country’s lowest currency unit. Price for electricity is a range from the minimum amount 100 (which translates to N1) to the maximum amount 10000000 (which translates to N100,000.00).

billerId is the unique Id of the electricity provider on Anchor.

slug is the human readable identifier of the electricity product/plan. When you list a biller product you will see the product slug on each biller product.

curl --request GET \
     --url https://api.sandbox.getanchor.co/api/v1/bills/billers/16832249711338-anc_blr/products \
     --header 'accept: application/json' \
     --header 'x-anchor-key: <API Key>'

{
  "data": [
    {
      "id": "168322497124421-anc_bll_itm",
      "type": "Electricity",
      "attributes": {
        "price": {
          "type": "Range",
          "minimumAmount": 100,
          "maximumAmount": 10000000,
          "currency": "NGN"
        },
        "name": "PrePaid Bill Payment",
        "slug": "ikeja_electric_prepaid_prepaid_bill_payment"
      },
      "relationships": {
        "provider": {
          "data": {
            "id": "16832249711338-anc_blr",
            "type": "Provider"
          }
        }
      }
    }
  ]
}

3. Validate Customer Meter Number

Verb	URL
`GET`	`{{baseUrl}}/api/v1/bills/customer-validation/:billprovider_slug/:meterAccountNumber`

The Customer Validation endpoint allows you to verify the name associated with a bill product provider. This endpoint is useful for ensuring that the meter number provided by the customer is valid and correctly associated with the given provider.

Path Parameters

billprovider-slug: The unique identifier for the bill product provider. This should be replaced with the actual slug for the provider you are validating.
meterAccountNumber: The customer meter number you want to validate.

curl --location 'https://api.sandbox.getanchor.co/api/v1/bills/customer-validation/ikeja_electric_prepaid_prepaid_bill_payment/00007200000' \
--header 'x-anchor-key: <API Key>'

{
    "data": {
        "id": "0",
        "type": "CustomerDetail",
        "attributes": {
            "customerNumber": "00007200000",
            "customerName": "Ayofemi Uba"
        }
    }
}

4. Make Payment:

When you have identified the electricity bill you want to purchase, you can proceed to purchase the identified electricity plan.

Attribute	Description
`type`	The type for electricity bill payment is `Electricity`.
`amount`	This is the fixed amount of the electricity (specified in the currencies lowest denomination).
`meterAccountNumber`	The meter number for which the bill payment is being made, or the meter number to be recharged.
`phoneNumber`	The phone number of the validated customer.
`productSlug`	The slug of the product for which the payment is being made.
`reference`	The unique identifier of the transaction on your system.

You would need to pass the account id and type (Deposit or Subaccount) where this transaction will be initiated and charged from.

curl --request POST \
     --url https://api.sandbox.getanchor.co/api/v1/bills \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-anchor-key: <API Key>' \
     --data '
{
  "data": {
    "type": "Electricity",
    "attributes": {
      "meterAccountNumber": "04042404048",
      "phoneNumber": "2347012345678",
      "reference": "01234567898976",
      "productSlug": "ikeja_electric_prepaid_prepaid_bill_payment",
      "amount": 50000
    },
    "relationships": {
      "account": {
        "data": {
          "type": "DepositAccount",
          "id": "16922123768364-anc_acc"
        }
      }
    }
  }
}
'

{
  "data": {
    "id": "17007387937120-anc_bll",
    "type": "BillPayment",
    "attributes": {
      "reference": "01234567898976",
      "createdAt": "2023-11-23T11:26:33.734157",
      "amount": 50000,
      "phoneNumber": "2347012345678",
      "customerDetail": {
        "meterNumber": "04042404048"
      },
      "detail": {
        "provider": "Abuja Electric Prepaid",
        "product": "PrePaid Bill Payment",
        "token": "-757990035059747286"
      },
      "category": "electricity",
      "commissionAmount": 0,
      "status": "COMPLETED",
      "updatedAt": "2023-11-23T11:26:34.559003"
    },
    "relationships": {
      "account": {
        "data": {
          "id": "16922609921350-anc_subacc",
          "type": "DepositAccount"
        }
      },
      "customer": {
        "data": {
          "id": "16922123736510-anc_bus_cst",
          "type": "BusinessCustomer"
        }
      }
    }
  }
}

Receive webhook events

You will receive bills.initiated events once the bill payment is initiated. If the bill payment is success full, you will receive bills.successful event. If this payment is not successful, you will receive bills.failed event.

{
  "data": {
    "id": "1719830371921188-anc_et",
    "type": "bills.initiated",
    "attributes": {
      "createdAt": "2024-07-01T10:39:32"
    },
    "relationships": {
      "bill": {
        "data": {
          "id": "171983037175614-anc_bll",
          "type": "BillPayment"
        }
      },
      "account": {
        "data": {
          "id": "16922609921350-anc_subacc",
          "type": "DepositAccount"
        }
      },
      "customer": {
        "data": {
          "id": "16922123736510-anc_bus_cst",
          "type": "BusinessCustomer"
        }
      }
    }
  }
}

{
  "data": {
    "id": "1719830373002191-anc_et",
    "type": "bills.successful",
    "attributes": {
      "createdAt": "2024-07-01T10:39:33"
    },
    "relationships": {
      "bill": {
        "data": {
          "id": "171983037175614-anc_bll",
          "type": "BillPayment"
        }
      },
      "account": {
        "data": {
          "id": "16922609921350-anc_subacc",
          "type": "DepositAccount"
        }
      },
      "customer": {
        "data": {
          "id": "16922123736510-anc_bus_cst",
          "type": "BusinessCustomer"
        }
      }
    }
  }

You can use the support included functionality when listening to this bill payment event to retrieve other information such as the payment detail or customer detail that is related to this event.

Below is a sample of bills.successful event with included functionality for BillPayment

{
  "data": {
    "id": "1719830371921188-anc_et",
    "type": "bills.initiated",
    "attributes": {
      "createdAt": "2024-07-01T10:39:32"
    },
    "relationships": {
      "bill": {
        "data": {
          "id": "171983037175614-anc_bll",
          "type": "BillPayment"
        }
      },
      "account": {
        "data": {
          "id": "16922609921350-anc_subacc",
          "type": "DepositAccount"
        }
      },
      "customer": {
        "data": {
          "id": "16922123736510-anc_bus_cst",
          "type": "BusinessCustomer"
        }
      }
    }
  },
  "included": [
    {
      "id": "171983037175614-anc_bll",
      "type": "BillPayment",
      "attributes": {
        "reference": "0123456789ee8976",
        "createdAt": "2024-07-01T10:39:32",
        "amount": 50000,
        "phoneNumber": "2347012345678",
        "customerDetail": {
          "meterNumber": "04042404048"
        },
        "detail": {
          "provider": "Ikeja Electric Prepaid",
          "product": "PrePaid Bill Payment",
          "token": "-694607352826985382"
        },
        "category": "electricity",
        "commissionAmount": 0,
        "status": "COMPLETED",
        "updatedAt": "2024-07-01T10:39:33"
      },
      "relationships": {
        "account": {
          "data": {
            "id": "16922609921350-anc_subacc",
            "type": "DepositAccount"
          }
        },
        "customer": {
          "data": {
            "id": "16922123736510-anc_bus_cst",
            "type": "BusinessCustomer"
          }
        }
      }
    }
  ]
}

{
  "data": {
    "id": "1719830373002191-anc_et",
    "type": "bills.successful",
    "attributes": {
      "createdAt": "2024-07-01T10:39:33"
    },
    "relationships": {
      "bill": {
        "data": {
          "id": "171983037175614-anc_bll",
          "type": "BillPayment"
        }
      },
      "account": {
        "data": {
          "id": "16922609921350-anc_subacc",
          "type": "DepositAccount"
        }
      },
      "customer": {
        "data": {
          "id": "16922123736510-anc_bus_cst",
          "type": "BusinessCustomer"
        }
      }
    }
  },
  "included": [
    {
      "id": "171983037175614-anc_bll",
      "type": "BillPayment",
      "attributes": {
        "reference": "0123456789ee8976",
        "createdAt": "2024-07-01T10:39:32",
        "amount": 50000,
        "phoneNumber": "2347012345678",
        "customerDetail": {
          "meterNumber": "04042404048"
        },
        "detail": {
          "provider": "Ikeja Electric Prepaid",
          "product": "PrePaid Bill Payment",
          "token": "-694607352826985382"
        },
        "category": "electricity",
        "commissionAmount": 0,
        "status": "COMPLETED",
        "updatedAt": "2024-07-01T10:39:33"
      },
      "relationships": {
        "account": {
          "data": {
            "id": "16922609921350-anc_subacc",
            "type": "DepositAccount"
          }
        },
        "customer": {
          "data": {
            "id": "16922123736510-anc_bus_cst",
            "type": "BusinessCustomer"
          }
        }
      }
    }
  ]
}