Quick Reference

This page contains some quick references to the developers.

URL Sandbox

https://dev.openbank.bancobest.pt/sandbox

URL Production

https://api.openbank.bancobest.pt/

Endpoint Initiate

Description

Endpoint that gives access to the authentication and consentment page. A needed step in order to use the '/Token' endpoint and access the operations.

Allowed Roles

PSP_AI
PSP_AS
PSP_IC
PSP_PI

Endpoint POST

https://dev.openbank.bancobest.pt/sandbox/api/v2/OAuth/Initiate

Request Header

Variable	Example Value	Description	Mandatory?
Authorization	OAuth oauth_consumer_key=0f4c0...	Basic OAuth authorization schema. See "How to Access API"	Yes
Certificate	9dFpJUCnQcwe80aAOHx7YWYlqisICXNnVSKiaiA9vGO8YnzlZoJcUVPJ/rZ68X8FD==	Public key of the certificate. See "How to Access API".	Yes
redirect_uri	myapplication.com/loginReturn	Endpoint to redirect the user too after the operation	Yes
response_type	200	Response type in case of a success. 200 by default	No
state	something_here	Value that can be used freely by the application that will be returned after the operation.	Yes

Response Body (JSON format)

Variable	Example Value	Description
LoginUrl	(see example below)	URL of the autentication and consent page

Example of Response Body.

json
{
    "LoginUrl": "https://www.bancobest.pt/ptg/start.swe?SWECmd=InvokeMethod&SWEService=BEST+Process+Web+Request+NS&SWEMethod=runService&serviceName=BEST+PSD2+Web&serviceMethod=StartLogin&login_token=f191ba310f111399c6dd5966fc2cd27e176bd8b91582f1df771a47531cf83226&state=none2&oper_id=1-BJN2KC"
}

Redirect URL: (GET parameters on the URL)

Variable	Example Value	Description
code	d007359368f94215b4e0bda6aa039563	Temporary code used to retrieve the Access Token
oper_id	1-BQMM39	ID of the consentment operation
state	something_here	Value that can be used freely by the application and it will be returned after the login.

myapplication.com/loginReturn?code=d007359368f94215b4e0bda6aa039563&state=something_here&oper_id=1-BQMM39

Endpoint Token

Allowed Roles

PSP_AI
PSP_AS
PSP_IC
PSP_PI

Endpoint POST

https://dev.openbank.bancobest.pt/sandbox/api/v2/OAuth/Token

Request Header

Variable	Example Value	Description	Mandatory?
Authorization	OAuth code=d007359368f94215b4e0bda6aa039563,oauth_consumer_key=0f4c0...	OAuth auhtorization schema with temporary code. See "How to Access API"	Yes
Certificate	9dFpJUCnQcwe80aAOHx7YWYlqisICXNnVSKiaiA9vGO8YnzlZoJcUVPJ/rZ68X8FD==	Public key of the certificate. See "How to Access API".	Yes

Request Body

NO REQUEST BODY

Response Body: (JSON Format)

Variable	Example Value	Description
access_token	b7633a278bae420dabc91df952d83532	Access Token to be used in the OAuth schema for the API operations.
expires_in	1648166400	Timestamp representing the time the retrieved Access Token is to expire.

Example of Response Body.

json
{
    "access_token": "b7633a278bae420dabc91df952d83532",
    "expires_in":1648166400
}

Endpoint CheckOperationByID

Description

Endpoint that provides extra information based on some specific operations. These operations are currently returned after the redirect by the '/Initiate' and '/InitiatePayment' endpoints.

Allowed Roles

PSP_AS
PSP_IC
PSP_PI

Endpoint POST

https://dev.openbank.bancobest.pt/sandbox/api/v2/Operation/CheckOperationByID/{ID}

Request Header

Variable	Example Value	Description	Mandatory?
Authorization	OAuth access_token=c7622a278bae420dabc91df952d83582,oauth_consumer_key=0f4c0...	Basic OAuth auhtorization schema with the access token. See "How to Access API"	Yes
Certificate	9dFpJUCnQcwe80aAOHx7YWYlqisICXNnVSKiaiA9vGO8YnzlZoJcUVPJ/rZ68X8FD==	Public key of the certificate. See "How to Access API".	Yes

Request Body

NO REQUEST BODY

Response Body

Example from an operation generated from the api/v2/OAuth/Initiate endpoint :

json
{
    "outputData": {
        "oper_id": "1-BQOCJB",
        "error_code": null,
        "error_desc": null,
        "redirect_url": "http://httpbin.org/get?oper_id=1-BQOCJB&status=INIT",
        "home_iban": null,
        "oper_type": "0",
        "oper_sub_type": null,
        "oper_status": null,
        "entity_name": "BANCO BEST",
        "destination": null,
        "dest_name": null,
        "amount": null,
        "description": null,
        "transfer_type": null,
        "dest_email": null,
        "dest_cellphone": null,
        "currency": null,
        "urgent": null,
        "transf_reason": null,
        "exp_detail": null,
        "dest_address": null,
        "swift": null,
        "bank_name": null,
        "bank_address": null,
        "bank_city": null,
        "bank_country": null,
        "entity": null,
        "reference": null,
        "regime_type": null,
        "reference_year": null,
        "reference_month": null,
        "beneficiary": null,
        "employer": null,
        "remuneration_type": null,
        "remuneration_units": null,
        "fiscal_number": null,
        "credit_card_num": null,
        "mov_date": null,
        "status": "INIT",
        "order_num": null
    },
    "returnCode": "0",
    "returnMsg": "Sucesso"
}

Variable	Data Type	Description	Observations
login_token	String	Token used by the consentment request
oper_type	String	Operation Type	Possible Values: 0 - Consentment Request / Initiate 1 - Operation (Transfer/Payment)
oper_sub_type	String	Operation Subtype	Only Used for Transferences/Payments: TRF_EC – Transference between accounts TRF_INTERB – Interbank Transference TRF_INTERN – Internacional Transference PS – Services Payments PC – Shopping Payments PE – State Payments PSS – Social Security Payments PCOM – Communications Payments TSU – Unique Social Tax (Taxa Social Única)
oper_status	String	Operation Status
error_code	String	Error Code
error_desc	String	Error Description
entity_name	String	Entity Name
certify_guid	String	Entity certificate GUID
tpp_auth_number	String	TPP Authorizatio Number
tpp_role	String	TPP Role
tpp_country	String	TPP Country
nca_identify	String	NCA Identification
timestamp_eba	String	EBA Verification Timestamp
home_iban	String	Origin IBAN
credit_card_num	String	Credit Card Number
redirect_url	String	TPP Link	URL used to redirect to the TPP's website
oper_date	Date	Operation Date
destination	String	Destination IBAN
dest_name	String	Destinatary Name
amount	Number	Amount to transfer	Must be greater than zero.
description	String	Description
transfer_type	String	Immediate Transference	Possible Values: 1 - Normal Transference 2 - Immediate Transference
dest_email	String	Destinatary Email
dest_cellphone	String	Destinatary Cellphone
currency	String	Currency	Only used when not sent in EUR.
urgent	String	Urgent	Possible values: Y - Yes N - No
transf_reason	String	Transference Reason	Possible values: 052 - Non-Resident Transf. (Any reason) 066 - Transf. between resident accounts, in Portugal or Exterior 068 - Transf. between emigrant accounts, in Portugal or Exterior 101 - Exporting/Importing of Merchandise 292 - Trips and Tourism - Trip expenses and touristic accommodations 479 - Other services provided by companies 483 - Education Services 489 - Other services of personal nature 622 - Private current transferences from residents to non-residents
exp_detail	String	Expenses are charged to…	Possible Values: SHA - Shared Expenses (Sha) OUR - Without Expenses to the beneficiary (Our) BEN - Without Expenses to the originator (Ben)
dest_address	String	Destinatary Address
swift	String	Destination Bank's SWIFT
bank_name	String	Destination Bank's Name
bank_address	String	Destination Bank's Address
bank_city	String	Destination Bank's City
bank_country	String	Destination Bank's Country code
entity	String	Entity
reference	String	Reference
regime_type	String	Regime Type	Possible Values: 3 - Domestic Service 4- Independent Workers 5- Voluntary Social Insurance 6- Agricultural Producers Açores
reference_year	String	Reference Year	Only the last 5 years are permitted (e.g.: In 2022, only 2022,2021,2020,2019, 2018, 2017)
reference_month	String	Reference Month	E.g.: 01,02,03,04,05,06,07,08,09,10,11,12
beneficiary	String	Social Security Beneficiary Number
employer	String	Social Security Employer Number
remuneration_type	String	Renumeration Type	Possible Values: 1 - Monthly - Full Month 2 - Monthly - Partial Month 3 - Hourly
remuneration_units	Integer	Renumeration Units
fiscal_number	String	Fiscal Number
mov_date	Date	Movement Date/Payment Execution Date
order_num	String	Movement Order Date
dest_country	String	ISO 3166-1 Numeric Code of the beneficiary's country	Must contain 4 characters (e.g.: Code '840' must be '0840')

Endpoint Balance

Description

Retrieve the balance and some account/credit card info for either all accounts/cards of the user or a specific one (defined by the ID).

Allowed Roles

PSP_AI
PSP_AS
PSP_IC
PSP_PI

Endpoint

https://dev.openbank.bancobest.pt/sandbox/api/v2/Operation/Balance/{Type}

https://dev.openbank.bancobest.pt/sandbox/api/v2/Operation/Balance/{Type}/{ID}

e.g.:

https://dev.openbank.bancobest.pt/sandbox/api/v2/Operation/Balance/Account/0-MDAwMDAxMDI2

Variable	Example Value	Description	Mandatory?
Type	Account or CreditCard	Indicates whether the request wants to access Account or Credit Card info.	Yes
ID	0-MDAwMDAxMDI2	Optional identifier to retrieve the balance of one specific Account. ONLY AVAILABLE FOR ACCOUNTS!	No

Request Header

Variable	Example Value	Description	Mandatory?
Authorization	OAuth access_token=c7622a278bae420dabc91df952d83582,oauth_consumer_key=0f4c0...	Basic OAuth auhtorization schema with the access token. See "How to Access API"	Yes
Certificate	9dFpJUCnQcwe80aAOHx7YWYlqisICXNnVSKiaiA9vGO8YnzlZoJcUVPJ/rZ68X8FD==	Public key of the certificate. See "How to Access API".	Yes

Request Body

NO REQUEST BODY

Response Body: (JSON Format)

For Account type Balances:

json
[
    {
        "ID": "0-MDAwMDAxMDI2",
        "Balance": 995.0000,
        "BalanceAvailable": 0.0,
        "BalanceBooked": 995.0000,
        "Currency": "EUR",
        "AccountType": "Account",
        "Product": "Conta Digital",
        "AccountNumber": {
            "Type": "IBAN",
            "Value": "PT50006500010000000620154"
        }
    }
]

For CreditCard type Balances:

json
[
    {
        "ID": "1-MDAwMDAxMDI2",
        "Balance": 995.0000,
        "BalanceAvailable": 0.0,
        "BalanceBooked": 0.0,
        "Currency": null,
        "AccountType": "CreditCard",
        "Product": "BestBankSandbox",
        "AccountNumber": {
            "Type": "CreditCard",
            "Value": "5247729000001026"
        }
    }
]

Response Body Error (JSON Format)

Trying to access an invalid account/credit (e.g.: Account doesn't belong to the user)

json
{
    "Message":"EACC002",
    "ErrorDate":"2022-01-30T00:00:00.0000000Z","ErrorID":"abf833d24de34bad8b5006f2ba621efx"
}

Endpoint Transactions

Description

Retrieve the transactions made from a certain Account or CreditCard.

Allowed Roles

PSP_AI
PSP_AS
PSP_PI

Endpoint

https://dev.openbank.bancobest.pt/sandbox/api/v2/Operation/Transactions/{Type}/{ID}

e.g.:

https://dev.openbank.bancobest.pt/sandbox/api/v2/Operation/Transactions/Account/0-MDAwMDAxMDI2

Variable	Example Value	Description	Mandatory?
Type	Account or CreditCard	Indicates whether the request wants to access Account or Credit Card info.	Yes
ID	0-MDAwMDAxMDI2	Identifier of the Account or Credit Card to retrieve the transactions from.	Yes

Request Header

Variable	Example Value	Description	Mandatory?
Authorization	OAuth access_token=c7622a278bae420dabc91df952d83582,oauth_consumer_key=0f4c0...	Basic OAuth auhtorization schema with the access token. See "How to Access API"	Yes
Certificate	9dFpJUCnQcwe80aAOHx7YWYlqisICXNnVSKiaiA9vGO8YnzlZoJcUVPJ/rZ68X8FD==	Public key of the certificate. See "How to Access API".	Yes

Request Body

NO REQUEST BODY

Response Body (JSON Format)

For transactions of the Account Type:

json
[
    {
        "Balance": 1000.0,
        "Type": "Credit",
        "Description": "Sandbox Virtual Main Account Bank",
        "Date": "1598349684",
        "Amount": 1000.0000,
        "MovimentCurrency": "EUR",
        "TransactionNumber": "10036"
    },
    {
        "Balance": 2000.0,
        "Type": "Credit",
        "Description": "",
        "Date": "1598372709",
        "Amount": 5.0000,
        "MovimentCurrency": "EUR",
        "TransactionNumber": "10037"
    },
    {
        "Balance": 2005.0,
        "Type": "Debit",
        "Description": "Sandbox Virtual Main Account Bank",
        "Date": "1598349684",
        "Amount": -1000.0000,
        "MovimentCurrency": "EUR",
        "TransactionNumber": "10038"
    },
    {
        "Balance": 1005.0,
        "Type": "Debit",
        "Description": "",
        "Date": "1598372709",
        "Amount": -5.0000,
        "MovimentCurrency": "EUR",
        "TransactionNumber": "10039"
    }
]

For transactions of the CreditCard Type:

json
[
    {
        "Balance": 1000.0,
        "Type": "Debit",
        "Description": "PAYMENT NOS Movies",
        "Date": "1530403200",
        "Amount": -10.0,
        "MovimentCurrency": null,
        "TransactionNumber": "2"
    },
    {
        "Balance": 990.0,
        "Type": "Credit",
        "Description": "REFUND Soccer Team Donative",
        "Date": "1529193600",
        "Amount": 10.0,
        "MovimentCurrency": null,
        "TransactionNumber": "3"
    }
]

Response Body Error (JSON Format)

Trying to access an invalid account/credit (e.g.: Account doesn't belong to the user)

json
{
    "Message":"EACC002",
    "ErrorDate":"2022-01-30T00:00:00.0000000Z","ErrorID":"abf833d24de34bad8b5006f2ba621efx"
}

Endpoint Initiate Payment

Beginning of the Payment Flow. From this endpoint transfers and payments are made with an entity and an ATM reference. In production environment the user receives an SMS to confirm the operation.

Sandbox Note:

Unlike the '/Initiate' endpoint, the '/InitiatePayment' does not have a sandbox specific page. That said, the 'LoginURL' will be equal to the 'redirect_uri' that is sent in the request. The operation ID resulting in this operation will have static data on 'CheckOperationByID' endpoint that represents the data of a regular transference.

Allowed Roles

PSP_AS

Endpoint POST

https://dev.openbank.bancobest.pt/sandbox/api/v2/Operation/InitiatePayment

Request Header

Variable	Example Value	Description	Mandatory?
Authorization	OAuth oauth_consumer_key=0f4c0...	Basic OAuth auhtorization schema. See "How to Access API"	Yes
Certificate	9dFpJUCnQcwe80aAOHx7YWYlqisICXNnVSKiaiA9vGO8YnzlZoJcUVPJ/rZ68X8FD==	Public key of the certificate. See "How to Access API".	Yes
redirect_uri	myapplication.com/loginReturn	Endpoint to redirect the user too after the operation	Yes

Request Body

Name	Required?	Type	Dimension	Format	Description	Notes
pispid	Y	String			Unique ID given by the PISP for the initiation of a payment/transfer operation. The validity of this ID is the PISP's responsibility.
environment	N	String	3	WEB/APP	Identifier of the environment where the payment will be redirected to.	By default it assumes WEB.
creditor.account.iban	Y	String	21		Beneficiary's IBAN
creditor.account.amount	Y	String	100		Amount
creditor.account.type.inside	N	boolean		true/false	Transfer type flag (inside = true - transfer between BEST accounts.)
creditor.account.type.interbank	N	boolean		true/false	Transfer type flag (interbank = true - transfer between different banks accounts.)
creditor.account.type.international	N	boolean		true/false	Transfer type flag (international = true - International transfer.)
creditor.name	Y	String	50		Beneficiary's name
creditor.description	Y	String	140		Description transfer
creditor.email	N	String	50		Beneficiary's E-mail
creditor.country	N	String	4		Beneficiary's Country Code - Must contain 4 characters (e.g.: Code '840' must be '0840')	ISO 3166-1 numeric code (e.g.: '0840' - United States of America) - Must always have 4 characters
debtor.iban	N	String	25		Origin IBAN	Without prefix PT50

Partial Request Body - (only used for Internacional )

Nome	Obrigatório?	Tipo	Dimensão	Descrição	Observações
creditor.account.info.currency	N	String	3	ISO 4217 code for currencies - By default assumes 'EUR'	Código ISO 4217 para moedas - Por padrão assume 'EUR'
creditor.account.info.urgency_flag	Y	(Y/N) String	1	Indicates urgency of the transfer (Y - Yes, N - No)
creditor.account.info.nature_code	Y	String	3	Transfer Nature code - See possible code list below
creditor.account.info.address	Y	String	50	Beneficiary's Address
creditor.account.info.expenses_code	Y	String	50	[Ignored if IBAN is SEPA] Expense Details - See possible code list below (Ingored if SEPA, will assume the 'SHA' value)
creditor.account.info.swift_code	Y	String	50	[Ignored if IBAN is SEPA] Beneficiary's Bank SWIFT Code.
creditor.account.info.bank_name	Y	String	50	[Ignored if IBAN is SEPA] Beneficiary's Bank Name.
creditor.account.info.bank_address	Y	String	50	[Ignored if IBAN is SEPA] Beneficiary's Address.
creditor.account.info.bank_address_city	Y	String	50	[Ignored if IBAN is SEPA] Beneficiary's City.
creditor.account.info.bank_country_code	Y	String	4	[Ignored if IBAN is SEPA] Beneficiary's Country Code - Must contain 4 characters (e.g.: Code '840' must be '0840')	ISO 3166-1 numeric code (e.g.: '0840' - United States of America) - Must always have 4 characters

Example of Request Body transfer between accounts:

json
{
    "pispid": "1234567890-1234",
    "environment": "WEB",
    "creditor": {
        "account": {
           "iban": "006500010000000000000",
		   "amount": "5",
           "type": {
	            "inside": true
	        }
        },
        "name": "Beneficiary name",
        "description": "Description",
        "email": "email@email.com"
    },    
    "debtor": {
        "iban": "006500010000000000000"        
    }
}

Body Response:

{
    "LoginUrl": "https://dev.openbank.bancobest.pt/api/v2/Auth/Index/1-000000"
}

Example of Request Body interbank transfer:

json
{
    "pispid": "1234567890-1234",
    "environment": "WEB",
    "type": "1",
    "creditor": {
        "account": {
           "iban": "006500010000000000000",
		   "amount": "5",
           "type": {
	            "interbank": true
	        }
        },
        "name": "Beneficiary name",
        "description": "Description",
        "email": "email@email.com"
    },    
    "debtor": {
        "iban": "006500010000000000000"     
    }
}

Response:

{
    "LoginUrl": "https://api.openbank.bancobest.pt/api/v2/Auth/Index/1-000000"
}

Example of Request Body international transfer:

json
{
    "pispid": "1234567890-1234",
    "environment": "WEB",
    "type": "",
    "creditor": {
        "account": {
           "iban": "006500010000000000000",
		   "amount": "5",
           "type": {
	            "international": true
	        },
            "info": {
                "currency": "EUR",
                "urgency_flag": "N",
                "nature_code": "066",
                "expenses_code": "OUR",
                "address": "Morada do Destinatário Address 1",
                "swift_code": "BESZPTPL123",
                "bank_name": "Nome do Banco Dest",
                "bank_address": "Praça Marquês de Pombal, Nº 3, 3º",
                "bank_address_city": "Lisboa",
                "bank_country_code": "0840"
            }
        },
        "name": "Beneficiary name",
        "description": "Description",
        "email": "email@email.com",
        "country" : "0840"
    },    
    "debtor": {
        "iban": "006500010000000000000"        
    }
}

Response:

{
    "LoginUrl": "https://api.openbank.bancobest.pt/api/v2/Auth/Index/1-000000"
}

Lista de códigos para Transferências Internacionais

Nature of transfer - Required. (nature_code) Possible values: o 052 - Transf. not residents; o 066 - Transf. between residents, Portugal and foreign; o 068 - Transf. between foreign accounts, Portugal and foreign; o 101 - Export/Import of merchandise; o 292 - Travel and Turism - travel expenses; o 479 - Other services; o 483 - Education Service; o 489 - Other services of a personal nature; o 622 - Transf. private from residents to not residents;

Expenses Details - Required. (expenses_code) Possible values: o SHA - Shared Expenses (Sha); o OUR - Without Expenses to the beneficiary (Our); o BEN - Without Expenses to the originator (Ben);

Redirect URL: (GET parameters on the URL)

Variable	Example Value	Description
oper_id	1-BQMM39	ID of the payment operation

myapplication.com/loginReturn?oper_id=1-BQMM37

Endpoint Initiate Payment - Other Payment Types

Example of Request Body for service payment:

Request Body

Name	Required?	Type	Dimension	Format	Description
creditor.payment_bill.entity	S	String	5		Entity
creditor.payment_bill.reference	S	String	9	Reference
creditor.payment_bill.amount	S	String	100		Amount
creditor.description	S	String	140		Description
debtor.iban	N	String	25		Origin IBAN

json
{  
  "creditor": {
    "payment_bill": {
      "entity": "22356",
      "reference": "123456789",
	  "amount": "5",
    },
    "description": "",
  },
  "debtor": {
        "iban": "006500010000000000000"
    }
}

Example of Request Body payment purchases:

Request Body

Name	Required?	Type	Dimension	Format	Description
creditor.payment_bill.enterprise	S	String	5		Enterprise
creditor.payment_bill.reference	S	String	9	Reference
creditor.payment_bill.amount	S	String	100		Amount
debtor.iban	N	String	25		Origin IBAN

json
{  
  "creditor": {
    "payment_bill": {
      "enterprise": "22356",
      "reference": "123456789",
	  "amount": "5",
    },
  },
  "debtor": {
        "iban": "006500010000000000000"
    }
}

Example of Request Body State payment:

Request Body

Name	Required?	Type	Dimension	Format	Description
creditor.state_bill.reference	S	String	9	Reference
creditor.state_bill.amount	S	String	100		Amount
debtor.iban	N	String	25		Origin IBAN

json
{  
  "creditor": {
    "state_bill": {
      "amount": "12",
      "reference": "123456789",
    },
  },
  "debtor": {
        "iban": "006500010000000000000"
    }
}

Example of Request Body Payment Santa Casa:

Request Body

Name	Required?	Type	Dimension	Format	Description
creditor.santa_casa.player_card_num	S	String	9	Player number
creditor.santa_casa.amount	S	String	100		Amount
debtor.iban	N	String	25		Origin IBAN

json
{  
  "creditor": {
    "santa_casa": {
      "amount": "12",
      "player_card_num": "123456789",
    },
  },
  "debtor": {
        "iban": "006500010000000000000"
    }
}

Example of Request Body payment Social Security:

Request Body

Name	Required?	Type	Dimension	Format	Description	Notes
creditor.social_security.regime_type	S	String	1	Regime type	3 - Domestic Service 4- self-employed 5- voluntary social insurance 6- Azores agricultural producers
creditor.social_security.reference_year	S	String	4	YYYY	Reference year	Just the last 5 years (If we are in 2019 just allow 2019,2018,2017,2016,2015,2014)
creditor.social_security.reference_month	S	String	2	MM	Reference month	Ex: 01,02,03,04,05,06,07,08,09,10,11,12
creditor.social_security.beneficiary	S	String	11		Nº Social Security Beneficiary
creditor.social_security.employer	N	String	11		Nº Beneficiary of the Employer	if regime_type = "3" then is required
creditor.social_security.remuneration_type	S	String	1		Amount	1 - Monthly - Complete month 2 - Monthly - Incomplete month 3 - Hourly
creditor.social_security.remuneration_units	S	String			Payment Units	If remuneration_type <> "1" then is required
creditor.social_security.remuneration_monthly	S	String			Value of effective monthly remuneration
debtor.iban	N	String	25		Origin IBAN

json
{  
  "creditor": {
    "social_security": {
      "regime_type": "3",
      "reference_year": "2021",
	  "reference_month": "01",
	  "beneficiary": "12345678900",
	  "employer": "12345678900",
	  "remuneration_type": "1",
	  "remuneration_units": "",
	  "remuneration_monthly": "",
    },
  },
  "debtor": {
        "iban": "006500010000000000000"
    }
}

Endpoint TopsUpsGetPaymentInfo

Description

In order to handle some payment types, it is necessary to retrieve the information from the Top Ups in the TopsUpsGetPaymentInfo API.

Allowed Roles

PSP_AS

Endpoint POST

https://dev.openbank.bancobest.pt/sandbox/api/v2/Operation/TopsUpsGetPaymentInfo

Request Header

Variable	Example Value	Description	Mandatory?
Authorization	OAuth oauth_consumer_key=0f4c0...	Basic OAuth auhtorization schema. See "How to Access API"	Yes
Certificate	9dFpJUCnQcwe80aAOHx7YWYlqisICXNnVSKiaiA9vGO8YnzlZoJcUVPJ/rZ68X8FD==	Public key of the certificate. See "How to Access API".	Yes

Example of Request Body (Top Up):

Request Body

Name	Required?	Type	Dimension	Description	Notes
creditor.topup.entity_code	Yes	String	5	Entity code	Information from TopsUpsGetPaymentInfo (entityCode)
creditor.topup.reference	Yes	Number		Cellphone or Reference
creditor.topup.amount	No	Number		Amount
creditor.topup.amount_desc	No	String	30	Description of the amount	Not required if "amount" filled. Information from TopsUpsGetPaymentInfo (amount)

Response Body

json
{
    "outputData": {
        "ListOfEntities": {
            "entity": [
                {
                    "entityName": "WTF",
                    "entityCode": "10058",
                    "ListOfPaymentTypes": {
                        "payment": [
                            {
                                "name": "Carregamentos",
                                "code": "1",
                                "amount_max": "100",
                                "amount_min": "5",
                                "reference_digits": "9",
                                "ListOfAmount": {
                                    "amount": [
                                        {
                                            "internal_code": "1",
                                            "description": "5 Euros",
                                            "amount": "5"
                                        },
                                        {
                                            "internal_code": "2",
                                            "description": "10 Euros",
                                            "amount": "10"
                                        },
                                        {
                                            "internal_code": "3",
                                            "description": "15 Euros",
                                            "amount": "15"
                                        },
                                        {
                                            "internal_code": "4",
                                            "description": "20 Euros",
                                            "amount": "20"
                                        },
                                        {
                                            "internal_code": "5",
                                            "description": "30 Euros",
                                            "amount": "30"
                                        },
                                        {
                                            "internal_code": "6",
                                            "description": "50 Euros",
                                            "amount": "50"
                                        },
                                        {
                                            "internal_code": "8",
                                            "description": "Outros Montantes",
                                            "amount": ""
                                        }
                                    ]
                                },
                                "ListOfDetails": {
                                    "details": [
                                        {
                                            "code": "1",
                                            "name": "Contribuinte",
                                            "value": ""
                                        },
                                        {
                                            "code": "2",
                                            "name": "Telemóvel",
                                            "value": ""
                                        }
                                    ]
                                }
                            }
                        ]
                    }
                }
            ]
        }
    },
    "returnCode": "0",
    "returnMsg": "Sucesso"
}

Generic Error messages

Description

List of generic error messages that may occur during the consumption of the APIs.

Errors

Missing variables in Header HttpStatusCode: 400

{
    "Message": "Missing one or more variables in the authorization header request.",
    "ErrorDate": "2021-01-26T11:21:38.9419034Z",
    "ErrorID": "ccc9b2b7df2643a5a975d0f76ff152bb"
}

Incorrect Header Authorization HttpStatusCode: 400

{
    "Message": "Incorrect Authorization Scheme.",
    "ErrorDate": "2021-01-26T11:25:37.4498494Z",
    "ErrorID": "6dc4ea9aff8345348b0c37f0dba29c32"
}

Account not found HttpStatusCode: 401

{
    "Message": "No account found. Maybe you are passing a wrong account id.",
    "ErrorDate": "2021-01-26T11:28:11.8021361Z",
    "ErrorID": "e2a3899c2f1645d4b9d7812a0ae6fc39"
}

Invalid IBAN HttpStatusCode: 401

{
    "Message": "Unknown IBAN. The creditor account must be a valid sandbox virtual account.",
    "ErrorDate": "2021-01-26T11:29:43.8125923Z",
    "ErrorID": "d241dca9ddbd4fad80688fa0e9ae93c4"
}

Payment creditor and debitor equals HttpStatusCode: 401

{
    "Message": "The creditor account and the debitor account is the same.",
    "ErrorDate": "2021-01-26T11:37:48.56841Z",
    "ErrorID": "ee10cf5419a34953b55aaed4631f0215"
}

Invalid Request Json HttpStatusCode: 400

{
    "Message": "Missing one or more variables in the body request.",
    "ErrorDate": "2021-01-26T11:41:29.9113813Z",
    "ErrorID": "5408ee366caf480d975ade8b81a2b5fc"
}

Invalid Token HttpStatusCode: 400

{
    "Message": "Invalid Token.",
    "ErrorDate": "2021-01-26T11:42:36.0774542Z",
    "ErrorID": "cea7ae36186346afb86da30bcfff341e"
}

Invalid Certificate HttpStatusCode: 401

{
    "Message": "Certificate error",
    "ErrorDate": "2021-01-26T11:43:44.9602376Z",
    "ErrorID": "918723fe03c046a5b259fe3a932919f2"
}

Generic Error, please contact the support HttpStatusCode: 417

{
    "Message": "We apologize but an unexpected error occured. Please try again later.",
    "ErrorDate": "2021-01-26T11:44:52.471263Z",
    "ErrorID": "51f4c9dff6084f6dab0cf9d7ab306622"
}

URL not found HttpStatusCode: 400

{
    "Message": "URL not found.",
    "ErrorDate": "2021-01-26T11:48:32.4858036Z",
    "ErrorID": "d6ced1637d8443e38c0730a4dfd05c22"
}

Invalid Request Json HttpStatusCode: 400

{
    "Message": "Missing input value",
    "ErrorDate": "2021-01-26T11:50:53.0260426Z",
    "ErrorID": "bfa03e5a1cc841a4a94d4295536d0a69"
}

Sandbox SMS number invalid HttpStatusCode: 401

{
    "Message": "The SMS number is wrong.",
    "ErrorDate": "2021-01-26T11:52:33.0950804Z",
    "ErrorID": "b120bd1b441d4992acdde7920f6264a2"
}

Invalid amount HttpStatusCode: 401

{
    "Message": "Invalid amount.",
    "ErrorDate": "2021-01-26T11:55:03.9314232Z",
    "ErrorID": "d653bc19dfab47fe903fdd8166d0dc75"
}

Invalid creditor HttpStatusCode: 401

{
    "Message": "Invalid creditor.",
    "ErrorDate": "2021-01-26T11:56:57.9314065Z",
    "ErrorID": "b621168e53db45f9a8e7010f0c710da2"
}

Payment previously sent HttpStatusCode: 401

{
    "Message": "This payment bill was sent previously to the sandbox. Type another bill reference or bill entity.",
    "ErrorDate": "2021-01-26T11:59:46.2469413Z",
    "ErrorID": "3fb3ffe5b4c945cabfbc705f7c86fd23"
}

Payment previously sent HttpStatusCode: 401

{
    "Message": "This government bill was sent previously to the sandbox. Type another bill reference.",
    "ErrorDate": "2021-01-26T12:00:57.913106Z",
    "ErrorID": "07bcdeb26ef746f5947e977bf4c695c4"
}

Pagamento not found HttpStatusCode: 401

{
    "Message": "Payment Not Found.",
    "ErrorDate": "2021-01-26T12:03:21.875039Z",
    "ErrorID": "cf8f519ea35a46eba34c8cbb93f5f84b"
}

Bill already paid HttpStatusCode: 401

{
    "Message": "This bill has been paid.",
    "ErrorDate": "2021-01-26T12:04:48.4444192Z",
    "ErrorID": "945894869aea4c4da060d3d1a2fb15d6"
}

Invalid Json request ID HttpStatusCode: 401

{
    "Message": "Id is required",
    "ErrorDate": "2021-01-26T12:08:41.9591402Z",
    "ErrorID": "37be13b57e6948ad9c0c610ba483fea2"
}

Access Token was cancelled. Likely a new Access Token was the user was created after the one provided. HttpStatusCode: 400

{
    "Message": "EGEN003",
    "ErrorDate": "2021-01-26T12:08:41.9591402Z",
    "ErrorID": "37be13b57e6948ad9c0c610ba483fea2"
}