We are using cookies in our website in order to offer better service to you. You allow us to use cookies by continuing to use our internet website. You can reach the detailed information on cookies from our Privacy Policy and Cookies Policy.
X
Home > Api Products > Bill Payments

Bill Payments

Description

​This API is used to payments of bills.​​

Institutions

​This API is used to retrieve institutions list.​

How it Works

Sample Request

GET /api/isbank/v1/bill-institutions
Headers:
X-IBM-client-id: {YOUR_CLEINT_ID} 
X-IBM-client-secret: {YOUR_CLEINT_SECRET} 
Authorization: Bearer {access_token}
Content-Type: application/json

Services of Institutions

This API is used to retrieve service list of institutions.​​

How it Works

Sample Request

GET /api/isbank/v1/bill-institution-services/413
Headers:
X-IBM-client-id: {YOUR_CLEINT_ID} 
X-IBM-client-secret: {YOUR_CLEINT_SECRET} 
Authorization: Bearer {access_token}
Content-Type: application/json

Queries

This API is used to query bill details for the given parameters.​

How it Works

Parameters

This part needs to be in body of the request.​

Sample Parameters for Single Stage Query

{
    "service_id": 413,
    "query_code": "301", 
    "query_flow_id": "",
    "basic_input_values": [ 
        {
            "name": "subscriberno", 
            "value": "978675" 
        }
    ],
    "customer_ip": "1.1.1.1"
}

Sample Parameters for Multi Stage Query

First Query

{
    "service_id": 10059, 
    "query_code": "100", 
    "query_flow_id": "",
    "basic_input_values": [ 
        {
            "name": "CpRelated",
            "value": "6465565"
        }
    ],
    "selected_input_values": [ 
        {
            "name": "ListField", 
            "selected_item": { 
                "key": "T",
                "value": "Tavşanlı"
            }
        }
    ],
    "customer_ip": "1.1.1.1"
}

Second Query

{
    "service_id": 10059, 
    "query_code": "301", 
    "query_flow_id": "74eff327-1c1d-4013-8cf1-22e9e79f5b97", 
    "basic_input_values": [
        {
            "name": "Subs",
            "value": "568456451"
        }
    ],
    "customer_ip": "1.1.1.1"
}

Sample Request

GET /api/isbank/v1/bill-payment-queries
Headers:
X-IBM-client-id: {YOUR_CLEINT_ID} 
X-IBM-client-secret: {YOUR_CLEINT_SECRET} 
Authorization: Bearer {access_token}
Content-Type: application/json

Validations

This API is used to validate payment request for the given parameters.​

How it Works

Parameters

This part needs to be in body of the request.​

Sample Parameters for Collectable Payment Validations

{
    "debtor_account_id": 43537304, 
    "collectable_id": 88043, 
    "amount": 60, 
    "currency_code": "TRY", 
    "debtor_use_of_overdraft": false,
    "debtor_use_of_sos": false,
    "service_id": 413, 
    "description": "Bill API Test",
    "customer_ip": "1.1.1.1"
}

Sample Parameters for Free Payment Validations

{
    "debtor_account_id": 43537304,
    "amount": 30,
    "currency_code": "TRY", 
    "debtor_use_of_overdraft": false,
    "debtor_use_of_sos": false,
    "service_id": 4, 
    "description": "Bill API Test",
    "basic_input_values": [ 
        {
            "name": "KartNo",
            "value": "55555555555"
        }
    ],
    "selected_input_values": [ 
        {
            "name": "OnBehalfOf",
            "selected_item": {
                "key": "K",
                "value": "Kendi Adıma"
            }
        }
    ],
    "complex_input_values": [ 
        {
            "name": "Address",
            "basic_input_field_values": [ 
                {
                    "name": "Country",
                    "value": "TÜRKİYE"
                },
                {
                    "name": "Province",
                    "value": "İSTANBUL"
                },
                {
                    "name": "District",
                    "value": "TUZLA"
                },
                {
                    "name": "Quarter",
                    "value": "TUTOM"
                },
                {
                    "name": "AddressText",
                    "value": "B-1"
                }
            ]
        }
    ],
    "customer_ip": "1.1.1.1"
}

Sample Request

GET /api/isbank/v1/bill-payment-validations
Headers:
X-IBM-client-id: {YOUR_CLEINT_ID} 
X-IBM-client-secret: {YOUR_CLEINT_SECRET} 
Authorization: Bearer {access_token}
Content-Type: application/json

Payments

​This API is used to execute bill payment.​

How it Works

Parameters

This part needs to be in body of the request.

Sample Parameters for Collectable Payments

{
    "idempotency_key": "daab3151-0727-4c3e-a5dc-ec1935f40258", 
    "debtor_account_id": 43537304, 
    "collectable_id": 88043,
    "amount": 60, 
    "currency_code": "TRY", 
    "debtor_use_of_overdraft": false, 
    "debtor_use_of_sos": false, 
    "service_id": 413, 
    "description": "Bill API Test", 
    "customer_ip": "1.1.1.1"
}

Sample Parameters for Free Payment 

{
    "idempotency_key": "daab3151-0727-4c3e-a5dc-ec1935f40258", 
    "debtor_account_id": 43537304,
    "amount": 30,
    "currency_code": "TRY", 
    "debtor_use_of_overdraft": false,
    "debtor_use_of_sos": false,
    "service_id": 4, 
    "description": "Bill API Test",
    "basic_input_values": [ 
        {
            "name": "KartNo",
            "value": "55555555555"
        }
    ],
    "selected_input_values": [ 
        {
            "name": "OnBehalfOf",
            "selected_item": {
                "key": "K",
                "value": "Kendi Adıma"
            }
        }
    ],
    "complex_input_values": [ 
        {
            "name": "Address",
            "basic_input_field_values": [ 
                {
                    "name": "Country",
                    "value": "TÜRKİYE"
                },
                {
                    "name": "Province",
                    "value": "İSTANBUL"
                },
                {
                    "name": "District",
                    "value": "TUZLA"
                },
                {
                    "name": "Quarter",
                    "value": "TUTOM"
                },
                {
                    "name": "AddressText",
                    "value": "B-1"
                }
            ]
        }
    ],
    "customer_ip": "1.1.1.1"
}

Sample Request

GET /api/isbank/v1/bill-payments
Headers:
X-IBM-client-id: {YOUR_CLEINT_ID} 
X-IBM-client-secret: {YOUR_CLEINT_SECRET} 
Authorization: Bearer {access_token}
Content-Type: application/json



Sample Response

Sample Response for Institutions

{
    "data": [
        {
            "id": 19556,
            "name": "Yemeksepeti",
            "services": [
                {
                    "id": 413,
                    "name": "Yemeksepeti"
                }
            ]
        }
        {
            "id": 21441,
            "name": "ZONGULDAK TİCARET VE SANAYİ ODASI",
            "services": [
                {
                    "id": 10212,
                    "name": "ZONGULDAK TİCARET VE SANAYİ ODASI"
                }
            ]
        }
    ]
}

Sample Response for Queryable Services

{
    "data": {
        "service_id": 413,
        "payment_features": {
            "collectable_payment_allowed": true,
            "free_payment_allowed": false,
            "collectable_payment_options": {
                "allowed_if_payment_order_exist": false,
                "exceed_payment_allowed": false,
                "partial_payment_allowed": false
            }
        },
        "free_collection_query_specs": {
            "predefined_collectables": [
                {
                    "main_info": []
                }
            ],
            "input_fields": [
                {
                    "required": false,
                    "items": []
                }
            ],
            "display_info": []
        },
        "collectable_query_specs": {
            "input_fields": [
                {
                    "business_type": "SUBSCRIPTION_INFO",
                    "description": "yemeksepeti.com üyelik numaranızı giriniz.",
                    "group_index": 0,
                    "label": "Üye Numarası (yemeksepeti.com)",
                    "name": "subscriberno",
                    "required": false,
                    "parameter_length": {
                        "max": 6,
                        "min": 6
                    },
                    "items": [],
                    "parameter_type": "Numeric"
                }
            ],
            "input_method": {
                "query_code": "301",
                "type": "Query"
            },
            "display_info": []
        },
        "amount_input": {
            "amount_limitations": {
                "amount_range": []
            },
            "decimal_fraction_allowed": false
        }
    }
}

Sample Response for Unqueryable Services

{
    "data": {
        "id": 4,
        "payment_features": {
            "collectable_payment_allowed": false,
            "free_payment_allowed": true,
            "collectable_payment_options": {
                "allowed_if_payment_order_exist": false,
                "exceed_payment_allowed": false,
                "partial_payment_allowed": false
            }
        },
        "free_collection_query_specs": {
            "input_method": {
                "type": "Query",
                "query_code": "301" 
            },
            "predefined_collectables": [
                {
                    "main_info": []
                }
            ],
            "input_fields": [
                {
                    "label": "Kart No", 
                    "name": "KartNo",
                    "required": false,
                    "parameter_length": {
                        "max": 16,
                        "min": 16
                    },
                    "parameter_type": "Numeric",
                    "items": [],
                    "regex": "^[0-9]+$",
                    "sample": "1111222233334444",
                    "description": "Lütfen Barokart numaranızı giriniz.",
                    "group_index": 0
                },
                {
                    "label": "Kimin Adına",
                    "name": "OnBehalfOf",
                    "required": false,
                    "items": [
                        {
                            "key": "K",
                            "value": "Kendi adıma"
                        },
                        {
                            "key": "B",
                            "value": "Başkası adına"
                        }
                    ],
                    "description": "Lütfen Başkası adına/Kendi adıma seçiniz",
                    "group_index": 0,
                    "input_fields": [
                        {
                            "items": []
                        }
                    ]
                },
                {
                    "label": "Adres", 
                    "name": "Address",
                    "required": false,
                    "items": [],
                    "description": "Lütfen adres alanını giriniz",
                    "group_index": 3,
                    "input_fields": [
                        {
                            "description": "Lütfen il alanını doldurunuz.",
                            "label": "İl",
                            "name": "Province",
                            "parameter_length": {
                                "max": "20",
                                "min": "1"
                            },
                            "parameter_type": "Alphanumeric",
                            "required": "true",
                            "ui_hint": "CUSTOMER_ADDRESS_PROVINCE",
                            "items": []
                        },
                        {
                            "description": "Lütfen ilçe alanını doldurunuz.",
                            "label": "İlçe",
                            "name": "District",
                            "parameter_length": {
                                "max": "20",
                                "min": "1"
                            },
                            "parameter_type": "Alphanumeric",
                            "required": "false",
                            "ui_hint": "CUSTOMER_ADDRESS_DISTRICT",
                            "items": []
                        }
                    ]
                }
            ],
            "display_info": []
        },
        "collectable_query_specs": {
            "input_fields": [
                {
                    "required": false,
                    "items": []
                }
            ],
            "display_info": []
        },
        "amount_input": {
            "selected_amount_limitation": {
                "currency_code": "TRY"
            },
            "amount_limitations": {
                "amount_range": [
                    {
                        "currency_code": "TRY"
                    }
                ]
            },
            "decimal_fraction_allowed": true
        }
    }
}

Sample Responses for Single Stage Query

{
    "service_id": 413, 
    "query_flow_id": "b02e61f6-e4a4-4901-ba9b-09a650f12c19",
    "amount_input": {
        "decimal_fraction_allowed": false,
        "amount_limitations": {
            "amount_range": []
        }
    },
    "next_query_input_fields": {
        "input_fields": [
            {
                "items": []
            }
        ],
        "input_method": {
            "type": "Payment"
        },
        "display_info": []
    },
    "collectables": [ 
        {
            "amount": { 
                "currency_code": "TRY",
                "equivalent_ccy": "UNSPECIFIED",
                "equivalent_qty": 0,
                "amount": 60
            },
            "main_info": [ 
                {
                    "business_type": "SUBSCRIPTION_INFO",
                    "key": "subscriberno",
                    "label": "Üye Numarası (yemeksepeti.com)",
                    "value": "978675",
                    "child_fields": []
                },
                {
                    "business_type": "SUBSC_NAME",
                    "key": "SubscriberName",
                    "label": "Abone Adı/Unvanı",
                    "value": "FATURA",
                    "child_fields": []
                },
                {
                    "business_type": "COLLECTABLE_BIZ_ID",
                    "key": "CollectableIdentifier",
                    "label": "Fatura Numarası",
                    "value": "APIODEME005",
                    "child_fields": []
                },
                {
                    "business_type": "DUE_DATE",
                    "key": "DueDate",
                    "label": "Son Ödeme Tarihi",
                    "value": "28.09.2020",
                    "child_fields": []
                },
                {
                    "business_type": "COLLECTABLE_AMOUNT_DUE",
                    "key": "DueAmount",
                    "label": "Tutar",
                    "value": "60,00 TRY",
                    "child_fields": []
                },
                {
                    "business_type": "COLLECTABLE_AMOUNT_MIN",
                    "key": "MinAmount",
                    "label": "Minimum Fatura Tutarı",
                    "value": "60,00 TRY",
                    "child_fields": []
                },
                {
                    "business_type": "COLLECTABLE_AMOUNT_MAX",
                    "key": "MaxAmount",
                    "label": "Maksimum Fatura Tutarı",
                    "value": "60,00 TRY",
                    "child_fields": []
                }
            ],
            "max_amount": {
                "currency_code": "TRY",
                "equivalent_ccy": "UNSPECIFIED",
                "equivalent_qty": 0,
                "amount": 60
            },
            "min_amount": { 
                "currency_code": "TRY",
                "equivalent_ccy": "UNSPECIFIED",
                "equivalent_qty": 0,
                "amount": 60
            },
            "collectable_id": 88065, 
            "payable": true 
        }
    ]
}

Sample Responses for Multi Stage Query

First Response

{
    "service_id": 10059, 
    "query_flow_id": "187be10b-d10a-4e7d-9a3c-ed1d7569fc37
    "amount_input": {
        "amount_limitations": {
            "amount_range": []
        }
    },
    "next_query_input_fields": { 
        "input_fields": [
            {
                "business_type": "SUBSCRIPTION_INFO",
                "description": "Giriniz",
                "group_index": 0,
                "label": "Abone adı",
                "name": "Subs", //Alan adı
                "required": "false",
                "items": [],
                "parameter_length": {
                    "max": 10,
                    "min": 1
                },
                "parameter_type": "Numeric"
            }
        ],
        "input_method": {
            "query_code": "301", 
            "type": "Query"
        },
        "display_info": [
            {
                "field_type": "TEXT",
                "value": "One piece is Real! "
            },
            {
                "label": "resolved",
                "value": "Cicek-001"
            }
        ]
    },
    "collectables": [
        {
            "main_info": [
                {
                    "child_fields": []
                }
            ]
        }
    ]
}

Second Response

{
    "service_id": 10059, 
    "query_flow_id": "74eff327-1c1d-4013-8cf1-22e9e79f5b97",
    "amount_input": {
        "decimal_fraction_allowed": false,
        "amount_limitations": {
            "amount_range": []
        }
    },
    "next_query_input_fields": {
        "input_fields": [
            {
                "items": []
            }
        ],
        "input_method": {
            "type": "Payment"
        },
        "display_info": []
    },
    "collectables": [ 
        {
            "amount": { 
                "currency_code": "TRY",
                "equivalent_ccy": "UNSPECIFIED",
                "equivalent_qty": 0,
                "amount": 50
            },
            "main_info": [ 
                {
                    "business_type": "SUBSCRIPTION_INFO",
                    "key": "Subs",
                    "label": "Abone adı",
                    "value": "568456451",
                    "child_fields": []
                },
                {
                    "business_type": "SUBSC_NAME",
                    "key": "SubscriberName",
                    "label": "Abone Adı/Unvanı",
                    "value": "Monkey D. Luffy",
                    "child_fields": []
                },
                {
                    "business_type": "COLLECTABLE_BIZ_ID",
                    "key": "CollectableIdentifier",
                    "label": "Fatura Numarası",
                    "value": "Meat5000x",
                    "child_fields": []
                },
                {
                    "business_type": "COLLECTABLE_AMOUNT_DUE",
                    "key": "DueAmount",
                    "label": "Tutar",
                    "value": "50,00 TRY",
                    "child_fields": []
                },
                {
                    "business_type": "COLLECTABLE_AMOUNT_MIN",
                    "key": "MinAmount",
                    "label": "Minimum Fatura Tutarı",
                    "value": "50,00 TRY",
                    "child_fields": []
                },
                {
                    "business_type": "COLLECTABLE_AMOUNT_MAX",
                    "key": "MaxAmount",
                    "label": "Maksimum Fatura Tutarı",
                    "value": "50,00 TRY",
                    "child_fields": []
                },
                {
                    "business_type": "RESERVED_FIELD",
                    "key": "ToBeResolved",
                    "label": "Ek Bilgi",
                    "value": "Cicek-001",
                    "child_fields": []
                }
            ],
            "max_amount": { 
                "currency_code": "TRY",
                "equivalent_ccy": "UNSPECIFIED",
                "equivalent_qty": 0,
                "amount": 50
            },
            "min_amount": { 
                "currency_code": "TRY",
                "equivalent_ccy": "UNSPECIFIED",
                "equivalent_qty": 0,
                "amount": 50
            },
            "collectable_id": 88252, 
            "payable": true, 
            "detail_info": {
                "data": "Breakfast : 20, Lunch : 30",
                "data_format": "Text"
            }
        }
    ]
}


Validations

Sample Response

{
    "data": {
        "overdraft_amount": 0,
        "sos_used": false, 
        "currency_code": "TRY", 
        "result": "Success", 
        "validation_results": [],
        "amount": 30, 
        "validation_token": "H20006452437" 
    }
}


Payments

Sample Response

{
    "data": { 
        "amount": 60, 
        "overdraft_amount": 0, 
        "sos_used": false, 
        "currency_code": "TRY", 
        "payment_type": "CP_COLLECTION",
        "execution_date": "2020-09-28T17:49:49.5776691+03:00",
        "collection_id": 2503749
    }
}