- Documentação Best Bank API
- Aceder à API
- Referência Rápida
Referência Rápida
Esta página contém algumas referências rápida para os desenvolvedores.
URL Sandbox
https://dev.openbank.bancobest.pt/sandbox
URL Production
https://api.openbank.bancobest.pt/
Endpoint Initiate
Descrição
Endpoint que dá acesso à página de autenticação e consentimentos. Um passo necessário para usar o endpoint '/Token' e aceder às operações.
Funções Permitidas
- PSP_AI
- PSP_AS
- PSP_IC
- PSP_PI
Endereço POST
https://api.openbank.bancobest.pt/api/v2/OAuth/Initiate
Cabeçalho do Pedido
| Variável | Valor de Exemplo | Descrição | Obrigatório? |
|---|---|---|---|
| Authorization | OAuth oauth_consumer_key=0f4c0... | Esquema OAuth para Autorização. Ver documentação "Aceder à API" | Sim |
| Certificate | 9dFpJUCnQcwe80aAOHx7YWYlqisICXNnVSKiaiA9vGO8YnzlZoJcUVPJ/rZ68X8FD== | Chave públic do certificado. Ver documentação "Aceder à API" | Sim |
| redirect_uri | myapplication.com/loginReturn | Endereço que o utilizador será redirecionado para após a operação. | Sim |
| response_type | 200 | Código de resposta HTTP retornado no caso de sucesso. Por padrão a resposta é 200. | Não |
| state | something_here | Valor utilizado livrement pela aplicação que será retornado após a operação. | Sim |
Corpo da Resposta: (Formato JSON)
| Variável | Valor de Exemplo | Descrição |
|---|---|---|
| LoginUrl | (ver exemplo em baixo) | URL da página de autenticação e consentimento. |
Exemplo de Corpo da Resposta.
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"
}
URL de Redirecionamento: (Parâmetros GET no URL)
| Variável | Valor de Exemplo | Descrição |
|---|---|---|
| code | d007359368f94215b4e0bda6aa039563 | Código Temporário utilizado para aceder ao Token de Acesso. |
| oper_id | 1-BQMM39 | Identificador da operação de consentimento. |
| state | something_here | Valor utilizado livremente pela aplicação que será retornado após a operação. |
myapplication.com/loginReturn?code=d007359368f94215b4e0bda6aa039563&state=something_here&oper_id=1-BQMM39
Endpoint Token
Funções Permitidas
- PSP_AI
- PSP_AS
- PSP_IC
- PSP_PI
Endereço POST
https://dev.openbank.bancobest.pt/sandbox/api/v2/OAuth/Token
Cabeçalho de Pedido
| Variável | Valor de Exemplo | Descrição | Obrigatório? |
|---|---|---|---|
| Authorization | OAuth code=d007359368f94215b4e0bda6aa039563,oauth_consumer_key=0f4c0... | Esquema OAuth para Autorização com o código temporário. Ver documentação "Aceder à API" | Sim |
| Certificate | 9dFpJUCnQcwe80aAOHx7YWYlqisICXNnVSKiaiA9vGO8YnzlZoJcUVPJ/rZ68X8FD== | Public key of the certificate. See "How to Access API". | Yes |
Corpo de Pedido
SEM CORPO DE PEDIDO
Corpo da Resposta: (Formato JSON)
| Variável | Valor de Exemplo | Descrição |
|---|---|---|
| access_token | b7633a278bae420dabc91df952d83532 | Token de Acesso a ser utilziado no esquema OAuth para as operações da API. |
| expires_in | 1648166400 | Timestamp que representa a tempo quanto o Access Token deverá expirar. |
Exemplo de Corpo da Resposta.
json
{
"access_token": "b7633a278bae420dabc91df952d83532",
"expires_in":1648166400
}
Endpoint CheckOperationByID
Descrição
Endpoint que ofereçe informação extra com base em algumas operações específicas. Estas operações de momento são retornadas após o redirecionamento dos endpoints de '/Initiate' e '/InitiatePayment'
Funções Permitidas
- PSP_AS
- PSP_IC
- PSP_PI
Endereço POST
https://dev.openbank.bancobest.pt/sandbox/api/v2/Operation/CheckOperationByID/{ID}
Cabeçalho de Pedido
| Variável | Valor de Exemplo | Descrição | Obrigatório? |
|---|---|---|---|
| Authorization | OAuth access_token=c7622a278bae420dabc91df952d83582,oauth_consumer_key=0f4c0... | Esquema OAuth para Autorização com o código de acesso. Ver documentação "Aceder à API" | Sim |
| Certificate | 9dFpJUCnQcwe80aAOHx7YWYlqisICXNnVSKiaiA9vGO8YnzlZoJcUVPJ/rZ68X8FD== | Chave públic do certificado. Ver documentação "Aceder à API" | Sim |
Corpo de Pedido
SEM CORPO DE PEDIDO
Corpo de Resposta
Exemplo de uma operação gerada a partir do endpoint api/v2/OAuth/Initiate :
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"
}
| Variável | Tipo de Dados | Descrição | Observações |
|---|---|---|---|
| login_token | String | Código utilizado no pedido de consentimento | |
| oper_type | String | Tipo de Operação | Valores possíveis: 0 - Pedido de Consentimento 1 - Operação (Transferência/Pagamento) |
| oper_sub_type | String | Sub-tipo de Operação | Apenas utilizado em Transferências/Pagamentos: TRF_EC – Transferência entre contas TRF_INTERB – Transferência interbancárias TRF_INTERN – Transferência internacional PS – Pagamento de Serviços PC – Pagamento Compras PE – Pagamento Estado PSS – Pagamento segurança social PCOM – Pagamento comunicações TSU – Taxa social unica |
| oper_status | String | Estado de Operação | |
| error_code | String | Código de Erro | |
| error_desc | String | Descrição de Erro | |
| entity_name | String | Nome de Entidade | |
| certify_guid | String | GUID do certificado da entidade | |
| tpp_auth_number | String | Número de Autorização do TPP | |
| tpp_role | String | Função do TPP | |
| tpp_country | String | País do TPP | |
| nca_identify | String | NCA Identificação NCA | |
| timestamp_eba | String | Timestamp de Verificação EBA | |
| home_iban | String | IBAN Origem | |
| credit_card_num | String | Número Cartão de Crédito | |
| redirect_url | String | Link utilizado para redireccionar para o site do TPP | Link utilizado para redireccionar para o site do TPP |
| oper_date | Date | Data da Operação | |
| destination | String | Destino do IBAN | |
| dest_name | String | Nome do Destinatário | |
| amount | Number | Valor a Transferir | Tem de ser superior a 0. |
| description | String | Descritivo | |
| transfer_type | String | Transferência Imediata | Valores possíveis: 1 - Transferência normal 2 - Transferência Imediata |
| dest_email | String | Email do Destinatário | |
| dest_cellphone | String | Telemóvel do Destinatário | |
| currency | String | Moeda | Quando não é enviado é utilizado o EUR |
| urgent | String | Urgente | Valores possíveis: Y - Sim N - Não |
| transf_reason | String | Natureza da Tranferencia | Valores possíveis: 052 - Transf. de não residentes (qualquer motivo) 066 - Transf. entre contas de residente, em Portugal e no Exterior 068 - Transf. entre contas de emigrante, em Portugal e no Exterior 101 - Exportação/Importação de Mercadorias 292 - Viagens e Turismo - desp de viagem e estada turística 479 - Outros serviços fornecidos por empresas 483 - Serviços de educação 489 - Outros de serviços de natureza pessoal 622 - Transf. correntes privadas de residentes p/ não residentes |
| exp_detail | String | Despesas a cargo de | Valores possíveis: SHA - Despesas partilhadas (Sha) OUR - Sem desp p/ beneficiário (Our) BEN - Sem desp p/ ordenador (Ben) |
| dest_address | String | Morada do Destinatário | |
| swift | String | Endereço SWIFT do Banco do Destinatário | |
| bank_name | String | Nome do banco destinatário | |
| bank_address | String | Morada do banco destinatário | |
| bank_city | String | Localidade do banco destinatário | |
| bank_country | String | Código do País do banco destinatário | |
| entity | String | Entidade | |
| reference | String | Referência | |
| regime_type | String | Tipo de Regime | Valores possíveis: 3 - Serviço doméstico 4 - Trabalhadores independentes 5 - Seguro social voluntário 6 - Produtores agricolas Açores |
| reference_year | String | Ano de referência | Só são permitidos os últimos 5 anos (Se estamos em 2019 só permite 2019,2018,2017,2016,2015,2014) |
| reference_month | String | Mês de referência | Ex.: 01,02,03,04,05,06,07,08,09,10,11,12 |
| beneficiary | String | Nº Beneficiário da Segurança Social | |
| employer | String | Nº Beneficiário da Entidade Patronal | |
| remuneration_type | String | Tipo de Remuneração | Valores possíveis: 1 - Mensal - Mês completo 2 - Mensal - Mês incompleto 3 - Horária |
| remuneration_units | Integer | Unidades de Pagamento | |
| fiscal_number | String | Número de contribuinte | |
| mov_date | Date | Data do Movimento/Data de Execução do Pagamento | Valor retornado nas APIs de pagamentos ou transferências |
| order_num | String | Número de Ordem do Movimento | Valor retornado na API de transferências |
| dest_country | String | Código Númerico ISO 3166-1 do país do destinatário | Deve sempre conter 4 caractéres (ex.: Código '840' deverá ser '0840') |
Endpoint Balance
Descrição
Pesquisar pelo balanço e mais alguma informação da conta/cartão de crédito para todas as contas/cartões do utilizador ou apenas um específico (definido pelo ID).
Funções Permitidas
- PSP_AI
- PSP_AS
- PSP_IC
- PSP_PI
Endereços
https://dev.openbank.bancobest.pt/sandbox/api/v2/Operation/Balance/{Type}
https://dev.openbank.bancobest.pt/sandbox/api/v2/Operation/Balance/{Type}/{ID}
ex.:
https://dev.openbank.bancobest.pt/sandbox/api/v2/Operation/Balance/Account/0-MDAwMDAxMDI2
| Variável | Valor de Exemplo | Descrição | Obrigatório? |
|---|---|---|---|
| Type | Account or CreditCard | Indica se o balanço acedido pertence a Contas ou Cartões de Crédito. | Sim |
| ID | 0-MDAwMDAxMDI2 | Identificador opcional utilizado para pesquisar balanço de uma Conta em específico. APENAS DISPONÍVEL PARA CONTAS! | Não |
Cabeçalho de Pedido
| Variável | Valor de Exemplo | Descrição | Obrigatório? |
|---|---|---|---|
| Authorization | OAuth access_token=c7622a278bae420dabc91df952d83582,oauth_consumer_key=0f4c0... | Esquema OAuth para Autorização com o token de acesso. Ver documentação "Aceder à API" | Sim |
Corpo de Pedido
SEM CORPO DE PEDIDO
Corpo de Resposta (Formato JSON)
- Para balanços do tipo Account (Conta):
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"
}
}
]
- Para balanços do tipo CreditCard (Cartão de Crédito):
json
[
{
"ID": "1-MDAwMDAxMDI2",
"Balance": 995.0000,
"BalanceAvailable": 0.0,
"BalanceBooked": 0.0,
"Currency": null,
"AccountType": "CreditCard",
"Product": "BestBankSandbox",
"AccountNumber": {
"Type": "CreditCard",
"Value": "5247729000001026"
}
}
]
Corpo de Pedido Erro (Formato JSON)
- Tentativa de aceder a uma conta/cartão de crédito inválido (e.x.: Conta não pertence ao utilizador)
json
{
"Message":"EACC002",
"ErrorDate":"2022-01-30T00:00:00.0000000Z","ErrorID":"abf833d24de34bad8b5006f2ba621efx"
}
Endpoint Transactions
Descrição
Pesquisar as transações feitas a partir de uma certa Conta ou Cartão de Crédito.
Funções Permitidas
- PSP_AI
- PSP_AS
- PSP_PI
Endereço
https://dev.openbank.bancobest.pt/sandbox/api/v2/Operation/Transactions/{Type}/{ID}
e.x.:
https://dev.openbank.bancobest.pt/sandbox/api/v2/Operation/Transactions/Account/0-MDAwMDAxMDI2
| Variável | Valor de Exemplo | Descrição | Obrigatório? | |
|---|---|---|---|---|
| Type | Account or CreditCard | Indica se as transferências acedidas pertencem a uma Conta ou Cartões de Crédito. | Sim | |
| ID | 0-MDAwMDAxMDI2 | Identificador utilizado para pesquisar as trasnferências de uma Conta ou Cartão de Crédito em específico. | Yes |
Cabeçalho de Pedido
| Variável | Valor de Exemplo | Descrição | Obrigatório? |
|---|---|---|---|
| Authorization | OAuth access_token=c7622a278bae420dabc91df952d83582,oauth_consumer_key=0f4c0... | Esquema OAuth para Autorização com o token de acesso. Ver documentação "Aceder à API" | Sim |
Corpo de Pedido
SEM CORPO DE PEDIDO
Corpo de Resposta (Formato JSON)
- Para transações do tipo Account (Conta):
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"
}
]
- Para transações do tipo CreditCard (Cartão de Crédito):
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"
}
]
Corpo de Pedido Erro (Formato JSON)
- Tentativa de aceder a uma conta/cartão de crédito inválido (e.x.: Conta não pertence ao utilizador)
json
{
"Message":"EACC002",
"ErrorDate":"2022-01-30T00:00:00.0000000Z","ErrorID":"abf833d24de34bad8b5006f2ba621efx"
}
Endpoint Initiate Payment
Início do Fluxo de Pagamento. A partir deste endpoint são feitas transferências e pagamentos com entidade e referência multibanco. Em produção, é enviado ao utilizador um SMS para confirmação da operação.
Notas Sandbox:
Ao contrário do endpoint '/Initiate', o '/InitiatePayment' não contém uma página específica para a sandbox. Dito isto, o ' LoginURL' irá ser igual ao valor do 'redirect_uri' que é enviado no pedido. O ID de operação que resulta deste pedido será um valor estático que poderá ser verificado no endpoint 'CheckOperationByID', que representa os dados de uma transferência regular.
Funções Permitidas
- PSP_AS
Endereço POST
https://api.openbank.bancobest.pt/api/v2/Operation/InitiatePayment
Headers
| Variável | Valor de Exemplo | Descrição | Mandatório? |
|---|---|---|---|
| Authorization | OAuth oauth_consumer_key=0f4c0... | Basic OAuth auhtorization schema. See "How to Access API" | Sim |
| certificate | 9dFpJUCnQcwe80aAOHx7YWYlqisICXNnVSKiaiA9vGO8YnzlZoJcUVPJ/rZ68X8FD== | Certificado em base64 que contém a chave pública | Sim |
| redirect_uri | myapplication.com/loginReturn | Endereço para o qual o utilizador da aplicação será redirecionado após a operação | Sim |
Corpo do Pedido
| Nome | Obrigatório? | Tipo | Dimensão | Formato | Descrição | Observações |
|---|---|---|---|---|---|---|
| pispid | S | String | ID dado pelo PISP para a iniciação de uma operação de pagamentos/transferências. Validade do valor é da responsabilidade do PISP. | |||
| environment | N | String | 3 | WEB/APP | Identificador do ambiente a que o pagamento será redirecionado. | Por padrão assume WEB. |
| creditor.account.iban | S | String | 21 | IBAN de Destino | ||
| creditor.account.amount | S | String | 100 | Montante da Transferência | ||
| creditor.account.type.inside | N | boolean | true/false | Tipo de transferência. (inside = true - transferência entre contas.) | ||
| creditor.account.type.interbank | N | boolean | true/false | Tipo de transferência. (interbank = true - transferência interbancária.) | ||
| creditor.account.type.international | N | boolean | true/false | Tipo de transferência. (international = true - transferência internacional.) | ||
| creditor.name | S | String | 50 | Nome do Destinatário da Transferência. | ||
| creditor.description | S | String | 140 | Descrição da Transferência. | ||
| creditor.email | N | String | 50 | Email do Destinatário. | ||
| creditor.country | S | String | 4 | País do Destinatário - Deve sempre conter 4 caractéres (ex.: Código '840' deverá ser '0840') | Código Númerico ISO 3166-1 (ex.: '0840' - Estados Unidos da America) - Deverá sempre ter 4 caractéres. | |
| debtor.iban | N | String | 25 | Iban de origem. | Não deve conter o prefixo PT50 |
Corpo do Pedido Parcial - (apenas usado em internacionais)
| Nome | Obrigatório? | Tipo | Dimensão | Formato | Descrição | Observações | ||
|---|---|---|---|---|---|---|---|---|
| creditor.account.info.currency | N | String | 3 | Código ISO 4217 para moedas - Por padrão assume 'EUR' | Código ISO 4217 para moedas - Por padrão assume 'EUR' | |||
| creditor.account.info.urgency_flag | S | (Y/N) String | 1 | Indica urgência da transferência (Y - Sim, N - Não) | ||||
| creditor.account.info.nature_code | S | String | 3 | Natureza da Transferência - Ver códigos possíveis em baixo. | ||||
| creditor.account.info.address | S | String | 50 | Endereço do Destinatário. | ||||
| creditor.account.info.expenses_code | S | String | 50 | [Ignorado se IBAN é SEPA] Detalhes de Despesas - Ver códigos possíveis em baixo. (Ignorado se SEPA, assume o valor 'SHA') | ||||
| creditor.account.info.swift_code | S | String | 50 | [Ignorado se IBAN é SEPA] Código SWIFT do Banco da conta do Destinatário. | ||||
| creditor.account.info.bank_name | S | String | 50 | [Ignorado se IBAN é SEPA] Nome do Banco da conta do Destinatário. | ||||
| creditor.account.info.bank_address | S | String | 50 | [Ignorado se IBAN é SEPA] Endereço do Banco da conta do Destinatário. | ||||
| creditor.account.info.bank_address_city | S | String | 50 | [Ignorado se IBAN é SEPA] Cidade do do Banco da conta do Destinatário. | ||||
| creditor.account.info.bank_country_code | S | String | 4 | [Ignorado se IBAN é SEPA] Código do país do Banco da conta do Destinatário. - Deve sempre conter 4 caractéres (ex.: Código '840' deverá ser '0840') | Código Númerico ISO 3166-1 (ex.: '0840' - Estados Unidos da America) - Deverá sempre ter 4 caractéres. |
Exemplo de Corpo do Pedido para transferências entre contas:
json
{
"pispid": "1234567890-1234",
"environment": "WEB",
"creditor": {
"account": {
"iban": "006500010000000000000",
"amount": "5",
"type": {
"inside": true
}
},
"name": "Beneficiary name",
"description": "descrição",
"email": "email@email.com"
},
"debtor": {
"iban": "006500010000000000000"
}
}
Resposta:
{
"LoginUrl": "https://api.openbank.bancobest.pt/api/v2/Auth/Index/1-000000"
}
Exemplo de Corpo do Pedido para transferências interbancária:
json
{
"pispid": "1234567890-1234",
"environment": "WEB",
"type": "1",
"creditor": {
"account": {
"iban": "006500010000000000000",
"amount": "5",
"type": {
"interbank": true
}
},
"name": "Beneficiary name",
"description": "descrição",
"email": "email@email.com"
},
"debtor": {
"iban": "006500010000000000000"
}
}
Resposta:
{
"LoginUrl": "https://api.openbank.bancobest.pt/api/v2/Auth/Index/1-000000"
}
Exemplo de Corpo do Pedido para transferências internacionais:
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": "descrição",
"email": "email@email.com",
"country" : "0840"
},
"debtor": {
"iban": "006500010000000000000"
}
}
Resposta:
{
"LoginUrl": "https://api.openbank.bancobest.pt/api/v2/Auth/Index/1-000000"
}
Lista de códigos para Transferências Internacionais
Natureza da Transferência - Obrigatório. (nature_code) Valores possíveis: o 052 - Transf. de não residentes (qualquer motivo); o 066 - Transf. entre contas de residente, em Portugal e no Exterior; o 068 - Transf. entre contas de emigrante, em Portugal e no Exterior; o 101 - Exportação/Importação de Mercadorias; o 292 - Viagens e Turismo - desp de viagem e estada turística; o 479 - Outros serviços fornecidos por empresas; o 483 - Serviços de educação; o 489 - Outros de serviços de natureza pessoal; o 622 - Transf. correntes privadas de residentes p/ não residentes;
Detalhes de Despesas - Obrigatório. (expenses_code) Valores possíveis: o SHA - Despesas partilhadas (Sha); o OUR - Sem despesas para o beneficiário (Our); o BEN - Sem despesas para o originador (Ben);
URL de Redirecionamento : (Parametro GET no URL)
| Variável | Valor exemplo | Descrição |
|---|---|---|
| oper_id | 1-BQMM39 | ID da operação de pagamento |
myapplication.com/loginReturn?oper_id=1-BQMM37
Pagamentos
Endereço POST
https://api.openbank.bancobest.pt/api/v2/Operation/InitiatePayment
Cabeçalho de Pedido
| Variável | Valor de Exemplo | Descrição |
|---|---|---|
| redirect_uri | myapplication.com/loginReturn | Endereço para o qual o utilizador da aplicação será redirecionado após a operação |
| response_type | 200 | Tipo de resposta. Atualmente este parâmetro não é usado, mas não pode ser nulo. |
| scope | user | Scope do utilizador. Atualmente este parâmetro não é usado, mas não pode ser nulo. |
| state | user | Valor que pode ser usado livremente pela aplicação, valor que será retornado após o login. |
| certificate | 9dFpJUCnQcwe80aAOH... | Certificado em base64 que contém a chave pública |
Exemplo de Corpo de Pedido para pagamento de serviços:
Corpo de Pedido (Formato JSON)
| Nome | Obrigatório? | Tipo | Dimensão | Formato | Descrição | Observações |
|---|---|---|---|---|---|---|
| creditor.payment_bill.entity | S | String | 5 | Entidade | ||
| creditor.payment_bill.reference | S | String | 9 | Referência | ||
| creditor.payment_bill.amount | S | String | 100 | Montante | ||
| creditor.description | S | String | 140 | Descrição | ||
| debtor.iban | N | String | 25 | Iban de origem. |
json
{
"creditor": {
"payment_bill": {
"entity": "22356",
"reference": "123456789",
"amount": "5",
},
"description": "",
},
"debtor": {
"iban": "006500010000000000000"
}
}
Corpo de Resposta (Formato JSON)
{
"LoginUrl": "https://api.openbank.bancobest.pt/api/v2/Auth/Index/1-000000"
}
Exemplo de Corpo de Pedido para pagamento de compras:
Corpo de Pedido (Formato JSON)
| Nome | Obrigatório? | Tipo | Dimensão | Formato | Descrição | Observações |
|---|---|---|---|---|---|---|
| creditor.payment_bill.enterprise | S | String | 5 | Empresa | ||
| creditor.payment_bill.reference | S | String | 9 | Referência | ||
| creditor.payment_bill.amount | S | String | 100 | Montante | ||
| debtor.iban | N | String | 25 | Iban de origem. |
json
{
"creditor": {
"payment_bill": {
"enterprise": "22356",
"reference": "123456789",
"amount": "5",
},
},
"debtor": {
"iban": "006500010000000000000"
}
}
Corpo de Resposta (Formato JSON)
{
"LoginUrl": "https://api.openbank.bancobest.pt/api/v2/Auth/Index/1-000000"
}
Exemplo de Corpo de Pedido para pagamento ao estado:
Corpo de Pedido (Formato JSON)
| Nome | Obrigatório? | Tipo | Dimensão | Formato | Descrição | Observações |
|---|---|---|---|---|---|---|
| creditor.state_bill.reference | S | String | 9 | Referência | ||
| creditor.state_bill.amount | S | String | 100 | Montante | ||
| debtor.iban | N | String | 25 | Iban de origem. |
json
{
"creditor": {
"state_bill": {
"amount": "12",
"reference": "123456789",
},
},
"debtor": {
"iban": "006500010000000000000"
}
}
Corpo de Resposta (Formato JSON)
{
"LoginUrl": "https://api.openbank.bancobest.pt/api/v2/Auth/Index/1-000000"
}
Exemplo de Corpo de Pedido para pagamento santa casa:
Corpo de Pedido (Formato JSON)
| Nome | Obrigatório? | Tipo | Dimensão | Formato | Descrição | Observações |
|---|---|---|---|---|---|---|
| creditor.santa_casa.player_card_num | S | String | 9 | Número de Jogador | ||
| creditor.santa_casa.amount | S | String | 100 | Montante | ||
| debtor.iban | N | String | 25 | Iban de origem. |
json
{
"creditor": {
"santa_casa": {
"amount": "12",
"player_card_num": "123456789",
},
},
"debtor": {
"iban": "006500010000000000000"
}
}
Corpo de Resposta (Formato JSON)
{
"LoginUrl": "https://api.openbank.bancobest.pt/api/v2/Auth/Index/1-000000"
}
Exemplo de Corpo de Pedido para pagamento segurança social:
Corpo de Pedido (Formato JSON)
| Nome | Obrigatório? | Tipo | Dimensão | Formato | Descrição | Observações |
|---|---|---|---|---|---|---|
| creditor.social_security.regime_type | S | String | 1 | Tipo de Regime | 3 - Serviço doméstico 4- Trabalhadores independentes 5- Seguro social voluntário 6- Produtores agricolas Açores | |
| creditor.social_security.reference_year | S | String | 4 | YYYY | Ano de referência | Só são permitidos os últimos 5 anos (Se estamos em 2019 só permite 2019,2018,2017,2016,2015,2014) |
| creditor.social_security.reference_month | S | String | 2 | MM | Mês de referência | Ex: 01,02,03,04,05,06,07,08,09,10,11,12 |
| creditor.social_security.beneficiary | S | String | 11 | Nº Beneficiário da Segurança Social | ||
| creditor.social_security.employer | N | String | 11 | Nº Beneficiário da Entidade Patronal | Se o regime_type = "3" então este campo é obrigatório | |
| creditor.social_security.remuneration_type | S | String | 1 | Montante | 1 - Mensal - Mês completo 2 - Mensal - Mês incompleto 3 - Horária | |
| creditor.social_security.remuneration_units | S | String | Unidades de Pagamento | Se o tipo de renumeração fpr diferente de "1", é obrigatório. | ||
| creditor.social_security.remuneration_monthly | S | String | Valor efetivo de renumeração mensal | |||
| debtor.iban | N | String | 25 | IBAN de Origem |
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
Descrição
De forma a tratar alguns tipos de pagaments, é necessário obter informação dos Top Ups / Carregamentos através da API TopsUpsGetPaymentInfo.
Funções Permitidas
- PSP_AS
Endereço POST
https://dev.openbank.bancobest.pt/sandbox/api/v2/Operation/TopsUpsGetPaymentInfo
Request Header
| Variável | Valor de Exemplo | Descrição | Obrigatório? |
|---|---|---|---|
| Authorization | OAuth oauth_consumer_key=0f4c0... | Esquema OAuth para Autorização. Ver documentação "Aceder à API" | Sim |
| Certificate | 9dFpJUCnQcwe80aAOHx7YWYlqisICXNnVSKiaiA9vGO8YnzlZoJcUVPJ/rZ68X8FD== | Chave públic do certificado. Ver documentação "Aceder à API" | Sim |
Exemplo de Corpo do Pedido. (Top Up):
Corpo de Pedido (Formato JSON)
| Nome | Obrigatório? | Tipo de Dados | Dimensão | Formato | Descrição | Notas |
|---|---|---|---|---|---|---|
| creditor.topup.entity_code | Sim | String | 5 | Código da Entidade | Informçaão de TopsUpsGetPaymentInfo (entityCode) | |
| creditor.topup.reference | Sim | Number | Telefone ou Referência | |||
| creditor.topup.amount | Não | Number | Quantia | |||
| creditor.topup.amount_desc | Não | String | 30 | Descrição da quantia | Não obrigatório se a Quantia estiver preenchida. Informação de TopsUpsGetPaymentInfo (amount) |
Corpo de Resposta (Formato JSON)
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"
}
Gweneric 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"
}
O Acess Token foi cancelado. O mais prov?vel ? um novo Access Token diferente do que foi passado no pedido ter sido criado para o mesmo utilizador. HttpStatusCode: 400
{
"Message": "EGEN003",
"ErrorDate": "2021-01-26T12:08:41.9591402Z",
"ErrorID": "37be13b57e6948ad9c0c610ba483fea2"
}