Home
APIs
How It Works
FAQ
Contact Us
Login
Register
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 Reques

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 Reques​

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 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

Sample Response​

​

Validations​

This API is used to validate payment request for the given parameters.
How it Works

Parameters​

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 Request​

POST /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
​

Bill Payments​

This API lists the customer's paid bills between the entered dates.
Sample Request by Entered Date Range
GET /api/isbank/v1/bill-payments?start_date={start_date}&end_date={end_date}

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


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 Response

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


​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 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
    }
}​


Sample Response
{
    "data": [
        {
            "refund_state": "Refunding",
            "refundable": "false",
            "refund": "true",
            "collectable_id": "233861",
            "amount": {
                "currency_code": "TRY",
                "equivalent_ccy": "TRY",
                "equivalent_qty": "20.00",
                "amount": "20.00"
            }
        },
        {
            "refund_state": "Refunding",
            "refundable": "false",
            "refund": "true",
            "collectable_id": "233906",
            "amount": {
                "currency_code": "TRY",
                "equivalent_ccy": "TRY",
                "equivalent_qty": "25.00",
                "amount": "25.00"
            }
        },
        {
            "refund_state": "Refunding",
            "refundable": "false",
            "refund": "true",
            "collectable_id": "233907",
            "amount": {
                "currency_code": "TRY",
                "equivalent_ccy": "TRY",
                "equivalent_qty": "348.42",
                "amount": "348.42"
            }
        },
        {
            "refund_state": "Refunding",
            "refundable": "false",
            "refund": "true",
            "collectable_id": "233947",
            "amount": {
                "currency_code": "TRY",
                "equivalent_ccy": "TRY",
                "equivalent_qty": "20.00",
                "amount": "20.00"
            }
        },
        {
            "refund_state": "Refunding",
            "refundable": "false",
            "refund": "true",
            "collectable_id": "233909",
            "amount": {
                "currency_code": "TRY",
                "equivalent_ccy": "TRY",
                "equivalent_qty": "20.00",
                "amount": "20.00"
            }
        },
        {
            "refund_state": "Refunding",
            "refundable": "false",
            "refund": "true",
            "collectable_id": "233912",
            "amount": {
                "currency_code": "TRY",
                "equivalent_ccy": "TRY",
                "equivalent_qty": "20.00",
                "amount": "20.00"
            }
        },
        {
            "refund_state": "Refunding",
            "refundable": "false",
            "refund": "true",
            "collectable_id": "234162",
            "amount": {
                "currency_code": "TRY",
                "equivalent_ccy": "TRY",
                "equivalent_qty": "277.35",
                "amount": "277.35"
            }
        }
    ]
}​

© 2018 Türkiye İş Bankası A.Ş. All rights reserved.
© 2018 Türkiye İş Bankası A.Ş. All rights reserved.