Home
Release Notes
Home
Release Notes
Linkedin
  1. Services
  • Baladâ„¢ Gateway Documentation đŸ“–
  • Get Started
  • Authorization
  • Responses
  • Go Live!
  • FAQs
  • APIs
    • Authentication
      • Token
    • Core
      • Exchange rate
        • Exchange Rates
      • Balance
        • Get Current Balance
      • Secrets
        • Generate Secret
        • Delete Secret
        • Get Secrets
    • Link
      • Sandbox Testing Guide
      • Error Codes
      • Transaction Lifecycle V2
      • Lookups
        • Purposes List
        • Sources List
        • Banks List
        • Relations
      • Transactions
        • Create transaction
        • Update transaction
        • Cancel transaction
        • Get transaction status V2
        • Transactions List
        • Export Transactions List
        • Validate Account
        • Request Sender Document Upload URL
      • Reconciliation
        • Reconciliation
      • Quotations
        • Create Quotation
    • Bills
      • Services
        • Categories
          GET
        • Providers
          GET
        • Services
          GET
        • Service Configurations
          GET
        • available currencies
          GET
      • Payments
        • Inquiry
        • Fees
        • Confirm Payment
        • Bill Payment List
  • Webhooks
    • Link.Transaction.StatusUpdateV2
  1. Services

Service Configurations

GET
/bills/services/{serviceId}/configurations
The "Get Service Configuration" API retrieves integration steps and details for a specific service based on the provided service ID. This API is essential for developers integrating bill payment services into their applications, as it provides detailed information about the required steps and parameters for each stage of the payment process.
Request Params
SI NoParameterLengthTypeMandatoryRemarks
1serviceId4StringYUnique identifier of the service
can be retreived from the Get Services endpoint
Response Params
SI NoParameterRemarks
1service_idUnique identifier for each service
2service_nameName of the service
Integration Steps
Provides developers with detailed information about each integration step.

StepNameDescriptionEndpointHTTP Method
1InquiryFacilitates bill inquiry process./bills/payments/inquiry/POST
Allows users to retrieve bill information.
Provides details about a specific bill item.
2FeesCalculates fees associated with bill payment./bills/payments/fees/POST
3Confirm PaymentConfirms payment transaction./bills/payments/confirm/POST
Provides details about the transaction.

Example:#

Step 1: Inquiry#

Description: Facilitates the inquiry process for bill payments. Allows users to retrieve information about a specific bill item by providing the account number associated with the bill.
Input Parameters:
ParameterTypeDescriptionValidations
account_numberStringThe account number provided by the user.Required, max length: 50 chars
Output Parameters:
ParameterTypeDescription
account_numberStringThe account number provided by the user.
balad_reference_numberIntegerReference number uniquely identifying the bill.
amount_egpDecimalAmount of the bill in Egyptian currency.
fees_egpDecimalFees associated with the inquiry/bill.
total_amount_egpDecimalTotal amount of the bill in Egyptian currency.
foreign_amountDecimalAmount of the bill in foreign currency.
partner_foreign_feesDecimalPartner applied fees in foreign currency.
total_foreign_amountDecimalTotal amount of the bill in foreign currency.
foreign_currency_codeStringISO currency code of the foreign currency.
display_messageStringDescription message of the request.
is_fees_calculatedBooleanFlag indicating if the fees are calculated.

Step 2: Fees#

Description: Calculates fees associated with the bill payment request.
Input Parameters:
ParameterTypeDescription
balad_reference_numberIntegerReference number uniquely identifying the bill item
Output Parameters:
Same as Step 1

Step 3: Confirm Payment#

Description: Confirms payment transaction and provides transaction details.
Input Parameters:
ParameterTypeDescription
balad_reference_numberIntegerReference number uniquely identifying the bill item
Output Parameters:
Same as Step 1, plus:
ParameterTypeDescription
transaction_numberStringUnique identifier of the created transaction.
transaction_timeDateTimeTime of the created transaction.
powered_byStringService provider powering the payment.
reference_numberStringReference number created on the service provider powering the payment.

Request

Authorization
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
Path Params

Header Params

Request Code Samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://gateway-sandbox.balad.tech/bills/services/1000/configurations' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json'

Responses

đŸŸ¢200Success
application/json
Bodyapplication/json

Example
{
    "data": {
        "service_id": 1000,
        "service_name": "We Home Internet Bills",
        "integration_steps": [
            {
                "step_number": 1,
                "step_name": "Inquiry",
                "url": "bills/payments/inquiry",
                "http_method": "POST",
                "input_parameters": [
                    {
                        "validations": {
                            "is_required": true,
                            "scale": null,
                            "min_value": null,
                            "max_value": null,
                            "min_length": 10,
                            "max_length": 10,
                            "starts_with": [
                                "02",
                                "03",
                                "045",
                                "046",
                                "013",
                                "015",
                                "016",
                                "028",
                                "040",
                                "043",
                                "047",
                                "048",
                                "049",
                                "050",
                                "055",
                                "057",
                                "062",
                                "063",
                                "064",
                                "065",
                                "068",
                                "0663",
                                "082",
                                "084",
                                "086",
                                "088",
                                "0693",
                                "093",
                                "0952",
                                "096",
                                "0972"
                            ],
                            "is_numeric": true
                        },
                        "key": "account_number",
                        "type": "String",
                        "description": "The account number provided by the user facilitates bill inquiries and payments like(phone number ,landline ,etc..)"
                    },
                    {
                        "validations": {
                            "is_required": true,
                            "scale": null,
                            "min_value": null,
                            "max_value": null,
                            "min_length": 3,
                            "max_length": 3,
                            "starts_with": null,
                            "is_numeric": null
                        },
                        "key": "foreign_currency_code",
                        "type": "String",
                        "description": "ISO currency code of the foreign currency applied on the request"
                    }
                ],
                "output_parameters": [
                    {
                        "key": "account_number",
                        "type": "String",
                        "description": "The account number provided by the user facilitates bill inquiries and payments like(phone number ,landline ,etc..)"
                    },
                    {
                        "key": "balad_reference_number",
                        "type": "Int",
                        "description": "Reference number that uniquely identify bill item"
                    },
                    {
                        "key": "amount_egp",
                        "type": "Decimal",
                        "description": "Amount of bill to be inquiry or paid in egyptian currency"
                    },
                    {
                        "key": "fees_egp",
                        "type": "Decimal",
                        "description": "Fees of the inquiry request/bill"
                    },
                    {
                        "key": "total_amount_egp",
                        "type": "Decimal",
                        "description": "Total amount of the inquired request and to be paid in egyptian currency"
                    },
                    {
                        "key": "foreign_amount",
                        "type": "Decimal",
                        "description": "Amount of bill to be inquiry or paid in foreign currency"
                    },
                    {
                        "key": "partner_foreign_fees",
                        "type": "Decimal",
                        "description": "Partner applied fees in foreign currency"
                    },
                    {
                        "key": "total_foreign_amount",
                        "type": "Decimal",
                        "description": "Total amount of the inquiries request and to be paid in foreign currency"
                    },
                    {
                        "key": "foreign_currency_code",
                        "type": "String",
                        "description": "ISO currency code of the foreign currency applied on the request"
                    },
                    {
                        "key": "display_message",
                        "type": "String",
                        "description": "Description message of the request"
                    },
                    {
                        "key": "is_fees_calculated",
                        "type": "Boolean",
                        "description": "Flag represents if the fees is calculated for the request"
                    }
                ]
            },
            {
                "step_number": 2,
                "step_name": "Fees",
                "url": "bills/payments/fees",
                "http_method": "POST",
                "input_parameters": [
                    {
                        "validations": {
                            "is_required": true,
                            "scale": null,
                            "min_value": null,
                            "max_value": null,
                            "min_length": null,
                            "max_length": null,
                            "starts_with": null,
                            "is_numeric": null
                        },
                        "key": "balad_reference_number",
                        "type": "Int",
                        "description": "Reference number that uniquely identify bill item"
                    }
                ],
                "output_parameters": [
                    {
                        "key": "account_number",
                        "type": "String",
                        "description": "The account number provided by the user facilitates bill inquiries and payments like(phone number ,landline ,etc..)"
                    },
                    {
                        "key": "balad_reference_number",
                        "type": "Int",
                        "description": "Reference number that uniquely identify bill item"
                    },
                    {
                        "key": "amount_egp",
                        "type": "Decimal",
                        "description": "Amount of bill to be inquiry or paid in egyptian currency"
                    },
                    {
                        "key": "fees_egp",
                        "type": "Decimal",
                        "description": "Fees of the inquiry request/bill"
                    },
                    {
                        "key": "total_amount_egp",
                        "type": "Decimal",
                        "description": "Total amount of the inquired request and to be paid in egyptian currency"
                    },
                    {
                        "key": "foreign_amount",
                        "type": "Decimal",
                        "description": "Amount of bill to be inquiry or paid in foreign currency"
                    },
                    {
                        "key": "partner_foreign_fees",
                        "type": "Decimal",
                        "description": "Partner applied fees in foreign currency"
                    },
                    {
                        "key": "total_foreign_amount",
                        "type": "Decimal",
                        "description": "Total amount of the inquiries request and to be paid in foreign currency"
                    },
                    {
                        "key": "foreign_currency_code",
                        "type": "String",
                        "description": "ISO currency code of the foreign currency applied on the request"
                    },
                    {
                        "key": "display_message",
                        "type": "String",
                        "description": "Description message of the request"
                    },
                    {
                        "key": "is_fees_calculated",
                        "type": "Boolean",
                        "description": "Flag represents if the fees is calculated for the request"
                    },
                    {
                        "key": "amount_in_cash",
                        "type": "Decimal",
                        "description": "Amount paid by customer in cash"
                    }
                ]
            },
            {
                "step_number": 3,
                "step_name": "Confirm Payment",
                "url": "bills/payments/confirm",
                "http_method": "POST",
                "input_parameters": [
                    {
                        "validations": {
                            "is_required": true,
                            "scale": null,
                            "min_value": null,
                            "max_value": null,
                            "min_length": null,
                            "max_length": null,
                            "starts_with": null,
                            "is_numeric": null
                        },
                        "key": "balad_reference_number",
                        "type": "Int",
                        "description": "Reference number that uniquely identify bill item"
                    }
                ],
                "output_parameters": [
                    {
                        "key": "account_number",
                        "type": "String",
                        "description": "The account number provided by the user facilitates bill inquiries and payments like(phone number ,landline ,etc..)"
                    },
                    {
                        "key": "balad_reference_number",
                        "type": "Int",
                        "description": "Reference number that uniquely identify bill item"
                    },
                    {
                        "key": "amount_egp",
                        "type": "Decimal",
                        "description": "Amount of bill to be inquiry or paid in egyptian currency"
                    },
                    {
                        "key": "fees_egp",
                        "type": "Decimal",
                        "description": "Fees of the inquiry request/bill"
                    },
                    {
                        "key": "total_amount_egp",
                        "type": "Decimal",
                        "description": "Total amount of the inquired request and to be paid in egyptian currency"
                    },
                    {
                        "key": "foreign_amount",
                        "type": "Decimal",
                        "description": "Amount of bill to be inquiry or paid in foreign currency"
                    },
                    {
                        "key": "partner_foreign_fees",
                        "type": "Decimal",
                        "description": "Partner applied fees in foreign currency"
                    },
                    {
                        "key": "total_foreign_amount",
                        "type": "Decimal",
                        "description": "Total amount of the inquiries request and to be paid in foreign currency"
                    },
                    {
                        "key": "foreign_currency_code",
                        "type": "String",
                        "description": "ISO currency code of the foreign currency applied on the request"
                    },
                    {
                        "key": "display_message",
                        "type": "String",
                        "description": "Description message of the request"
                    },
                    {
                        "key": "is_fees_calculated",
                        "type": "Boolean",
                        "description": "Flag represents if the fees is calculated for the request"
                    },
                    {
                        "key": "transaction_number",
                        "type": "String",
                        "description": "Unique identifier of the created transaction on balad"
                    },
                    {
                        "key": "transaction_time",
                        "type": "DateTime",
                        "description": "Time of the created transaction on balad"
                    },
                    {
                        "key": "powered_by",
                        "type": "String",
                        "description": "The service provider powering the payment"
                    },
                    {
                        "key": "reference_number",
                        "type": "String",
                        "description": "Reference number that created on the service provider powering the payment"
                    },
                    {
                        "key": "amount_in_cash",
                        "type": "Decimal",
                        "description": "Amount paid by customer in cash"
                    }
                ]
            }
        ]
    },
    "errors": null
}
Previous
Services
Next
available currencies
Built with