In this guide, we are going to help you test BBVA’s APIs using the REST Postman API tool. This follows on from our Quickstart guide, where we explain how to register at BBVA API_Market and create your first app.

There are two different ways for you to test the operation of the APIs that have the Sandbox available:

– Through the console that you will find in the technical documentation of the APIs that have it available.

– Using API calling tools.

Next we’re going to see how to make calls to an API that requires two-legged authentication, to an API that requires three-legged authentication and we’ll explain the concept of OTP – One-Time Password.

Consult the API’s technical documentation to find out if the API you are going to use requires two-legged or three-legged authentication.

To make an API call with two-legged authentication, you must first obtain an access_token and then make the API call with the obtained access_token.

Remember that you must have created an application in BBVA API_Market with an API that requires two-legged authentication, such as, Loans Auto.

Get access_token

Once inside Postman, we must enter the following parameters:

· URL: https://connect.bbva.com/token?grant_type=client_credentials
· Method: POST

Headers:

· Authorization: Basic CREDENTIALS
· Content-Type: application/json

To obtain the value of the CREDENTIALS field we must convert to base64 (www.base64encode.org) the concatenation of appID, “:” and Secret OAuth, i.e.: appID:Secret OAuth.

To get appID and Secret OAuth, go into your app detail.

Example :

· appID = app.mx.pProd001
· Secret OAuth = R$Xm@…j6f1x@3

If we convert the string app.mx.pProd001:R$Xm@…j6f1x@3 to base64, the result is: YXBwLm14LnBQcm9kMDAxOlJA4oCmajZmMXhAMw==

So the header parameters are as follows:

· Authorization: Basic YXBwLm14LnBQcm9kMDAxOlJA4oCmajZmMXhAMw==
· Content-Type: application/json

This call returns a json of like this:

{
"access_token": "eyJhbGciOiJSU0EtT0FFUCIsInppcCI6IkRFRiIsImVuYyI6IkExMjhHQ00ifQ.fjdmI--zqhzDOyAGCDLivxhgdBZ2UqpvYetUch4qZ7H8k4ipm9bNcsXarvNGMlcX7TSCtnNd9r9yDmGdWyqZC-5Ymox-HWGuuZgtzG8k0Z9Gw6b1S5SbnXgH2zDiUMTVR6afBE7xpX0pII6D0IOfhzoCZ4g1iBbJ6ypkKJFw1f8IOY6ds4U6J4Kcq23KemjI0R5NNxRxP6X7cTDy9eQWkgh97iKKdJaBAgxf7MXfSEKpBabw9Ag5jHNDRF7KCjkCgmZoqjnfxuaJj5y_MdwR2SuuWj572KPME-OymiLAdza_Ul-zLjt8mnWnWSxFoMiMzk2pAio25pkwje5em6B1BA.XsvVLUkjhZQNAFCU.pMiWtSb1FO1rtQowW8G5iZ6jEMe2op-GZ2IuLDOrvj4bzqwnoo6hJB9FMLrZqEn9PCKlFUeZsspbNtrsUZqetO8F05Aw8vtQV_zEzf4ZACBLZ1kqQ5H2SG3YrKtYtobJDjvS2_08UWpflKjjAJhfUSkYndPBpc1fCeDsQoxSyVUc28ExMQXqh6QNuWaADmuvNgdyLvTGys5jUPw44mlegmDihIn3Hbx1ZgRk7zbzsB6qkY18jm44_cE2OgvPx3dcmk7UQkj-spSuxcYna3h80zSnZkjqdeQJ0NiKxA.zfgdS3NuvAHa9TUivYuAbA",
"token_type": "jwt",
"expires_in": 3599,
"scope": "Accounts_SBX Customers_SBX Loans_SBX Locations_SBX"
}

The access_token the service returns to us will be used in the API call.

Calling an API with the access_token obtained

For example, we call the merchant service of API Auto Loan:

· URL: https://apis.bbvabancomer.com/loans-auto-sbx/v1/
· Method: GET

Headers:

· Authorization: jwt access_token (the access_token obtained in the previous call)
· Content-Type: application/json

Example :

· Authorization: jwt eyJhbG….UivYuAbA
· Accept: application/json

This call returns a json of like this:

{"result": {"code": 200,"info": "OK"},"data": {"merchant": {"id": "10444","name": "GENERICA","addresses": [{"streetName": "OLMO 117 ","interiorNumber": "1","exteriorNumber": "117","state": {"id": "DF","name": "CIUDAD DE MEXICO"},"zipCode": "04030","neighborhood": "BARRIO SAN LUCAS","municipality": "COYOACAN","country": "MX"}],"manager": {"firstName": "virtual72","middleName": "F&I","lastName": "F&I"},"brands": [{"id": "78","name": "GENERICA"}]}}}

To call an API with three-legged authentication, we first need the code that is used to obtain an access_token, and then we make the API call with the obtained access_token. This code is valid for a specific user and for a limited time.

Remember that you must have created an application in BBVA API_Market with an API that requires three-legged authentication available, such as Customers.

Get code needed to access_token. BBVA Connect

It is necessary that when calling these APIs, the Sandbox connect is previously invoked indicating the redirect_url field. In other words, the address the client returns to after authentication. Remember that you need to have that same address set up in your app.

You can check it in your app’s advanced settings.

As an example of redirect_url we suggest you use the following URL: https://static.bbvaapimarket.com/resources/retail/callback/index.html

First we call from the browser to the following URL:
https://connect.bbva.com/sandboxconnect?client_id=APP_ID&response_type=code&redirect_uri=REDIRECT_URL

Where APP_ID is the id of the configured app (for example, app.bbva.Prod001) and REDIRECT_URL is the redirect_url configured in the advanced options of your application.

The browser will load the BBVA Connect screen where it will display the username and password of any of the Sandbox users. In the API documentation there are several test users/passwords, e.g.:

· Username: 00000034B
· Password: 123456

After entering a correct username and password, the Scopes acceptance screen will appear, authorizing the application for the required services.

The acceptance process ends by loading a page showing the code that you can copy directly. Note that this code expires after 30 seconds, so this is the time you have to obtain the access_token described in the following point.

Get access_token with the obtained code

To get the acces_token, we must access Postman and set up the call following the same steps described in the “Get access_token” section of this guide.

All we need to change is the URL:
https://connect.bbva.com/token?grant_type=authorization_code&redirect_uri=REDIRECT_URL&code=RECEIVED_CODE

Where REDIRECT_URL is the one we have configured in the application and CODE_OBTAINED is the code we have obtained in the previous point.

With the access_token obtained in the previous point, we set up a call in Postman with the following parameters:

· URL: https://apis.bbva.com/customers-sbx/v1/me-basic
· Method: GET

Headers:

· Authorization: jwt ACCESS_TOKEN
· Accept: application/json

{ "access_token": "eyJhbGciOiJSU0EtT0FFUCIsInppcCI6IkRFRiIsImVuYyI6IkExMjhHQ00ifQ.TI2wrGU73CKqLpQv-reFkDBx_rhBlvJ_Mqe4D5TDqGetVvX-sXdL0ghj3USaEkgc880pWONDxI68inv89sMF6OOErs5Fj-xNwwyO5MR1l0nXG10Apsp7PXX34YFZU-QiqDZL9dbn6R0QJH7RSNY79LQhKFKJvBbacayiP-jYjug3hwyAj5jaAKMzx-yDCgIEVKTgbC9IiOrcnLFL3AWG6W_pzBdlfxtctKN6mJyJtuk5p30kbCJf6PBHbCdC7VFE67A8p-knw4w0x62Q6hgpX1AfTsAczhDU6oOGNr6xpnOiOVfQ3qHgv-RT9pkqswvhfoEJf_6Y6Oqjje3C0k3L0Q.3WYfyQs3oCRNdiaY.fpqF4GdlUkZdCTH0hNjhaV6pmo2xtalCYYg7CfG9cSq-HkZ0Eu9fd7CkFTS8zL9fZ1BJep_uBXEXpQGwNn0uTmgMIFMyTH71rChNdfvqx6IwhU3hQ8umnuSu0ITOYVndJBBTdzZC3mxfColvLwA7jZWd49VYzFDyVuZtRM2AMIk0TanitUJrAcn6ceSpt8FCuBA1Mdc5J21u3zxs8HcY_GgjZi5MDO0vn39aRIuM10AVyYuUyDy3P_Vqt9toSyBScidn225hXXcBSNmArWYR50Wmt9CtNW43IZGD33UzcUYM1sZrm8GxYhUt1baby0qWsybhnK3BMzPmK5GJlXNdjiVAMHkQi7275n4hVP7Z5k4Csz1Kc4owvRZlTLdoPYPQ0_5WbWgw1mk3oWb2nPt6JPUU-vT7m6tyONKf44CfNz_87wDhjadU5eg0MU1TrrSjq9JOxaxP.TqE_WnfFxn-bo_JOcJNSOw", "token_type": "jwt", "refresh_token": "eyJhbGciOiJSU0EtT0FFUCIsInppcCI6IkRFRiIsImVuYyI6IkExMjhHQ00ifQ.O3R95eVCoWe04xDeAKJj1EhBzTQoGeKGQRmlw4uJisKQDBjcPrIOEggMZYiqtORqFVLhwvsiZV2Mp229Rb1LwMVGt5DwEEtd94TISQ4toQfX30w8sPImgw_WarLAZ2_qh1Yie7JiDGSucIuV8yxixzYOOS8y_5chflD7URsSfyaMc4C2xvAH5wRP_n899btUbmd6gYwcx9bOTBk5vA5EQg8yTxBPaBbUrjkehbfN0P5v6RAkU8rRGYHAniKCKG2l3Dxt4q2lRvMJqLnHKorY0hB_aXP3S6ziwRpBqd2QqAlnBeHL5-8nMO1lN4r4lu-jY2ELhcGKvF-QkOBjc_TsJg.Mw6InT_Q126l61R3.mrPMmmKBLTLnkmx0BFl76ylzQ3rAf6nzRYdM3sBM-v_S-v2ZcC0yL0_fmM-u1GrQWp_5W0UA4EBSxo0mUMyM26OCqSfG96o5o31fVDErn7DdYMfPnFyXjLB8gBVcLoqxjDj0iJz0wnYe-PvmTLFKZGqGXn7G5wAK5D5ZoUrx9I5o1_LkGNTnL4ZUtrG76x1JfFPosER-Bku7Uoy84l_SjlB1KSOk93DPFBBSAv7cpLte06CiZ41KvgmM_nk950dLV7hsuFhy9w7AA7PKtfYfrGXjWnY1eHj7Eo0Uhb9ZUpcOnnZpZyRmBtmeIlcigCkC9CInnFSilOTO39cIhl-VGT4Jlymtf1yLCYVyDF6KXUCRoZMFeT_M_8K03GD6wJ0uj23kLK01yLxTuz9tm05p4wo8wjFtvs5y_J-ixdTaPC5ir-W-ZfGJ--RoY5zfKqSGzgG1mtYERK3DvVzM0wRYXqz1FhzpvnqBtp81rLaAmNDiVAGJq6t5jan3kPSftwuLfQFmwAGU-fttxmA1ALzPXyFFO1hmjdOayKVHSz2IUtVDoPN9YLJjf8j4LAUhI5ZSJEM.qNWCMNovgd0l_E1DmV3Jfw", "expires_in": 3599, "scope": "card-notifications-sbx_full paymentsTransfersList_sbx accounts_detail_full_sbx_1 paystats_sbx_test paymentsTransfer_execution_sbx_1 cardsV2_detail_full_sbx_1 loanpreapprovedsimulation_sbx card_transactions_sbx atms_sbx cards_detail_basic_sbx_2 data_manager_sbx loanpreapproved_sbx event-generator-sbx_full notifications-sbx_full paymentsTransferOrders_execution_sbx_1 paymentsTransfersMobileCash_sbx account_transactions_sbx customers_full_sbx_1", "refresh_expires_in": 43199 }

OTP (you can read more about this term and other technical concepts in our glossary) is an acronym for a one-time password. This password is generated to validate an action and will only be valid for that action. In this section we clearly summarize, using an example, the steps to follow in order to make a transfer through an API that requires an OTP.

Get code needed to access_token. BBVA Connect

We need to follow the steps indicated in this guide in the “Obtain code needed to order access_token BBVA Connect” and “Obtain access_token with the code obtained” sections. In the first section we’ll get a code, in the second section that code is used to get the access_token.

First API call

We make a first call to the Customers API (within Customers we use Me Full as an example). In this call we use the access_token obtained in the previous point as a parameter of the headers.

We set up the call in Postman:

· URL: https://apis.bbva.com/customers-sbx/v1/me-full
· Method: GET

Headers:

· Authorization: jwt access_token
· Accept: application/json
· Content-Type: application/json

This call returns a json with a 428 response type, with the information “Second factor required”, a ticket that we use in the next section and a new token that we call token_2.

Validate token_2

We have to validate the token that we obtained in the previous step. This token is the OTP key, and it is used to validate the transaction that we defined in the previous call.

To validate the token_2 we access the browser and enter the following URL:
https://connect.bbva.com/otp?ticket=TICKET&back_url=OTP_URL

Within this URL we replace the following fields:

· TICKET: we enter the ticket code we have in the previous Postman.
· OTP_URL: we have to use the OTP URL that is configured in the application we have created in the Quickstart guide.

The browser response to this URL is a screen that explains what the API is intended to do, in this case, get the full information about a bank customer. The user would receive an SMS with a verification code that should be entered in the field provided. As we are in a test environment, no SMS is sent and any value of 4 numbers entered in the field is accepted.

Once the code is sent, we will see the browser response in the URL. We will see the OTP URL with the ticket we have entered and the result of the Query: http:s3-eu-west-1.amazonaws.com/openp-clientapi-prod-eu-west-1/public/callback/index.html?ticket=TICKET&result=OK

Second API call

After validating token_2, we use it to make the second API call. In this case, we repeat the same operation described in the First API Call section, but using token_2 instead of the access_token.

· URL: https://apis.bbva.com/customers-sbx/v1/me-full
· Method: GET

Headers:

· Authorization: jwt token_2
· Accept: application/json
· Content-Type: application/json

When the call succeeds, the result is a json with code 201 200 indicating that data collection was successful.

{"result": {"code": 200,"info": "OK"},"data": {"firstName": "Carmen","surname": "Rodriguez","secondSurname": "Rodriguez","sex": "FEMALE","birthdate": "1970-08-19","email": "caop@mailinator.com","userId": "930ffbcb6be59758990076c356ecb88694ffcacaa7047383e6c0ea565b600a12","addresses": [{"id": "00001","zipcode": "28001"}],"identityDocument": [{"type": "NATIONALID","number": "000000034B"}]}}