Authorization

VakıfBank APIs use two different methods of OAuth 2.0 protocol for authentication and authorization.


Authorization Code Method

This method requires customer authentication. It is often used to call APIs containing customer data.

In the Authorization Code method, with the authorization of the customer, a customer-specific token information is transmitted to the 3rd party application.


1. Obtaining Authorization Code

As a result of the call made to the Authorization address with the following information, the customer login screen is opened. After the customer login, authorization code information is sent to the routing address of the application as a result of the customer's authorization to the application for the relevant transactions.

Retail Address:

GET: https://apigw.vakifbank.com.tr:8443/auth/oauth/v2/authorize

Corporate Address:

GET: https://apigw.vakifbank.com.tr:8443/auth/oauth/v2/commercial/authorize

Parameter Description

client_id

Mandatory You can obtain it from the Auth tab on your application page.

response_type

It is a fixed value. "code" information must be sent.

scope

It contains the scope information of the APIs for which authorization is requested. It can be obtained from the API page to use.

state

Optional. It refers to the information to be sent to the forwarding address.

redirect_uri

It is the address information to which the created authorization code information will be directed.

resource

API Plan information. "sandbox" for testing, "production" for real environment must be called for.

Customer Login

In this method, customer logins are made with an internet banking password. In the authorization call made from a 3rd party application, the internet banking login screen is opened and the customer is expected to authorize the application after logging in.

Test Clients

Testing can be performed in the sandbox environment with the following customer numbers.

Customer Number User code Password OTP
445806749637 - 112233 123456
445805642686 - 112233 123456
445805642712 51163450904 112233 123456

2. Transmitting the Authorization Code

The authorization code created after the customer authorization can be sent to the forwarding address transmitted from the 3rd party application in the following ways.

Parameter Description

code

In case the customer approves, it is the field containing the authorization code information.

state

It contains the state information sent in the request.

error

Information containing the error if the customer refuses to authorize.

3. Getting Access Token

Access token is obtained by using the authorization code transmitted to the forwarding address.

Address:

POST: https://apigw.vakifbank.com.tr:8443/auth/oauth/v2/token

Parameter Description

grant_type

authorization_code information must be sent.

code

Authorization Code information obtained from /authorize address must be sent.

redirect_uri

It is the forwarding address information to which the token will be forwarded.


Response Message Parameters

Parameter Name Description

access_token

It is the token information generated as a result of authorization.

token_type

Bearer

refresh_token

It is the refresh token information that can be used for token renewal.

expires_in

It is the token validity period in seconds.

scope

It is the authorized scope information.

4. Getting Access Token with Refresh Token

If the API is requested to be called when the access token expires, the user must purchase the access token again. If there is a previously obtained refresh token for APIs authorized with Authorization Code, access token can be obtained without re-login processes by using this method.

Address :

POST: https://apigw.vakifbank.com.tr:8443/auth/oauth/v2/token

Parameter Description

grant_type

refresh_token information should be sent.

refresh_token

It is the refresh token information that can be used for token renewal.

client_id

It is the API Key information on the application page.

client_secret

It is the API Secret information on the application page.

scope

It is the authorized scope information.

Reply Message

Parameter Name Description

access_token

Outputs a token enabling access.

token_type

Bearer

refresh_token

It is the refresh token information that can be used for token renewal.

expires_in

It is the token validity period in seconds.

scope

It is the scope information that is authorized.


Client Credentials Method

This method is used in open APIs that do not require customer authentication or in private APIs prepared between the institution and the bank.  

Address :

POST: https://apigw.vakifbank.com.tr:8443/auth/oauth/v2/token

Request Message

Parameter Name Description

client_id

It is the API Key information on the application page.

client_secret

It is the API Secret information on the application page.

grant_type

client_credentials should be sent.

scope

It contains the scope information of the APIs for which authorization is requested. It can be obtained from the API page to use.

Reply Message

Parameter Name Description

access_token

Outputs an access token.

token_type

Bearer

expires_in

It is the token validity period in seconds.

scope

It is the scope information that is authorized.


B2B Credentials Method

This method is used in the one-to-one integrations of APIs containing customer data between the commercial customer and the bank.  

Address :

POST: https://apigw.vakifbank.com.tr:8443/auth/oauth/v2/token

Request Message

Parameter Name Description

client_id

It is the API Key information on the application page.

client_secret

It is the API Secret information on the application page.

grant_type

b2b_credentials must be sent.

scope

It contains the scope information of the APIs for which authorization is requested. It can be obtained from the API page to use.

consentId

It is the consent number. It is transmitted by the relevant business unit.

Reply Message

Parameter Name Description

access_token

Outputs an access token.

token_type

Bearer

expires_in

It is the token validity period in seconds.

scope

It is the scope information that is authorized.