Confidential

Hub de Pagamento de Contas – API User Guide

Payments Hub
API – USER GUIDE

4
Confidential

Accounts Payment Hub– API User Guide

Throughout this material, concepts of payment APIs and DDA, onboarding, methods of use, technical
documentation, business rules, as well as examples of use will be presented.

2023 – 07 V1.1
1
Confidential

Accounts Payment Hub– API User Guide

1. Overview.................................................................................................................................................6
1.1 Advantages ....................................................................................................................................7
1.2 First Steps.......................................................................................................................................7
1.3 Work areas .....................................................................................................................................8
1.4 Transactional ...............................................................................................................................10
2. Onboarding ...........................................................................................................................................12
2.1 Own Payments .............................................................................................................................12
2.1.1 Workspace Type: PAYMENTS ................................................................................................12
2.2 Third-Party Payments ..................................................................................................................14
2.2.1 Workspace Type: DIGITAL_CORBAN .....................................................................................15
2.2.2 Workspace Type: PHYSICAL_CORBAN ...................................................................................15
2.3 Developers Portal ........................................................................................................................15
2.4 Technical Dpcumentation ............................................................................................................24
2.5 Certificates ...................................................................................................................................25
2.5.1 Digital certificates formats ....................................................................................................25
2.5.2 Digital certificates chain ........................................................................................................26
2.5.3 Types of certificate (ICP Certificates) ....................................................................................28
2.5.4 SSL Certificates (We do not accept this type of certificate) ..................................................29
2.6 Access credential .........................................................................................................................31
2.6.1 OAuth 2 ..................................................................................................................................31
2.6.2 Mutual TLS (mTLS) .................................................................................................................32
2.6.3 Access Token ..........................................................................................................................34
2.7 APIs URL .......................................................................................................................................37
2.8 Rate Limit .....................................................................................................................................42
2.9 Sandbox .......................................................................................................................................42
2.10 Production Environment .............................................................................................................42
3. Setup Vision ..........................................................................................................................................44
3.1 HTTP Methods .............................................................................................................................44
3.1.1 Status HTTP return code ........................................................................................................44
3.2 Workspaces..................................................................................................................................45
3.2.1 Workspace Rating ..................................................................................................................47
3.2.2 Workspace Creation (POST)...................................................................................................47

2023 – 07 V1.1
2
Confidential

Accounts Payment Hub– API User Guide

3.2.3 Workspace list query by CNPJ (GET) ......................................................................................51

3.2.4 Query by Workspace ID (GET) ...............................................................................................53
3.2.5 Workspace Maintenance (PATCH).........................................................................................54
3.2.6 Exclusion of a Workspace (DELETE) .......................................................................................58
4. 4. Transaction Vision ............................................................................................................................60
4.1 Payment status ............................................................................................................................61
4.2 Payment methods........................................................................................................................63
4.2.1 Santander Payment Slips and Other Bank Payment Slips .....................................................63
4.2.1.1 POST (Start paying a bond).............................................................................................64

4.2.1.2 PATCH (Performs the payment of an account) ..............................................................67

4.2.1.3 GET (Queries by ID the data/status of a payment) ........................................................70

4.2.1.4 GET (Paginated query of the payment data/status) ......................................................71

4.2.1.5 DDA (Authorized Direct Debit) .......................................................................................72

4.2.1.6 DDA Webhook ................................................................................................................76

4.2.2 Bar Code Collection ...............................................................................................................78

4.2.2.1 POST (Initiates payment from a barcode) ......................................................................78

4.2.2.2 PATCH (Makes payment of a barcode) ..........................................................................81

4.2.2.3 GET (Query by ID the payment data/status of a barcode).............................................84

4.2.2.4 GET (Consulta paginada dos dados/status de pagamento) ...........................................84

4.2.3 Pix Transfer ............................................................................................................................86

4.2.3.1 POST (Initiates the payment of a Pix) .............................................................................86

4.2.3.1.1 DICT key .....................................................................................................................86

4.2.3.1.2 Beneficiary - Branch and Account ..............................................................................88
4.2.3.1.3 QR Code .....................................................................................................................90
4.2.3.2 PATCH (Makes payment of a Pix) ...................................................................................94

4.2.3.2.1 Chave DICT .................................................................................................................94

4.2.3.2.2 Beneficiary – Branch and Account .............................................................................96
4.2.3.2.3 QR Code .....................................................................................................................97

2023 – 07 V1.1
3
Confidential

Accounts Payment Hub– API User Guide

4.2.3.3 GET (Query by ID the data/status of payment of a Pix) ...............................................100

4.2.3.4 GET (Paginated query of payment data/status)...........................................................101

4.2.4 Field by Field Tax..................................................................................................................103

4.2.4.1 POST (Initiates the payment of a field by field tax) .....................................................103

4.2.4.1.1 GARE ICMS ...............................................................................................................103

4.2.4.1.2 GARE ITCMD.............................................................................................................106
4.2.4.1.3 DARF .........................................................................................................................109
4.2.4.1.4 GPS ...........................................................................................................................111
4.2.4.2 PATCH (Makes payment of a field by field tax) ............................................................115

4.2.4.2.1 GARE ICMS ...............................................................................................................115

4.2.4.2.2 GARE ITCMD.............................................................................................................117
4.2.4.2.3 DARF .........................................................................................................................118
4.2.4.2.4 GPS ...........................................................................................................................120
4.2.4.3 GET (Query by ID the data/status of payment of a tax) ...............................................123

4.2.4.4 GET (Paginated query of payment data/status)...........................................................123

4.2.5 Vehicle Debts .......................................................................................................................125

4.2.5.1 GET (Queries debts of a renavam) ...............................................................................125

4.2.5.2 POST (Starts payment of a vehicle debt)......................................................................127

4.2.5.3 PATCH (Makes payment of a vehicle debt) ..................................................................130

4.2.5.4 GET (Queries by ID the payment data/status of a vehicle debt) .................................133

4.2.5.5 GET (Paginated query of payment data/status)...........................................................133

4.3 Payment schedules ....................................................................................................................135

4.4 Receipts......................................................................................................................................136
5. Version history....................................................................................................................................137

2023 – 07 V1.1
4
Confidential

Hub de Pagamento de Contas – API User Guide

OVERVIEW

2023 – 07 V1.1
5
Confidential

Accounts Payment Hub– API User Guide

1. Overview

The Santander Accounts Payment Application Programming Interface (“API”) is a feature created to
facilitate the management of accounts payable for our Clients, facilitating the payment of bank slips,
consumer bills or taxes that contain a bar code or field-to-field, pix transfer, vehicle debits and
consultation of DDA slips. The API not only helps manage “accounts payable”, but also enables the
creation of new business models.

With a focus on connecting services between companies, each API is associated with a single endpoint,
where the endpoint represents a connection URL to be called by the service user system to send data and
receive the response corresponding to the service that the endpoint represents. . Endpoints with
variations can be published to indicate different versions.

Request
Processing
Rersponse
Result
Client
Santander System
Example
Clearing chambers

2023 – 07 V1.1
6
Confidential

Accounts Payment Hub– API User Guide

1.1 Advantages

o The company that presents the service does not necessarily need to develop a function access
screen, leaving this effort to those who will use the provided service;
o Connection standardization, as all systems that will use the service know exactly which fields to
send or receive and which are the possible responses;
o Provide integration between systems built in different languages in an agile, secure and fully
compatible manner;
o Possess authentication layers generating access security in use;
o Reduction in the volume of data transferred, as the information exchanged is more direct and
follows simpler models than pre-set layouts in which some fields are repeated countless times;
o Publication of templates and patterns on open-use websites for developer communities.

Currently, APIs are the basis of our daily lives on the internet, allowing us to make purchases and register
on social networks, in a way that the banking sector could not be different. The target audience for
payment APIs are Clients who want to (i) automate “accounts payable” to make online payments and (ii)
create solutions to make payments available to their Clients using Santander as an intermediary.

1.2 First Steps

To use the APIs, the client must access the Developers Portal, where it will be possible to:

▪ Obtain technical documentation for development;

▪ Register the certificates;

▪ Generate the credentials for using Sandbox services and the production environment.

Portal Developers is a web platform created to connect systems, accessed through the link:
https://developer.santander.com.br.

2023 – 07 V1.1
7
Confidential

Accounts Payment Hub– API User Guide

APIs Clients
Access the Developers Portal
Has access to the APIs Library
Registers in the portal or PJ login
Registers the certificate and generates credentials
Carries out tests in Sandbox and has access to the production environment

1.3 Work areas

In order to use the Payments APIs, it is mandatory that the Client's accounts and the desired transactional
products are previously registered through Workspaces.

Workspaces is nothing more than work areas that allow the management of payment APIs. It is very
similar to an agreement, where the Client will be able to parameterize the debit accounts, being able to
indicate a main account and additional accounts and enable payment methods.

So what do we know about Workspaces:

• To use the APIs, it is mandatory that the accounts are registered in Workspaces;
• The accounts must belong to the same CNPJ root associated with the access credential;
• There is no limitation on the number of accounts;
• The Client may have several Workspaces;
• The main account is mandatory and will always be the charged account.

2023 – 07 V1.1
8
Confidential

Accounts Payment Hub– API User Guide

Setup vision
Client with the credentials in hand
Calls a Workspaces registration
Calls a Workspaces query by CNPJ
Calls a workspace query by ID
Calls a workspace exclusion
Santander registers a work area and returns a single ID to workspace
Santander returns a pages list of workspaces created
Santander returns a unit query by ID of workspace registered
Santander excludes workspace by ID registered

2023 – 07 V1.1
9
Confidential

Accounts Payment Hub– API User Guide

1.4 Transactional

After the Workspace registration, the Client is able to call the transactions available in the Payments Hub,
bringing greater agility in operations, transactions processed in real time, direct connection with the
clearinghouses Sefaz, CIP, SPI, etc.

Transaction vision
Calls the payment start
Calls the payment conclusion
Calls a query to validate payment status
Santander returns transaction validation data
Santander returns transaction conclusion data
Santander returns a query with transaction status

2023 – 07 V1.1
10
Confidential

Accounts Payment Hub– API User Guide

ONBOARDING

2023 – 07 V1.1
11
Confidential

Accounts Payment Hub– API User Guide

2. Onboarding

The Account Payments API is indicated for companies that need to make their payments to suppliers in
an automated, fast and secure way, directly from their management system and for those companies that
want to work as a Santander banking correspondent.

For companies that will make their own payments, it is necessary to have a work area, called Workspaces,
of the PAYMENTS type and for companies that will be a Santander bank correspondent, it is necessary to
have a work area of the type DIGITAL_CORBAN or PHYSICAL_CORBAN and watch the resolution.

For the payment of third parties, current BACEN regulations are being respected. CMN Resolution No.
4,935/2021 provides for the hiring of correspondents who act as service providers to financial institutions
and institutions authorized to operate by the Central Bank of Brazil.

2.1 Own Payments

2.1.1 Workspace Type: PAYMENTS

For those companies that want to make their own payments we have the PAYMENTS type in the
Workspace. In the user's view with the own payments category, we have the validation of the Payment
to Suppliers agreement. If you are a Client and already have an active agreement with the Internet Bank
for Legal Entities, you can go to the step to access the Developers Portal. Otherwise, access Internet
Banking Legal Entity and contract online here.

The payments available in the account payment API for the PAYMENTS type are: Santander securities and
other banks, bar collection, pix transfer, field-to-field tribute, vehicle debits and consultation and DDA
webhook.

2023 – 07 V1.1
12
Confidential

Accounts Payment Hub– API User Guide

Own payments
Has active PAGFOR agreement
No
Hiring Santander PAGFOR is easy and quick, all you have to do is access your Corporate Internet Banking and hire online
Acess: IBPJ > Pagamento a Fornecedores > Convênio > Contratar Pagamento a Fornecedor
Yes
Access Developers Portal
Register in the Portal or PJ login
Register the certificate and generate credential
Call the Token generation endpoint
Call a workspace registration of the Type:

2023 – 07 V1.1
13
Confidential

Accounts Payment Hub– API User Guide

2.2 Third-Party Payments

For companies that wish to be a Digital or Physical Banking Correspondent (“Corban”), we have the
CORBAN journey, with the types DIGITAL_CORBAN and PHYSICAL_CORBAN. If the company has already
hired Corban, you can go to the access step to the Developers Portal.

Third-Party Payment
Has active CORBAN agreement
No
Contract with your manager or Cash Expert
Yes
Access the Developers Portal
Register in the portal or PJ login
Register the certificate and generate credentials
Call the TOKEN generation endpoint
Call a workspace registration of the type:

2023 – 07 V1.1
14
Confidential

Accounts Payment Hub– API User Guide

2.2.1 Workspace Type: DIGITAL_CORBAN

The Digital Banking Correspondent is a solution that enables our business partners to offer their Clients a
payment service, using the bank's structure and available products, such as payments, receipts and
reconciliation. Partners can, through their website, applications or digital solutions, provide the payment
of utility bills, bills from the Bank itself and from other banks, taxes with bar codes and field-by-field taxes.

In short, it is a service that captures Clients and serves them through a digital platform, so instead of a
Client physically going to request a service, the Corban Digital audience can access it online.

The implementation and integration model is via API, the technology involves communication between
systems through programming standards. Transactions will be debited from the Client's account in one
unit due to the characteristics of the product.

The target audience are corporate clients, from any segment and who are account holders, public or
private entities that are interested in using a structured product to manage their clients' commitments.

2.2.2 Workspace Type: PHYSICAL_CORBAN

The Physical Banking Correspondent is a solution that allows a regularly established legal entity, linked to
a financial institution in a sub-established way from another correspondent, to provide services to
Santander.

2.3 Developers Portal

To use the Payments APIs, Clients must access the Developers Portal, where it will be possible to:

• Obtain technical documentation for development;

• Register the certificates;
• Generate service usage credentials.

The Developer Portal is a web platform created to connect systems, accessed through the link: <
https://developer.santander.com.br > and follow the step by step to register:

2023 – 07 V1.1
15
Confidential

Accounts Payment Hub– API User Guide

Registration Flow
Click in “Cadastre-se”
In “Criar uma conta” and enter your data
Check the box “Termos de Uso”
Click in “Save”

After completing the registration: 1. enter the valid email address and after receiving the confirmation
email; 2. enter the confirmation code and then return to the home page and click on “Login” and follow
the step by step by typing your “E-mail” and “Password” and clicking on “Login”.

For a better access experience to the Developers Portal, PJ login and follow the rules of use below:

3. Click in “Login”;

4. Click in “Acesse com sua conta PJ;

2023 – 07 V1.1
16
Confidential

Accounts Payment Hub– API User Guide

5. Click in “Agência”
6. Click in “Conta”
7. Enter the “Usuário’
8. Enter the “Senha”
9. Click in “Login”

i. Only the Master User or a user invited by the Master can create applications in Production;
ii. It is necessary that the Master User has the Santander ID enabled;
iii. It is necessary that the Master User has an email registered to his user;

2023 – 07 V1.1
17
Confidential

Accounts Payment Hub– API User Guide

iv. In order for the Master User to have access to two or more companies, within the Portal, it is
necessary that he/she does the PJ Login for the different companies to be associated with his/her
account.

After logging in with the PJ account, access the account options icon next to the name “Sign out” and click
on step 10 in “Minhas aplicações”. To create an application, first select an environment: “Sandbox” or
“Produção”.

For the application in Sandbox follow the step by step below:

Passo a Passo:

. Clicar em riar no a a i a o ;
. Inserir um nome para a aplica o;
. Inserir o cer cado digital;
5. Inserir alguma informa o na aplica o;
6. Escolher o produto ue dese a reali ar os testes em sandbox;
. Clicar em Paga n o d on as and o ;
8. Clicar em En iar .
8

2023 – 07 V1.1
18
Confidential

Accounts Payment Hub– API User Guide

. Click in “Criar nova aplica o”;

13. Enter a name for the application;
14. Enter the digital certificate;
15. Enter any information in the application;
16. Choose the product which you wish to test in Sandbox;
14. Click in “Pagamento de Contas (Sandbox);
8. Click in “Enviar”

After clicking on “Enviar”, go to “Minhas Aplicações” the credentials will be available to start the tests in
Sandbox, just click on the icons next to the names ClientID and Client Secret to copy the credentials and
start the tests:

To create an application in Production, make sure that step 20 is in “Produ o” and click in “Aplica ões”

2023 – 07 V1.1
19
Confidential

Accounts Payment Hub– API User Guide

On the tab “Nova aplicação” we have two types of applications, how to know which type of application
you are going to create, check below the rules to choose the options “Sou um desenvolvedor” or “Utilizo
um parceiro”.

Usage rules for creating an application:

i. I am a developer
▪ Will I be doing the API development?
If yes, I'm a developer.
▪ I am going to use a partner for my API development, but they are not listed as “a
partner”?
If yes, I'm a developer.

Passo a Passo:

. Selecione o o d s n o dor ;
. Inserir um nome para a aplica o;
. Inserir o cer cado digital;
5. Inserir alguma informa o na aplica o;
6. Escolher o produto ue dese a e clicar em Paga n os d on as ;
. Clicar em En iar .

Step by step:
. Select “Sou desenvolvedor”;
23. Enter a name for the application;
24. Enter the digital certificate;
25. Insert any information on the application;
6. Choose the product you wich and click in “Pagamento de Contas”;
. Click in “Enviar”

2023 – 07 V1.1
20
Confidential

Accounts Payment Hub– API User Guide

ii. I use a partner

▪ I am going to use a partner to develop the API and is this partner registered in the list of
partners?
If so, use a partner.

Step by step:
8. Select “Use a partner”
29. Enter a name for the application;
0. Select the desired “Parceiro”
. Select the desired “Produto”;
. Clic =k in “Enviar”

After sending the creation of the applications that contain the credentials, the user will receive
an email (which is registered as the master user).

After creation, a new window will open informing you that a new request for creation has been opened.
Then refresh the page to view the created application.

2023 – 07 V1.1
21
Confidential

Accounts Payment Hub– API User Guide

33. In this space, two keys were generated, the “ i n ID” and the “ i n r ”. To copy, just click on
the button next to the Client ID to copy the content and to copy the Client Secret, just repeat the same
procedure.

34. After clicking the button and copying the content, a message will appear that the content has been
copied to the clipboard. To paste the result, just open some document editor (word, notepad) and paste
the content.

35. To view the technical documentation of the selected product, just click on “Documentação Técnica”.

To invite a user, you need to access the Companies page and follow the step by step below:

2023 – 07 V1.1
22
Confidential

Accounts Payment Hub– API User Guide

Step by step:
6. Click in “Membros”;
. Click in “Convidar”;
38. Type the emailof the people who will be invited;
9. Click in “Convidar”

For the guest user to enter the portal, he must necessarily create an account on the Portal.

2023 – 07 V1.1
23
Confidential

Accounts Payment Hub– API User Guide

Step by step:
0. Click in “Produ o”;
. Click in “Verificar convites”;
. Click in “Aceitar”;
. After accepting, click in “Minhas aplica ões”.

The Developer Portal is a platform created to connect partners. In it, you will find all the necessary
information on how to access our APIs and their specifications, in addition to the necessary
documentation. Our goal is to enhance the development of your digital solutions, improving your
products and services.

2.4 Technical Dpcumentation

Swagger is the technical documentation and it is an open source application that helps developers in the
processes of defining, creating, documenting, consuming APIs, even helping with code generation. With
this tool, the aim is to standardize the integration to the service, with the presentation of the resources
that an API has: endpoints, received data, returned data, HTTP codes, authentication methods, among
others.

2023 – 07 V1.1
24
Confidential

Accounts Payment Hub– API User Guide

2.5 Certificates
Certificates must be issued by the client and follow some sending rules, check the rules below:

It is important to point out that Banco Santander has no relationship with Certification Authorities and
that the list only seeks to illustrate those that meet the security requirements.

Rules for sending a digital certificate

• Must be in .PEM, .CER or .CRT format;

• We accept A1 type certificates (ICP);

• The files must have the complete chain, containing: root, intermediary and leaf;

• Size must be 2048 bits;

• Must have a minimum validity of 90 days;

• It must have reliable external Certifying Entities, here we accept those from ICP-Brasil, in this link
you can check which ones are: < https://estrutura.iti.gov.br/ >;

• The certificate must have the attribute “Key Usage” enabled for “Digital signature” or “Key
agreement", and the “Enhanced Key Usage” containing the extension "TLS Web Client
Authentication (1.3.6.1.5.5.7.3.2).

Notes:

• We do not accept self-signed certificates;

• We recommend using different certificates for production and approval environments

(Sandbox).

2.5.1 Digital certificates formats

Digital certificates can be found in different file formats, depending on the context and purpose of the
certificate. Here are some of the common file formats for digital certificates:

2023 – 07 V1.1
25
Confidential

Accounts Payment Hub– API User Guide

I. PEM (Privacy-Enhanced Mail): The PEM format is widely used and is a standard for certificates and
private keys. PEM files are base64 encoded and have .pem, .crt, .cer, or .key file extensions;
II. DER (Distinguished Encoding Rules): The DER format is also widely used and is a binary
representation of a certificate. DER files usually have a .der or .cer extension;
III. PFX/P12 (Personal Information Exchange): The PFX format is a container that can include the
digital certificate, the corresponding private key, and optionally the intermediate certificate
chains. PFX files have .pfx or .p12 extensions;
IV. PKCS#7/P7B: The PKCS#7 or P7B format is used to store digital certificates in a compressed format.
P7B files usually contain certificates in PEM or DER format and can have .p7b or .p7c extensions;
V. PKCS#12/PFX: The PKCS#12 format is similar to PFX and is used to store digital certificates, private
keys, and intermediate certificate chains in an encrypted container. PKCS#12 files have .pfx or .p12
extensions.

public and private key:

Usually when buying a certificate the file comes in PFX format. The client is able to segregate the
public and private key from this file, and with that he will have two .CRT, .CER or .PEM files.
The Client must not send the PFX file or the PRIVATE key file to Santander. The client must send
ONLY the public key of the certificate.

2.5.2 Digital certificates chain

The chain hierarchy of digital certificates follows a tree structure, where each certificate is linked to a
superior certificate, except for the root certificate. The certificate chain hierarchy involves several entities,
including certificate authorities (CAs) and certificate issuing entities. Below you can see an overview of
how the certificate chain hierarchy works:

I. Root certificate: At the top of the hierarchy is the root certificate, which is issued by the root CA.
The root certificate is self-signed, which means that the root CA generates and signs its own

2023 – 07 V1.1
26
Confidential

Accounts Payment Hub– API User Guide

certificate, establishing its trust and identity. The root certificate is pre-installed on operating
systems and browsers and serves as the initial trust point;
II. Intermediate Certificate Authorities: Below the root certificate are intermediate certificate
authorities (intermediate CAs) that issue certificates to entities and end users. Intermediate CAs
are also trusted entities and issue certificates using their own private key. Certificates issued by
intermediate CAs are linked to the root certificate via digital signature.

III. Leaf certificate: Also known as an end certificate or end certificate, it refers to the digital certificate
at the end of the certification hierarchy, which is issued to a specific entity such as a website, email
server or end user. In the structure of the certificate chain, the leaf certificate is the last certificate
in the hierarchy, as it does not issue certificates to other entities. Instead, it is signed by an
intermediate certification authority (intermediate CA) in the certificate chain. The leaf certificate
contains information about the specific entity it represents, such as the website's domain name
or email address, along with its corresponding public key. This certificate is used to authenticate
the identity of the subject and establish a secure connection in encrypted communications..

It is important to remember that trust in the certificate chain depends on trust in the root certificate and
the intermediate CAs involved. Trust is established through pre-installation of root certificates on
operating systems and browsers and through reputation and trust in intermediate CAs.

The certificate chain hierarchy is essential to ensure the authenticity and security of encrypted
communications. It allows parties to trust the identities presented by certificates and establish secure and
trusted connections in digital environments.

Check below the chair hierarchy of ICP-Brasil:

2023 – 07 V1.1
27
Confidential

Accounts Payment Hub– API User Guide

2.5.3 Types of certificate (ICP Certificates)

There are 12 (twelve) types of digital certificates, initially foreseen, for final users of ICP-Brasil, 8 (eight)
related to Digital Signature (A1, A2, A3, A4, T3, T4, A CF-e-SAT and OM-BR) and 4 (four) with secrecy (S1,
S2, S3 and S4).

They can be classified according to their application or encryption levels, but the most common are the
A1 and A3 types. The main difference between them is in the way they are stored, where the A1 is a
certificate that is generated in digital file format, that is, it is possible to carry out manipulation,
installation on the computer and backup copies of it. The A3 type is a certificate that is stored on a physical
device, such as a token or a smart card. Below you can find the complete list of certificate types:

▪ Type A certificate - Digital Signature

This is the most popular type of Digital Certificate, its main benefit is to perform digital signatures,
identifying the holder, attesting to the authenticity of the operation and confirming the integrity of the
signed document. That is, everything that is done through the Certificate has legal validity, similar to your
own handwriting signature, only in the virtual world. The issuing method involves face-to-face or virtual
interview and documentation validation.

▪ Type S certificate - Confidentiality Certificates

The Type S Digital Certificate is used to guarantee secrecy of the transaction. With it, it is possible to
encrypt, for example, an e-mail, which becomes accessible only with the use of an authorized Digital

2023 – 07 V1.1
28
Confidential

Accounts Payment Hub– API User Guide

Certificate to open it. In this way, confidential content becomes inaccessible to unauthorized
persons/hackers.

▪ Type T certificate - Confidentiality Certificates

The T-type Digital Certificate is better known as a time stamp, or timestamp. It is like a stamp, which
attests to the existence of an electronic document or digital signature at a given date and time.

▪ Type A CF-e-SAT certificate

They can only be issued for equipment that is part of the Electronic Tax Receipt Authentication and
Transmission System - SAT-CF-e, following the CONFAZ regulations.

▪ OM-BR type certificate - Metrological Object type certificates

Metrological Object - COM-BR certificates can only be issued for metrological equipment regulated by
Inmetro.

2.5.4 SSL Certificates (We do not accept this type of certificate)

In addition to the ICP certificates mentioned above, there are also SSL-type certificates, which are web
domain certificates. These are the most common certificates used worldwide. There are three types of
SSL certificate available today: Extended Validation (SSL EV); Organizational Validation (SSL OV); and
Domain Validation (SSL DV). Encryption levels are the same for each certificate, which differs from the
enablement and verification processes required to obtain the certificate..

▪ Extended Validation SSL Certificate (SSL EV)

With an SSL EV, the Certificate Authority (CA) verifies the applicant's right to use a specific domain name
and performs a full company verification. The process for issuing EV SSL Certificates is strictly defined in
the EV Guidelines, formally endorsed by the CA/Browser Forum in 2007. All steps required by a CA before
issuing a certificate are specified here, including:

I. Check the legal, physical and operational existence of the entity;

2023 – 07 V1.1
29
Confidential

Accounts Payment Hub– API User Guide

II. Check that the identity of the entity matches the official records;
III. Check that the entity has exclusive right to use the domain specified in the EV SSL certificate;
IV. And check that the entity has properly authorized the issuance of the EV SSL certificate.

▪ Organization Validation Certificates (SSL OV)

The CA verifies the applicant's right to use a specific domain name AND performs company verifications.
Additional verified company information is displayed to Clients when they click on the Secure Site Seal,
providing greater visibility into who is behind the site and the associated increased trust. The company
name also appears on the certificate in the ON field.

▪ Domain Validation Certificates (SSL DV)

The certification authority verifies the applicant's right to use a specific domain name. No company
identity information is verified and no information is displayed other than the encryption information in
the Secure Site Seal. While you can be sure that your information is encrypted, you cannot be sure who is
actually on the receiving end of that information..

Use of SSL certificates:

Since the process of issuing SSL certificates is more focused on validating a web domain, we do not
accept this type of certificate. The certificate currently accepted by Santander is the type ICP A1,
where there is rigorous validation facing the company.

2023 – 07 V1.1
30
Confidential

Accounts Payment Hub– API User Guide

2.6 Access credential

With the certificate registered in the bank's systems, access credentials are generated and consist of 2
pieces of information:

Client Id - It is a public identifier for applications (understood as the “user” of the application). Some call
it APP Key. Even if it's public, it's best not to be disclosed to third parties, it can be formatted as a 32-
character hexadecimal string. It must also be unique across all clients handled by the authorization server.
If the client id is discovered by others, it will be a little easier to create phishing attacks against an
application;

Client Secret - It is an access “key” known only by the application requesting the resource and by the
authorization server. It must be random enough not to be easily reproduced or discovered, and it serves
to ensure that the application really knows who owns this information.

With the credentials, you must request an access token (Access Token) generated by OAuth 2 that
represents an authorization protocol that allows an application to authenticate itself in another. The
requesting application (client id) requests access permission for a system that owns a resource
(authorizer). The owner system may or may not grant access to the application. Once permission is
granted, it can be revoked at any time.

2.6.1 OAuth 2

OAuth 2.0 is an authorization protocol and was primarily designed as a means of granting access to
OpenAPI.

OAuth 2 was built on top of 4 roles, being:

▪ Resource Owner: person or entity granting access to your data. Also called resource owner.
▪ Resource Server: the API that is exposed on the internet and needs data protection. To gain access
to its content, a token is required, which is issued by the authorization server.

2023 – 07 V1.1
31
Confidential

Accounts Payment Hub– API User Guide

▪ Authorization Server: responsible for authenticating the client id and issuing access tokens. It is
he who has the information of the resource owner, authentic and interacts with the Resource
Server after identifying the client id.
▪ Client: it is the application that interacts with the Resource Owner, such as the browser, speaking
in the case of a web application. In our case, this role belongs to the resource requesting system..

OAuth 2.0 mTLS client authentication and certificate-bound Access Tokens is a specification of RFC 8505.

The general flow of token request, exchange and response goes as follows:

1. The Client makes the authorization request, providing the client ID and the client secret, also
providing an endpoint to send the access token;
2. Santander authenticates the Client and verifies that the requested scopes are allowed;
3. The Client interacts with Santander to grant access;
4. Santander redirects back to the Client with an access token;
5. With the access token, the client requests access to the API.

2.6.2 Mutual TLS (mTLS)

mTLS is a method for mutual authentication, ensuring that parties at either end of a network connection
are who they claim to be, helping to keep APIs secure. The Access Token (JWT) is issued with the
FingerPrint of the Certificate for validating security on the Gateway and is a short-lived token (15 min)
used to access the Santander APIs.

Access Token (JWT) linked to mTLS guarantee that only the party in possession of the private key
corresponding to the certificate can use the token to access the associated resources. Access Tokens
contain the certificate thumbprint.

2023 – 07 V1.1
32
Confidential

Accounts Payment Hub– API User Guide

Client
Client using the Santander OpenAPI
Workspaces
Payment slips
Collection payments
PIX Transfer
DDA
Vehicle debits
Duties
Other products
Santander
mTLS Flow
Start communication
Presents server certificate
Presents client certificate
Approves communication
Obtains Access Token (ClientID + Client Secret)
Returns access token (JWT)
Consumption od Santander APIs (ClientID + JWT)
API gateway (open)
Validates Client certificate
Validates JWT
Authenticatin/Authorization
Performs security validations for the access
Santander API

2023 – 07 V1.1
33
Confidential

Accounts Payment Hub– API User Guide

2.6.3 Access Token

JWT (JSON Web Token) is an RFC 7519 specification for performing authentication between two parties
through a signed token that authenticates a web request. This token is a Base64 code that stores JSON
objects with the data that allow authentication of the request.

To generate an Access Token and make calls to the Payments Hub, follow the steps in the Postman tool
below:

I. Certificate import
Click on the tool icon in Postman and then on “Settings”:

Access the “ r ifi a s” tab and click on “Add r ifi a ”:

2023 – 07 V1.1
34
Confidential

Accounts Payment Hub– API User Guide

Fill in the “Hos ” field with: trust-sandbox.api.santander.com.br (Sandbox) or trust-

open.api.santander.com.br (Production Environment) import the CRT file and the KEY file by clicking on
“ Fi ” (if the certificate is in PFX format, import it into the PFX file and include the “Pass hras ”),
then click on “Add”.

2023 – 07 V1.1
35
Confidential

Accounts Payment Hub– API User Guide

II. JWT Generation

In the POST method enter the URL <https://trust-sandbox.api.santander.com.br/auth/oauth/v2/token>
for Sandbox and Production Environment <https://trust-
open.api.santander.com.br/auth/oauth/v2/token>.

Click on the “Body” tab and on the “ -www-form- r n od d” item and fill in the information “ i n _id
: Ins r h i n ID”, “ i n _s r : Ins r h i n r ” and “gran _ y : i n _ r d n ia s”.
When clicking on “ nd”, the JWT will be generated in the field “a ss_ ok n”:

III. Including JWT in API calls

Click on the tab “Authorization”, select the Type “OAuth 2.0” and paste the JWT on the field “Token”:

2023 – 07 V1.1
36
Confidential

Accounts Payment Hub– API User Guide

Click on the tab “Headers” and include the headera “X-Application-Key: (client_id)”:

After these steps, just continue the calls in the Payments Hub normally. If it starts to return a 401 error,
generate a new JWT and replace it in the “A horiza ion” tab, as shown in step II and III.

2.7 APIs URL

▪ JWT generation URLs

Sandbox

POST: https://trust-sandbox.api.santander.com.br/auth/oauth/v2/token

productive environment

POST: https://trust-open.api.santander.com.br/auth/oauth/v2/token

▪ Sandbox environment URLs:

Workspaces

POST: https://trust-sandbox.api.santander.com.br/management_payments_partners/v1/workspaces

PATCH: https://trust-sandbox.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id

GET per ID: https://trust-sandbox.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id

GET per CNPJ: https://trust-sandbox.api.santander.com.br/management_payments_partners/v1/workspaces

DELETE: https://trust-sandbox.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id

Bank Slip Payments

2023 – 07 V1.1
37
Confidential

Accounts Payment Hub– API User Guide

POST: https://trust-
sandbox.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/bank_slip_payments

PATCH: https://trust-
sandbox.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/bank_slip_payments/:bank_slip_p

ayment_id

GET: https://trust-
sandbox.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/bank_slip_payments/:bank_slip_p

ayment_id

Barcode Payments

POST: https://trust-
sandbox.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/barcode_payments

PATCH: https://trust-
sandbox.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/barcode_payments/:barcode_pay
ment_id

GET: https://trust-
sandbox.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/barcode_payments/:barcode_pay
ment_id

Pix Payments

POST: https://trust-
sandbox.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/pix_payments

PATCH: https://trust-
sandbox.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/pix_payments/:pix_payment_id

GET: https://trust-
sandbox.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/pix_payments/:pix_payment_id

Vehicle Taxes Payments

GET: https://trust-
sandbox.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/available_vehicle_taxes

2023 – 07 V1.1
38
Confidential

Accounts Payment Hub– API User Guide

POST: https://trust-
sandbox.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/vehicle_taxes_payments

PATCH: https://trust-
sandbox.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/vehicle_taxes_payments/:vehicle_

tax_id

GET: https://trust-
sandbox.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/vehicle_taxes_payments/:vehicle_

tax_id

Taxes by Fields Payments

POST: https://trust-
sandbox.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/taxes_by_fields_payments

PATCH: https://trust-
sandbox.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/taxes_by_fields_payments/:taxes_
by_fields_payment_id

GET: https://trust-
sandbox.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/taxes_by_fields_payments/:taxes_
by_fields_payment_id

▪ URLs do ambiente Produção:

Workspaces

POST: https://trust-open.api.santander.com.br/management_payments_partners/v1/workspaces

PATCH: https://trust-open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id

GET por ID: https://trust-open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id

GET por CNPJ: https://trust-open.api.santander.com.br/management_payments_partners/v1/workspaces

DELETE: https://trust-open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id

Bank Slip Payments

2023 – 07 V1.1
39
Confidential

Accounts Payment Hub– API User Guide

POST: https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/bank_slip_payments

PATCH: https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/bank_slip_payments/:bank_slip_pay

ment_id

GET por ID: https://trust-

open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/bank_slip_payments/:bank_slip_pay

ment_id

GET lista: https://trust-

open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/bank_slip_payments?_limit=&_offset

=&_sort=&initialDate=2023-05-20&finalDate=2023-05-26&status=PAYED

DDA: https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/available_bank_slips?_limit=&_offset

=&_sort=&beneficiaryDocument=63918424000150&bankNumber=&titleOrigin=OWN&originAggregates=&originAuthorized=

0&titleSituation=OPEN_TO_EXPIRE&initialIssueDate=2022-01-01&finalIssueDate=2022-12-
31&initialValue=0.0&finalValue=0.0&initialDueDate=2022-10-01&finalDueDate=2022-10-30

Barcode Payments

POST: https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/barcode_payments

PATCH: https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/barcode_payments/:barcode_payme

nt_id

GET por ID: https://trust-

open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/barcode_payments/:barcode_payme

nt_id

GET lista: https://trust-

open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/barcode_payments?_limit=&_offset=

&_sort=&initialDate=2023-05-01&finalDate=2023-05-10&status=PAYED

Pix Payments

2023 – 07 V1.1
40
Confidential

Accounts Payment Hub– API User Guide

POST: https://trust-open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/pix_payments

PATCH: https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/pix_payments/:pix_payment_id

GET por ID: https://trust-

open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/pix_payments/:pix_payment_id

GET lista: https://trust-

open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/pix_payments?_limit=&_offset=&_so
rt=&initialDate=2023-05-01&finalDate=2023-05-10&status=PAYED

Vehicle Taxes Payments

GET: https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/available_vehicle_taxes

POST: https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/vehicle_taxes_payments

PATCH: https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/vehicle_taxes_payments/:vehicle_tax_

id

GET por ID: https://trust-

open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/vehicle_taxes_payments/:vehicle_tax_
id

GET lista: https://trust-

open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/vehicle_taxes_payments?_limit=&_of
fset=&_sort=&initialDate=2023-05-01&finalDate=2023-05-10&status=PAYED

Taxes by Fields Payments

POST: https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/taxes_by_fields_payments

PATCH: https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/taxes_by_fields_payments/:taxes_by_

fields_payment_id

2023 – 07 V1.1
41
Confidential

Accounts Payment Hub– API User Guide

GET por ID: https://trust-

open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/taxes_by_fields_payments/:taxes_by_

fields_payment_id

GET lista: https://trust-

open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/taxes_by_fields_payments?_limit=&_

offset=&_sort=&initialDate=2023-05-01&finalDate=2023-05-10&status=PAYED

2.8 Rate Limit

The rate limit is the number of API calls an application can make in a given period. If this limit is exceeded,
all API consumers will receive an HTTP 429 status code until the restriction time interval, normally in
seconds, is exceeded. It is important to note that Rate Limiting is applied globally to the API, that is, the
call limit is unique and does not depend on which application is consuming the API..

For the Payment Hub, the rate limit has a value of 10 TPS.

2.9 Sandbox
To access the Sandbox, just log in to the Developers Portal, create your application and access your
credentials. With these credentials, you access our Sandbox environment. On the Portal, you can
download our postman collection and integrate the Sandbox directly into your system to explore our APIs.

2.10 Production Environment

To access the production environment, your company will need to be a Santander account holder. For
Own Payments, you only need to have an agreement with Payments to Suppliers, and for Third Party
Payments, you need a corban contract, with this, any user indicated by the company will be able to access
the Developer Portal and request credentials, as well as register the certificate. On the Portal, you can
download our postman collection of endpoints in production and integrate directly into your system to
explore our APIs.

2023 – 07 V1.1
42
Confidential

Accounts Payment Hub– API User Guide

SETUP VISION

2023 – 07 V1.1
43
Confidential

Accounts Payment Hub– API User Guide

3. Setup Vision

In order to access the client system and consume the payment APIs, it is necessary to register one or more
Workspaces, with the Workspace being the “gateway” to access the Transactional Payments Hub.

3.1 HTTP Methods

The Hypertext Transfer Protocol (HTTP) is a protocol used to ensure the standardization of communication
between APIs using a path (URL). This method uses some verbs to represent its functions and has an error
pattern for possible “returns”, being designed to allow communication between clients and servers..

The most used HTTP methods in API's are:

▪ GET - Used to retrieve some information (query);

▪ POST - Used to add or create a record;
▪ DELETE - Used to remove certain information;
▪ PATCH - Used to change specific information of a given record.

3.1.1 Status HTTP return code

In the HTTP protocol there is also the use of return codes for a good understanding when a request was
successful or unsuccessful in a simplified and standardized way.

The statuses are composed of 3 digits and in a generic way:

▪ 200 - Successful request, indicates success;

▪ 400 – Indicates Client information error;
▪ 500 – Indicates Server error;

And each of them can unfold into more specific ones.:

▪ 201 - Request successful, resource created;

▪ 204 - The server successfully served the request and there is no content to return;

2023 – 07 V1.1
44
Confidential

Accounts Payment Hub– API User Guide

▪ 401 - Unauthorized/authenticated, the request cannot be answered because the authentication

credentials were not informed or are invalid.
▪ 403 - Unauthorized, the request was understood by the server, but it refuses to execute it because
the client is not authorized;
▪ 404 - Information not found;
▪ 406 - Indicates that the client requested the response in a message format that is not supported
by the service provider;
▪ 409 - Indicates that the request could not be processed because of conflict with the current status
of the target resource or with other resources;
▪ 410 - The destination resource is no longer available on the source server;
▪ 415 - Format not supported by this method on target resource;
▪ 422 - Entity not processed/inadequate;
▪ 429 - The user sent too many requests in a certain period;
▪ 501 - The server does not support the functionality required to fulfill the request;
▪ 503 - Server error;
▪ 504 – Server error, request timeout.

It is part of the process to execute an action in an API through one of the verbs and receive a return code
indicating the status of that request. As the codes are standards, the application can implement standard
behaviors according to the return codes.

3.2 Workspaces
In the Payments APIs, the Payment Hub user can make up to five (5) calls in the Workspace, which are:

2023 – 07 V1.1
45
Confidential

Accounts Payment Hub– API User Guide

▪ POST – Creation of a Workspace;

▪ GET-ALL – Workspace list query by CNPJ;
▪ GET – Workspace query by ID;
▪ PATCH – Maintenance/Alteration of a Workspace;
▪ DELETE – Deletion of a Workspace.

Client registerd a workspace

Client checks the workspaces created and which are associated to the access credential
Client consults a workspace created by ID
Client makes changes of a workspace registered
Client excludes a workspace registered
Client can create several workspaces
It is mandatory that a Santander current account is registered
The client can add a main account and several additional accounts in a workspace
The accounts can belong to the same root CNPJ associated to the access credential
There is no limit of registered accounts
The mnaisn account wil always be charged

2023 – 07 V1.1
46
Confidential

Accounts Payment Hub– API User Guide

3.2.1 Workspace Rating

In the Payments Hub we have some Workspace classifications for different Client profiles:

▪ PAYMENTS for the Client who wants to make their own payments;
▪ DIGITAL_CORBAN for the client who wants to make third-party payments digitally;
▪ PHYSICAL_CORBAN for the client who wants to make payments and be bank correspondents in
an understated or direct way.

3.2.2 Workspace Creation (POST)

To create a Workspace in Payments Hub, you need to consume the POST/workspaces method endpoint.

Request
Field Description Mandatory
type Workspace classification, can be PAYMENTS, Yes
DIGITAL_CORBAN and PHYSICAL_CORBAN.
mainDebitAccount The field mainDebitAccount is the Workspace main Yes
account, in this field you must insert the branch, the
branch number that can have up to 4 digits and you
must insert the number, the account number that
must contain a maximum of 12 digits and if the
account has only one digit, add leading zeros.
description Workspace description and can be up to 30 No
characters long.
tags The tag field is the Workspace identification and No
must have a maximum of 20 characters and the
number of tags must not exceed 5.
addicionalDebitAccounts If the customer has additional accounts, they are No
inserted in this field and follow the same rule as in
the mainDebitAccount field, in this field you have to
insert the branch, the branch number that can have

2023 – 07 V1.1
47
Confidential

Accounts Payment Hub– API User Guide

up to 4 digits and you have to insert the number, the

account number that must contain up to a maximum
of 12 digits and if the account has only one digit, add
the zeros to the left.
place Registration of the sub-established physical bank No
correspondent point for the type
PHYSICAL_CORBAN. In this field, fill in the cnpj,
corporation name (corporateName), fantasy name
(fantasyName), email, telephone number (phone)
and address information (address) such as: zip code
(zipCode), state (state), city ( city), neighborhood
(district), street (street), address number (number)
and complement (complement).
webhookURL Field to include the DDA webhook URL. The URL is for No
the customer to receive notifications when a billing
slip is issued in their name. Must start with https://
and have a maximum of 350 characters.
pixPaymentsActive PIX transfer payment method: DICT, QR Code and No
Agency and account.
bankSlipPaymentsActive Payment method for bank slips Santander and other No
banks.
bankSlipAvailableActive Modality to enable the DDA, it is necessary that when No
enabling the DDA. Make sure
bankSlipPaymentsActive is also enabled by enabling
the DDA flag.
barCodePaymentsActive Mode of payment of concessionaires and taxes with No
barcodes.
taxesByFieldPaymentsActive Field-by-field tribute payment method: GPS, DARF, No
GARE ICMS, and GARE ITCMD.

2023 – 07 V1.1
48
Confidential

Accounts Payment Hub– API User Guide

vehicleTaxesPaymentsActive Renavam payment method: IPVA, DPVAT and No

Licensing.
bankSlipAvailableWebhookActive Modality to enable the DDA webhook. Make sure you No
enter the URL you want to receive notification of slips
issued for your CNPJ in the webhookURL flag.
To activate the payment method in Workspace, the customer must send the product fields as true, if the
customer does not inform the field, false will be sent by default and in the case of the webhookURL as
null.

For types DIGITAL_CORBAN and PHYSICAL_CORBAN, the modality pixPaymentsActive must be sent as false,
as there is no Pix Transfer product for this Workspace classification.

Response – Status 201 (Workspace Created)

Field Description Mandatory
id The Id field is unique to the customer in the Yes
Workspace created and follows the UUID v4
standard of RFC 4122 and in the payment modalities
it is presented with the field workspace_id.

status The status field returns to indicate if the Workspace is Yes

ACTIVE and INACTIVE.
type Workspace classification, can be PAYMENTS, Yes
DIGITAL_CORBAN and PHYSICAL_CORBAN.
mainDebitAccount The mainDebitAccount field is the main Workspace Yes
account with branch (branch number) and number
(account number).
description Workspace description. No
creationDate Workspace creation date. Yes
tags Workspace idetification Tag. Yes

2023 – 07 V1.1
49
Confidential

Accounts Payment Hub– API User Guide

addicionalDebitAccounts Additional accounts, follow the same rule of the No

mainDebitAccount field, in this field you have to
insert the branch (branch number) and number
(account number).
place Sub-established physical correspondent bank point No
information for type PHYSICAL_CORBAN.
webhookURL Field to include the DDA webhook URL. Yes
pixPaymentsActive Method of payment transfer PIX: DICT, QR Code and No
Agency and account.
bankSlipPaymentsActive Method of payment for bank slips Santander and No
other banks.
bankSlipAvailableActive Modality to enable the DDA, it is necessary that No
when enabling the DDA.
barCodePaymentsActive Mode of payment of concessionaires and taxes with No
barcodes.
taxesByFieldPaymentsActive Field-to-field tribute payment method: GPS, DARF, No
GARE ICMS, and GARE ITCMD.
vehicleTaxesPaymentsActive Renavam payment method: IPVA, DPVAT and No
Licensing.
bankSlipAvailableWebhookActive Modality to enable the DDA webhook. No

Response – Status 400 (Bad Request)

Field Description Mandatory
_errorCode Error code. Yes
_message Error message with a maximum of 30 characters. Yes
_details Error message detail with a maximum of 100 characters. Yes
_timestamp Date and time when the error occurs, following the RFC Yes
3339, ISO 8601 standard.

2023 – 07 V1.1
50
Confidential

Accounts Payment Hub– API User Guide

_traceId Trace id is the unique identifier among all calls where we Yes
trace all transactions.
_errors The _errors object has the additional information about No
the error:
▪ _code – Specific error code;
▪ _field – Error field identification;
▪ _message – error message description.

The other Status Codes follow the same pattern as the 400 Bad Request status.

3.2.3 Workspace list query by CNPJ (GET)

To perform a paginated query of Workspaces by CNPJ, you have to consume the endpoint of the
GET/workspaces method.

Parameters
Field Description Mandatory
_limit Maximum total that each page will bring in the query. No
_offset Records are shifted in the query. No
_sort Filter for paginated query, if nothing is sent, default No
'desc'.

This API has two main objects: the _pageable* that handles the pagination and the _content* that brings
the Workspace data.

Response – Status 200 (_pageable)

Field Description Mandatory
_limit It is the maximum total that each page will bring in the Yes
query, with a minimum of 1 (one) Workspace and a
maximum of 50 (fifty) Workspaces per page.

2023 – 07 V1.1
51
Confidential

Accounts Payment Hub– API User Guide

_offset Is the offset record of the query. Yes

_pageNumber Is the page number in the query. Yes
_pageElements Is the amount of record on the query page. Yes
_totalPages Is the total number of pages for this query. Yes
_totalElements It is the total number of records reported in this query. Yes

The _contet* field brings all the Workspace data mentioned above: workspace_id, creationDate*, status,
type*, description, mainDebitAccount*, addicionalDebitAccounts and payment methods:
bankSlipPaymentsActive, pixPaymentsActive, barCodePaymentsActive, taxesByFieldPaymentsActive,
vehicleTaxesPaymentsActive, webhookURL, bankSlipAvailableActive and bankS
lipAvailableWebhookActive. The Status Code: Bad Request follows the same error pattern presented
above and for the other status codes it also follows the same pattern.

Response – Status 400 Bad Request

Field Description Mandatory
_errorCode Error code. Yes
_message Error message with a maximum of 30 characters. Yes
_details Error message detail with a maximum of 100 characters. Yes
_timestamp Date and time when the error occurs, following the RFC Yes
3339, ISO 8601 standard.
_traceId Trace id is the unique identifier among all calls where we Yes
trace all transactions.
_errors The _errors object has the additional information about No
the error:
▪ _code – Specific error code;
▪ _field – Error field identification;
▪ _message – error message description.

2023 – 07 V1.1
52
Confidential

Accounts Payment Hub– API User Guide

3.2.4 Query by Workspace ID (GET)

To make a query by ID of a specific Workspace, it is necessary to consume the endpoint of the

GET/workspaces/{workspace_id} method and insert the workspace ID in the URL.

Parameters
Field Description Mandatory
workspace_id The Id field is unique to the client in the Workspace Yes
created and follows the UUID v4 standard of RFC
4122.

Response – Status 200 (Consulta Workspace por ID)

Field Description Mandatory
id The Id field is unique to the client in the Workspace Yes
created and follows the UUID v4 standard of RFC
4122.
status The status field returns to indicate whether the Yes
Workspace is ACTIVE or INACTIVE.
type Workspace classification, can be PAYMENTS, Yes
DIGITAL_CORBAN and PHYSICAL_CORBAN.
mainDebitAccount The mainDebitAccount field is the main Workspace Yes
account with branch (branch number) and number
(account number).
description Workspace description. No
creationDate Workspace creation date. Yes
tags Workspace identification tag. No
addicionalDebitAccounts Additional accounts, follow the same rule as in the No
mainDebitAccount field, in this field you must enter
the branch (branch number) and number (account
number).

2023 – 07 V1.1
53
Confidential

Accounts Payment Hub– API User Guide

place Physical corresponding bank point information No

subset for type PHYSICAL_CORBAN.
webhookURL Field to include the DDA webhook URL. No
pixPaymentsActive Method of payment transfer PIX: DICT, QR Code and No
Agency and account.
bankSlipPaymentsActive Method of payment for bank slips Santander and No
other banks.
bankSlipAvailableActive Modality to enable the DDA, it is necessary that No
when enabling the DDA.
barCodePaymentsActive Mode of payment of concessionaires and taxes with No
barcodes.
taxesByFieldPaymentsActive Field-to-field tribute payment method: GPS, DARF, No
GARE ICMS, and GARE ITCMD.
vehicleTaxesPaymentsActive Renavam payment method: IPVA, DPVAT and No
Licensing.
bankSlipAvailableWebhookActive Modality to enable the DDA webhook. No

The other Status Codes follow the same pattern as the 400 Bad Request status.

3.2.5 Workspace Maintenance (PATCH)

To maintain/update an already registered Workspace, it is necessary to consume the endpoint of the

method PATCH/workspaces/{workspace_id}.

Parameters
Field Description Mandatory
workspace_id The Id field is unique to the client in the Workspace Yes
created and follows the UUID v4 standard of RFC
4122.

2023 – 07 V1.1
54
Confidential

Accounts Payment Hub– API User Guide

Request
Field Description Mandatory
mainDebitAccount The field mainDebitAccount is the Workspace main Yes
account, in this field you must insert the branch, the
branch number that can have up to 4 digits and you
must insert the number, the account number that
must contain a maximum of 12 digits and if the
account has only one digit, add the leading zeros.
description Workspace Description and can be up to 30 No
characters long
tags The tag field is the Workspace identification and No
must have a maximum of 20 characters and the
number of tags must not exceed 5.
addicionalDebitAccounts If the customer has additional accounts, they are No
inserted in this field and follow the same rule as in
the mainDebitAccount field, in this field you have to
insert the branch, the branch number that can have
up to 4 digits and you have to insert the number, the
account number that must contain up to a maximum
of 12 digits and if the account has only one digit, add
zeros to the left.
place Registration of the sub-established physical bank No
correspondent point for the type
PHYSICAL_CORBAN. In this field, fill in the cnpj,
corporation name (corporateName), fantasy name
(fantasyName), email, telephone number (phone)
and address information (address) such as: zip code
(zipCode), state (state), city ( city), neighborhood
(district), street (street), address number (number)
and complement (complement).

2023 – 07 V1.1
55
Confidential

Accounts Payment Hub– API User Guide

webhookURL Field para incluir a URL do webhook DDA. No

pixPaymentsActive Method of payment transfer PIX: DICT, QR Code and No
Agency and account.
bankSlipPaymentsActive Method of payment for bank slips Santander and No
other banks.
bankSlipAvailableActive Modality to enable the DDA, it is necessary that No
when enabling the DDA.
barCodePaymentsActive Mode of payment of concessionaires and taxes with No
barcodes.
taxesByFieldPaymentsActive Field-to-field tribute payment method: GPS, DARF, No
GARE ICMS, and GARE ITCMD.
vehicleTaxesPaymentsActive Renavam payment method: IPVA, DPVAT and No
Licensing.
bankSlipAvailableWebhookActive Modality to enable the DDA webhook. No

To maintain additional accounts, it is necessary to send the body of the request with the accounts, even if
you only want to change one account.

Example:

▪ We have the following additional accounts registered in the workspace:

{
"type": "PAYMENTS",
"description": "user-guide-v1.1",
"mainDebitAccount": {
"branch": "0001",
"number": "000000000001"
},
"additionalDebitAccounts": [
{
"branch": “0001”,
"number": “00000000000A”

2023 – 07 V1.1
56
Confidential

Accounts Payment Hub– API User Guide

}
{
"branch": “0001”,
"number": “00000000000B”
}
{
"branch": “0001”,
"number": “00000000000C”
}
],
"bankSlipPaymentsActive": true
}

▪ And want to remove the account "branch": "0001",

"number": "00000000000B"

▪ It is necessary to send in the body of the requisition the accounts that you want to keep in the
Workspace:

{
"type": "PAYMENTS",
"description": "user-guide-v1.1",
"mainDebitAccount": {
"branch": "0001",
"number": "000000000001"
},
"additionalDebitAccounts": [
{
"branch": “000 ”,
"number": “00000000000A”
}
{
"branch": “000 ”,
"number": “00000000000C”
}
],
"bankSlipPaymentsActive": true
}

▪ Then the account "branch": "0001", the list of additional accounts is removed.
"number": "00000000000B"

2023 – 07 V1.1
57
Confidential

Accounts Payment Hub– API User Guide

To maintain the main account, just send the body of the request to the agency and tell us what you want.

It is worth mentioning that it is allowed to change other fields in the workspace, such as: tags, description
and product flags.

To update the main account with one of the accounts that are in the additional accounts, follow the same
procedure as above and the additional account will be removed from the additional accounts.

The request response follows the same pattern as those presented above, for the other error Status Codes
they follow the same pattern as the 400 Bad Request status.

3.2.6 Exclusion of a Workspace (DELETE)

To delete a Workspace, it is necessary to consume the endpoint of the

DELETE/workspaces/{workspace_id} method. Just send the workspace_id* and the response will return
Status Code 204 Resource Deleted. And if it happens to try to delete a Workspace_id that does not exist
or that has already been removed, the request response follows the same pattern as those presented
above, for the other Error Status Codes they follow the same pattern as the 400 Bad Request status.

Parameters
Field Description Mandatory
workspace_id The Id field is unique to the client in the Workspace Yes
created and follows the UUID v4 standard of RFC
4122.

2023 – 07 V1.1
58
Confidential

Accounts Payment Hub– API User Guide

TRANSACTION VISION

2023 – 07 V1.1
59
Confidential

Accounts Payment Hub– API User Guide

4. 4. Transaction Vision

After registering with Workspace, the customer is able to call the transactions available in the Payments
Hub. The transaction flow is basically given by three endpoints: POST, PATCH and GET, that is, three
transactions are performed safely and quickly. POST is the initiation of payment, where authentication
and initiation of payment takes place with data validation in the CIP as an example of billing titles or in
the SPI when it is a Pix transfer. The PATCH is the confirmation of payment and updating of data in the
competent clearinghouses of each product and the GET is the query of the payment status and can be
carried out both in the POST and in the PATCH.

Status query
Payment confirmation
Payment start/validation
Authentication

2023 – 07 V1.1
60
Confidential

Accounts Payment Hub– API User Guide

Client
payment
payment data
Authentication
Data recovery
Clearing house
Validation of information at CIP, SPI, internally, SEFAZ, etc
Data updating at CIP, SPI, internally, SEFAZ, etc

4.1 Payment status

In the payments API we have 6 (six) payment statuses:

Payment starts at POST and has the possibility of three statuses: PENDING_VALIDATION, READY_TO_PAY
e REJECTED.

On successful POST: PENDING_VALIDATION e READY_TO_PAY

▪ PENDING_VALIDATION is the data validation pending status in the clearinghouses.

▪ READY_TO_PAY is the status of ready for payment and the guarantee that the customer can
proceed to the next step: the PATCH.

In case of POST failure: REJECTED

▪ REJECTED is the payment rejection status.

2023 – 07 V1.1
61
Confidential

Accounts Payment Hub– API User Guide

To go to the PATCH, it is necessary that the payment status in the POST is READY_TO_PAY.

The customer in the PATCH sends us the authorization that we can proceed with the payment, and there
is the possibility of three statuses in the PATCH, remembering that AUTHORIZED is sent in the input fields
of the API:

▪ AUTHORIZED is the status that the customer sends authorizing the continuation of the payment.

In case of success of the PATCH: PENDING_CONFIRMATION and PAYED

▪ PENDING_CONFIRMATION is the payment confirmation pending status, this status can happen if
any clearing house goes down at the exact moment the APIs are called, if the receiving bank is
evaluating the transaction, if the customer runs out of account balance, etc. other cases.
▪ PAYED is the status of successful payment.

In case of PATCH failure: REJECTED

▪ REJECTED is the payment rejection status.

2023 – 07 V1.1
62
Confidential

Accounts Payment Hub– API User Guide

4.2 Payment methods

We have in the Payments Hub some payment methods available, such as: Santander Payment Slips, Other
Banks Payment Slips, Collection with Barra, Pix Transfer, Field to Field Tribute (GARE ICMS, GARE ITCMD,
DARF and GARE), Renavam Payment and Consultation (DPVAT , IPVA and Licensing).

4.2.1 Santander Payment Slips and Other Bank Payment Slips

With the Payments API you choose which services you want to hire, from debit accounts, payment of bank
slips issued by Santander, or other banks. Your company will also be able to validate the barcode or
typeable line of the slips, checking data, such as amounts or beneficiaries.

It is indicated for companies that need to make their payments to suppliers in an automated, fast and
secure way, directly from their management system and for those companies that want to work as a
Santander bank correspondent.

2023 – 07 V1.1
63
Confidential

Accounts Payment Hub– API User Guide

4.2.1.1 POST (Start paying a bond)

To initiate a payment with Payment Slips Santander or Payment Slips Outro Bancos, it is necessary to call
the endpoint POST (https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/{workspace_id}/bank_sli
p_payments), with the following input and output fields:

Parameters
Field Description Mandatory
workspace_id The Id field is unique to the client in the Workspace created and Yes
follows the UUID v4 standard of RFC 4122.

Request
Field Description Mandatory
id Payment identification id, follows the UUID v4 standard of RFC No
4122.
code Barcode or digitable line of bank slip Santander or other bank Yes
slips.
tags The tag field is the payment identification and must have a No
maximum of 20 characters and the number of tags must not
exceed 5.
paymentDate Payday. No

The payment id field is not mandatory, so if the customer does not send this field, we generate an id for the
customer.

2023 – 07 V1.1
64
Confidential

Accounts Payment Hub– API User Guide

Barcode has a limit of 44 positions and typeable line has a limit of 47 positions.

Santander Boletos start with 033.

If several consultations are requested and have READY_TO_PAY status, the last request overwrites the
others, that is, the other open consultations with different ids are rejected.

Response – Status 201

Field Description
id Payment identification id.
workspaceId Customer's unique ID in the Workspace created.
code Barcode or digitable line of the Santander slip or other bank slip.
debitAccount Branch number and account for direct debit.
status Payment status.
rejectReason Reason for rejecting the payment.
dueDate Payment Due Date.
accountingDate Accounting date of payment.
nominalValue Nominal/declared value of the payment.
deductedValue Amount deducted from payment, for example: rebates and discounts.
addedValue Additional payment amount, for example: interest and fines.
totalValue Total payment amount.
payer Payer data: name, name of the payer registered in the bill of exchange;
documentType, type of payer registered in the payment slip (CPF – individual, CNPJ

2023 – 07 V1.1
65
Confidential

Accounts Payment Hub– API User Guide

– legal entity); and documentNumber, the payer's document number registered in

the bill of exchange.
beneficiary Beneficiary data: name, name of the beneficiary; documentType, type of
beneficiary (CPF – individual, CNPJ – legal entity); and documentNumber, number
of the beneficiary's document.
finalPayer Final payer data: name, name of the final payer; documentType, type of final payer
(CPF – individual, CNPJ – legal entity); and documentNumber, document number
of the final payer.
partialPayment Partial payment details: min, minimum partial payment; max, maximum amount
accepted for payment; payed, partial amount paid so far.
transaction Transaction data: value, transaction value; code, transaction bank authentication
code; date, date on which the transaction takes place following the RFC 3339
standard; ISO 8601.
tags The tag field is the identification of the payment.
paymentValue Payment amount.

Final payer information is required for all workspace types and for Bank Slip Payments and Barcode
Payments. The final payer must be filled in the PATCH request.

Transaction.value and transaction.code data return null on POST and will only return filled in on PATCH if
the transaction is successfully completed.

When something unexpected happens in POST, we have error statuses:

▪ 400 - Customer information error

▪ 401 - Not Authorized/Authenticated
▪ 403 - Not Authorized

2023 – 07 V1.1
66
Confidential

Accounts Payment Hub– API User Guide

▪ 404 - Information not found

▪ 406 - The target resource does not have a current representation that would be acceptable
▪ 422 - Entity does not process/inadequate
▪ 429 - User sent too many requests in a given period
▪ 500 - Server Error, Application is out
▪ 501 - The server does not support the functionality required to fulfill the request

Response – Status 400

Field Description Mandatory
_errorCode Error code. Yes
_message Error message with a maximum of 30 characters. Yes
_details Error message detail with a maximum of 100 characters. Yes
_timestamp Date and time when the error occurs, following the RFC Yes
3339, ISO 8601 standard.
_traceId Trace id is the unique identifier among all calls where we Yes
trace all transactions.
_errors The _errors object has additional information about the No
error:
▪ _code – Specific error code;
▪ _field – Identification of the field with error;
▪ _message – error message description.
The other Status Codes follow the same pattern as the 400 Bad Request status.

4.2.1.2 PATCH (Performs the payment of an account)

To perform a payment with Santander Payment Slip or Other Banks Payment Slips, it is necessary to call
the endpoint PATCH (https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/{workspace_id}/bank_sli
p_payments/{bank_slip_payment_id}), with the following input and output fields:

Parameters

2023 – 07 V1.1
67
Confidential

Accounts Payment Hub– API User Guide

Field Description Mandatory

workspace_id The Id field is unique to the client in the Workspace created Yes
and follows the UUID v4 standard of RFC 4122.
bank_slip_payment_id Payment identification id, follows the UUID v4 standard of Yes
RFC 4122.

Request
Campo Descrição Obrigatório
paymentValue Payment amount. Sim
debitAccount Branch number and account for direct debit Não
finalPayer Final payer data: name, name of the final payer; Sim
documentType, type of final payer (CPF - Individual, CNPJ -
Legal Entity); and documentNumber, document number of
the final payer.
status Payment status AUTHORIZED to release the payment. Sim

A on a d dé i o “d i A o n ” s n o infor ada na r q s do PAT H, é n ndido q o i n quer

que debitemos da conta principal cadastrada na workspace o valor informado.

Response – Status 200

Campo Descrição
id Payment identification id
workspaceId Client’s uni ue id in the Workspace created.
code Código de barras ou linha digitável do boleto Santander ou boleto outros bancos.
debitAccount Branch number and account for direct debit
status Payment status.
rejectReason Reason for rejecting the payment.
dueDate Data de vencimento do pagamento.

2023 – 07 V1.1
68
Confidential

Accounts Payment Hub– API User Guide

accountingDate Accounting date of payment.

nominalValue Nominal/declared value of the payment.
deductedValue Value deducted from payment, for example: deductions and discounts.
addedValue Additional payment value, for example: interest and fines.
totalValue Total value of payment.
payer Payer data: name, nome do pagador registrado no boleto; documentType, tipo de
pagador registrado no boleto (CPF – pessoa física, CNPJ – pessoa jurídica); and the
documentNumber, número do documento do pagador registrado no boleto.
beneficiary Beneficiary data: name, beneficiary name; documentType, type of beneficiary
(CPF- Individual, CNPJ- Legal Entity); e documentNumber, número do documento
do beneficiário.
finalPayer Final payer data: name, name of the final payer; documentType, type of final payer
(CPF - Individual, CNPJ - Legal Entity); and documentNumber, document number
of the final payer.
partialPayment Partial payment details: min,minimum partial payment; max, maximum amount
accepted for payment; payed, partial amount paid so far.
transaction Transaction data: value, transaction value; code, transaction bank authentication
code; date, date on which the transaction takes place following RFC 3339 standard;
ISO 8601.
tags The tag field is the identification of the payment.
paymentValue Payment amount.

When something unexpected happens in the PATCH, we have the error statuses:

▪ 400 - Client information error

▪ 401 - Unauthorized/Authenticated
▪ 403 - Unauthorized
▪ 404 - Information not found
▪ 406 - The target resource does not have a current representation that would be acceptable
▪ 410 - The destination resource is no longer available on the source server

2023 – 07 V1.1
69
Confidential

Accounts Payment Hub– API User Guide

▪ 422 - Entity does not process/inappropriate

▪ 429 - The user sent too many requests in a given period
▪ 500 - Server Error, Application is out
▪ 501 - The server does not support the functionality required to fulfill the request

Response – Status 400

Field Description Mandatory
_errorCode Error code. Yes
_message Error message with a maximum of 30 characters. Yes
_details Detail of the error message with a maximum of 100 Yes
characters.
_timestamp Date and time the error occurred, following RFC 3339 Yes
standard, ISO 8601.
_traceId Trace id is the unique identifier among all calls where we Yes
trace all transactions.
_errors The _errors objct has the addition information about the No
error:
▪ _code – Specific error code;
▪ _field – Identification of the field with error;
▪ _message – error message description.

The other Status Code follows the same pattern as the 400 Bad Request status.

4.2.1.3 GET (Queries by ID the data/status of a payment)

To check the payment status in the POST or PATCH, it is necessary to call endpoint GET (https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/{workspace_id}/bank_sli
p_payments/{bank_slip_payment_id}).

In GET parameters, the Workspace id and payment id fields are mandatory:

2023 – 07 V1.1
70
Confidential

Accounts Payment Hub– API User Guide

Parameters
Field Description Mandatory
workspace_id Client’s uni ue id in the Workspace created and follows Yes
UUID v4 standard of RFC 4122.
bank_slip_payment_id Payment identification id, follows UUID v4 standard of Yes
RFC 4122.

The GET response is the same as POST and PATCH.

4.2.1.4 GET (Paginated query of the payment data/status)

To carry out a paginated query of payment statuses in a date range, it is necessary to call endpoint GET
(https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/{workspace_id}/bank_sli
p_payments). This query helps the client when carrying out reconciliations for the payment of Santander
and other bank slips.

Parameters (Filters)
Field Description Value Mandatory
workspace_id Unique client id of a registered - Yes
workspace.
_limit Maximum total that each page will - No
bring in the query.
_offset Records being shifted in the query. - No
_sort Filter for paginated query if nothing is - No
sent, ‘desc’ standard.
initialDate Start date of the query, YYYY-MM-DD YYYY-MM-DD No
(Year-Month-Day) standard.
finalDate Final date of the query, YYYY-MM-DD YYYY-MM-DD No
(Year-Month-Day).

2023 – 07 V1.1
71
Confidential

Accounts Payment Hub– API User Guide

status Transactional status filter that can be PENDING_VALIDATION No

called in the API. READY_TO_PAY
PENDING_CONFIRMATION
PAYED
REJECTED

Response – Status 200

Field Description Mandatory
_limit It is the maximum total number of records that each page Yes
will bring in the query, with a minimum of one (1) and a
maximum of one hundred (100) records per page.
_offset It is the offset record of the query. Yes
_pageNumber It is the page number of the query. Yes
_pageElements It is the number of records on the query page. Yes
_totalPages It is the total number of pages for this query. Yes
_totalElements It is the total number of records reported in this query. Yes

_content It brings all POST and PATCH response data. Yes

The Status Code: Bad Request follows the same error pattern presented above and for the other status
code it also follows the same pattern.

4.2.1.5 DDA (Authorized Direct Debit)

The DDA is a product that allows clients to electronically access their payment slips through electronic
payment channels, without the need for a physical payment slip or for typing a barcode for payment.

2023 – 07 V1.1
72
Confidential

Accounts Payment Hub– API User Guide

All payment slips issued in the name of the payer are available in the DDA, such as condominium fee, rent,
club, school, credit card invoice, among others. The payment slips are made available on the same day of
adhesion and all payment slips registered in the name of the Payer will be made available, regardless of
the issuing bank.

The contracting may be carried out by the Call Center, through Internet Banking and also in the Corporate
Santander application.

The DDA List API brings practicalities to search for your payment slips with numerous filters and in a
paginated way, managing your payment slips and still paying in the payment API itself. In addition, it
enables the webhook in the workspace and receives payment slip receipt notices, reducing the risk of
fraud and data tampering.

It is necessary that when enabling the DDA flag in the Workspace, the client makes sure that the
bankSlipPaymentsActive is also enabled.

To carry out a DDA payment slip query it is necessary to call endpoint GET (https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/{workspace_id}/available
_bank_slips).

Parameters (Filtros)
Field Description Value Mandatory
workspace_id Unique client id of a registered - Yes
workspace.
_limit Maximum total that each page will bring - No
in the query.
_offset Records being shifted in the query. - No
_sort Filter for paginated query if nothing is - No
sent, ‘desc’ standard.
initialDueDate Initial Due Date. YYYY-MM-DD No
finalDueDate Final Due Date. YYYY-MM-DD No

2023 – 07 V1.1
73
Confidential

Accounts Payment Hub– API User Guide

initialIssueDate Initial Payment Slip Issue Date. YYYY-MM-DD No

finalIssueDate Final Payment Slip Issued Date. YYYY-MM-DD No
titleSituation All title situation: No
ALL
ALL = All open;
OPEN_TO_EXPIRE
OPEN_TO_EXPIRE = Expiring;
OPEN_EXPIRED
OPEN_EXPIRED = Expired;
SCHEDULED
SCHEDULED = Scheduled;
PAID
PAID = Paid;
ISSUED
ISSUED = Written-off by the beneficiary.
titleOrigin In all origin situations, this filter has to be No
selected for originAggregates and
OWN
originAuthorized to work correctly.
AGGREGATE
OWN = Own;
AUTHORIZED
AGGREGATE = Aggregate;
ALL
AUTHORIZED = Authorized;
ALL = All.
originAggregates List of aggregates, insert CPF or CNPJ - No
number.
originAuthorized List of authorized persons, insert CPF or - No
CNPJ number.
beneficiaryDocument Document number of the original - No
beneficiary.
bankNumber Our Number, it has a maximum of 13 - No
digits.
initialValue Initial Value. Eg.: 100.0 No
finalValue Final Value. Eg.: 150.0 No

Response – Status 200

Field Description Mandatory

2023 – 07 V1.1
74
Confidential

Accounts Payment Hub– API User Guide

_limit It is the maximum total number of records that each page Yes
will bring in the query, with a minimum of one (1) and a
maximum of one hundred (100) records per page.
_offset It is the offset record of the query. Yes
_pageNumber It is the page number of the query. Yes
_pageElements It is the number of records on the query page. Yes
_totalPages It is the total number of pages for this query. Yes
_totalElements It is the total number of records reported in this query. Yes

_content It brings the payment slip details: Yes

dueDate: Due date;
code: Typeable line;
paymentLimitDate: Payment limit date;
payerDocumentNumber: Payer document number;
nominalValue: Nominal/declared value on the payment
slip;
beneficiary: Original beneficiary, this object brings the
name of the beneficiary, type and document number;
finalBeneficiary: Final beneficiary, this object brings the
beneficiary name, document type and number.

Response – Status 400

Field Description Mandatory
_errorCode Error code. Yes
_message Error message with a maximum of 30 characters. Yes
_details Detail of the error message with a maximum of 100 Yes
characters.
_timestamp Date and time the error occurred, following RFC 3339 Yes
standard, ISO 8601.

2023 – 07 V1.1
75
Confidential

Accounts Payment Hub– API User Guide

_traceId Trace id is the unique identifier among all calls where we Yes
trace all transactions.
_errors The _errors object has additional information about the No
error:
▪ _code – Specific error code;
▪ _field – Identification of the field with error;
▪ _message – error message description.

For the other status code, it also follows the same pattern as the 400 Bad Request status.

4.2.1.6 DDA Webhook

To enable DDA webhook it is necessary to create a workspace or change an existing one, set
bankSlipAvailableWebhookActive flag to true. Make sure you enter the URL you want to receive
notification of the payment slips issued for your CNPJ in the webhookURL flag in conjunction with enabling
the webhook flag.

The webhookURL flag in the workspace is for the client to receive notifications when a payment slip is issued
in his/her name. It is mandatory to start with https:// and have a maximum of 350 characters.

The client will receive a notification whenever a payment slip is issued in his/her name, the notification
will contain the following fields:

DDA Webhook Notification

Field Description Mandatory
dueDate Due date Yes
code Typeable line Yes
paymentLimitDate Payment limit date. Yes
payerDocumentNumber The payer’s document number. Yes

2023 – 07 V1.1
76
Confidential

Accounts Payment Hub– API User Guide

nominalValue Nominal/declared value in the payment slip. Yes

Beneficiary Original beneficiary, this object brings the name of the Yes
beneficiary, document type and number.
finalBeneficiary Final beneficiary, this object brings the name of the Yes
beneficiary, document type and number.

If the client has aggregates and authorized ones, he/she will also receive notification of the payment slips
issued for the aggregates and authorized ones.

2023 – 07 V1.1
77
Confidential

Accounts Payment Hub– API User Guide

4.2.2 Bar Code Collection

With the Payment API with Bar Code Collection, you may pay municipal, state or federal taxes and even
consumption bills (utilities). Learn about all the payments that can be made through our APIs by clicking
here.

A simple way for your business to pay federal, state or local taxes and utility bills enabled for bank
processing.

4.2.2.1 POST (Initiates payment from a barcode)

To initiate a barcode Collection payment, it is necessary to call endpoint POST (https://trust-

open.api.santander.com.br/management_payments_partners/v1/workspaces/{workspace_id}/barcode
_payments), having the following input and output fields:

Parameters
Field Description Mandatory
workspace_id Client’s uni ue id in the Workspace created and follows Yes
UUID v4 standard of RFC 4122.

Request
Field Description Mandatory
id Payment identification id and follows UUID v4 standard of No
RFC 4122.
code Barcode or typeable line of a collection with bar. Yes
tags The tag field is the payment identification and must have No
a maximum of 20 characters and the number of tags must
not exceed 5.
paymentDate Payment date. No

2023 – 07 V1.1
78
Confidential

Accounts Payment Hub– API User Guide

Barcode has a limit of 44 positions and typeable line has a limit of 48 positions.

Collection barcode starts with 8.

Response – Status 201

Field Description
id Payment identification id
workspaceId Client’s unique id in the Workspace created.
Code Barcode or typeable line of Barcode Collection.
debitAccount Branch number and account for direct debit
status Payment status.
rejectReason Reason for rejecting the payment.
paymentType Barcode payment type with UTILITY (consumer bills) or TAXES.
accountingDate Accounting date of payment.
finalPayer Final payer data: name, name of the final payer; documentType, type of final payer
(CPF - Individual, CNPJ - Legal Entity); and documentNumber, document number
of the final payer.
totalValue Total value of payment.
Concessionary Utility company details: code, collection agreement code; and name, collection
agreement name.
transaction Transaction data: value, transaction value; code, transaction bank authentication
code; date, date on which the transaction takes place following RFC 3339 standard;
ISO 8601.
tags The tag field is the identification of the payment.
paymentValue Payment amount.
When something unexpected happens in the POST, we have the error statuses:

▪ 400 - Client information error

2023 – 07 V1.1
79
Confidential

Accounts Payment Hub– API User Guide

▪ 401 - Unauthorized/Authenticated
▪ 403 - Unauthorized
▪ 404 - Information not found
▪ 406 - The target resource does not have a current representation that would be acceptable
▪ 422 - Entity does not process/inappropriate
▪ 429 - The user sent too many requests in a given period
▪ 500 - Server Error, Application is out
▪ 501 - The server does not support the functionality required to fulfill the request

Response – Status 400

Field Description Mandatory
_errorCode Error code. Yes
_message Error message with a maximum of 30 characters. Yes
_details Detail of the error message with a maximum of 100 Yes
characters.
_timestamp Date and time the error occurred, following RFC 3339 Yes
standard, ISO 8601.
_traceId Trace id is the unique identifier among all calls where we Yes
trace all transactions.
_errors The _errors object has additional information about the No
error:
▪ _code – Specific error code;
▪ _field – Identification of the field with error;
▪ _message – error message description.

The other Status Code follows the same pattern as the 400 Bad Request status.

2023 – 07 V1.1
80
Confidential

Accounts Payment Hub– API User Guide

4.2.2.2 PATCH (Makes payment of a barcode)

To make a barcode collection payment, it is necessary to call endpoint PATCH (https://trust-

open.api.santander.com.br/management_payments_partners/v1/workspaces/{workspace_id}/barcode
_payments/{barcode_payment_id}), with the following input and output fields:

Parameters
Field Description Mandatory
workspace_id Client’s uni ue id in the Workspace created and follows Yes
UUID v4 standard of RFC 4122.
barcode_payment_id Payment identification id, follows UUID v4 standard of Yes
RFC 4122.

Request
Field Description Mandatory
paymentValue Payment amount. Yes
debitAccount Branch number and account for direct debit No
finalPayer Final payer data: name, name of the final payer; Yes
documentType, type of final payer (CPF - Individual, CNPJ
- Legal Entity); and documentNumber, document number
of the final payer.
status Payment status AUTHORIZED to release the payment. Yes

Response – Status 200

Field Description
id Payment identification id
workspaceId Client’s uni ue id in the Workspace created.
code Collection barcode or typeable line with barcode.
debitAccount Branch number and account for direct debit
status Payment status.
rejectReason Reason for rejecting the payment.

2023 – 07 V1.1
81
Confidential

Accounts Payment Hub– API User Guide

paymentType Barcode payment type with UTILITY (consumer bills) or TAXES categories.
accountingDate Accounting date of payment.
totalValue Total value of payment.
concessionary Utility company details: code, collection agreement code; and name, collection
agreement name.
transaction Transaction data: value, transaction value; code, transaction bank authentication
code; date, date on which the transaction takes place following RFC 3339 standard;
ISO 8601.
tags The tag field is the identification of the payment.
paymentValue Payment amount.

When something unexpected happens in the PATCH, we have the error statuses:

▪ 400 - Client information error

▪ 401 - Unauthorized/Authenticated
▪ 403 - Unauthorized
▪ 404 - Information not found
▪ 406 - The target resource does not have a current representation that would be acceptable
▪ 410 - The destination resource is no longer available on the source server
▪ 422 - Entity does not process/inappropriate
▪ 429 - The user sent too many requests in a given period
▪ 500 - Server Error, Application is out
▪ 501 - The server does not support the functionality required to fulfill the request

Response – Status 400

Field Description Mandatory
_errorCode Error code. Yes
_message Error message with a maximum of 30 characters. Yes

2023 – 07 V1.1
82
Confidential

Accounts Payment Hub– API User Guide

_details Detail of the error message with a maximum of 100 Yes

characters.
_timestamp Date and time the error occurred, following RFC 3339 Yes
standard, ISO 8601.
_traceId Trace id is the unique identifier among all calls where we Yes
trace all transactions.
_errors The _errors object has additional information about the No
error:
▪ _code – Specific error code;
▪ _field – Identification of the field with error;
▪ _message – error message description.

The other Status Code follows the same pattern as the 400 Bad Request status.

2023 – 07 V1.1
83
Confidential

Accounts Payment Hub– API User Guide

4.2.2.3 GET (Query by ID the payment data/status of a barcode)

To check the payment status in the POST or PATCH, it is necessary to call endpoint GET (https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/{workspace_id}/barcode
_payments/{barcode_payment_id}).

In GET parameters, the Workspace id and payment id fields are mandatory:

Parameters
Field Description Mandatory
workspace_id Client’s uni ue id in the Workspace created and follows Yes
UUID v4 standard of RFC 4122.
barcode_payment_id Payment identification id, follows UUID v4 standard of Yes
RFC 4122.

The GET response is the same as POST and PATCH.

4.2.2.4 GET (Consulta paginada dos dados/status de pagamento)

To carry out a paginated query of payment statuses in a date range, it is necessary to call endpoint GET
(https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/{workspace_id}/barcode
_payments). This query helps the client when carrying out his/her reconciliations for the payment of
collection with bar.

Parameters (Filtros)
Field Description Value Mandatory
workspace_id Unique client id of a registered - Yes
workspace.
_limit Maximum total that each page will - No
bring in the query.
_offset Records being shifted in the query. - No

2023 – 07 V1.1
84
Confidential

Accounts Payment Hub– API User Guide

_sort Filter for paginated query if nothing is - No

sent, ‘desc’ standard.
initialDate Start date of the query, YYYY-MM-DD YYYY-MM-DD No
(Year-Month-Day) standard.
finalDate Final date of the query, YYYY-MM-DD YYYY-MM-DD No
(Year-Month-Day).
status Transactional status filter that can be PENDING_VALIDATION No
called in the API. READY_TO_PAY
PENDING_CONFIRMATION
PAYED
REJECTED

Response – Status 200

Field Description Mandatory
_limit It is the maximum total number of records that each page Yes
will bring in the query, with a minimum of one (1) and a
maximum of one hundred (100) records per page.
_offset It is the offset record of the query. Yes
_pageNumber It is the page number of the query. Yes
_pageElements It is the number of records on the query page. Yes
_totalPages It is the total number of pages for this query. Yes
_totalElements It is the total number of records reported in this query. Yes

_content It brings all POST and PATCH response data. Yes

The Status Code: Bad Request follows the same error pattern presented above and for the other status
code it also follows the same pattern.

2023 – 07 V1.1
85
Confidential

Accounts Payment Hub– API User Guide

4.2.3 Pix Transfer

Pix is a new means of payment created by the Central Bank of Brazil. The idea is to facilitate the transfer
of values between people, as it becomes possible to pay for purchases, transfer and receive money
instantly. For example, wire transfer (TED and DOC) can take hours and even days to be completed, for
the money to be credited in the destination account. With Pix, financial transactions are immediate and
contain the same authentication and encryption security measures used in other means of payment.
Everything is digital and encrypted, which gives you more security so you can carry out banking
transactions without worry.

In addition, the transactions are traceable, which facilitates the work of authorities in case something
suspicious is identified. It works 24 hours a day, 7 days a week!

You can make transfers by DICT key (CNPJ/CPF, cell phone, email and random key), branch and account
and QR Code.

Pix transfer is accepted for own payments, that is, only for the workspace PAYMENTS type.

4.2.3.1 POST (Initiates the payment of a Pix)

To initiate a pix transfer payment, it is necessary to call endpoint POST (https://trust-

open.api.santander.com.br/management_payments_partners/v1/workspaces/{workspace_id}/pix_pay
ments). In this endpoint, it is possible to initiate a transfer through DICT key, QR Code and branch and
account (beneficiary), below are the input and output fields of the API for the different means of transfer:

4.2.3.1.1 DICT key

Parameters
Field Description Mandatory

2023 – 07 V1.1
86
Confidential

Accounts Payment Hub– API User Guide

workspace_id Client’s uni ue id in the Workspace created and follows Yes

UUID v4 standard of RFC 4122.

Request
Field Description Mandatory
id Payment identification id and follows UUID v4 standard of No
RFC 4122.
tags The tag field is the payment identification and must have No
a maximum of 20 characters and the number of tags must
not exceed 5.
remittanceInformation Information field must be filled in whenever the paying No
user enters some additional information in a payment, to
be sent to the recipient. The maximum field length is 138
characters.
dictCodeType Type of Pix key, which may be: CPF, CNPJ, MOBILE PHONE, Yes
EMAIL or EVP (random key).
dictCode Pix key Yes
paymentValue Payment value. Yes

Response – Status 201

Field Description
id Payment identification id
workspaceId Client’s uni ue id in the Workspace created.
debitAccount Branch number and account for direct debit
status Payment status.
dictCodeType Type of Pix key, which may be: CPF, CNPJ, MOBILE PHONE, EMAIL or EVP.
dictCode Pix key.
remittanceInformation Additional information field of a pix transfer.
nominalValue Nominal/declared value of the payment.

2023 – 07 V1.1
87
Confidential

Accounts Payment Hub– API User Guide

totalValue Total value of payment.

payer Payer data: name, name of the payer registered in the workspace;
documentType, type of payer registered in the workspace (CPF - Individual,
CNPJ - Legal Entity); and the documentNumber, the payer’s document
number.
beneficiary Beneficiary data: name, beneficiary name; documentType, type of beneficiary
(CPF- Individual, CNPJ- Legal Entity); documentNumber, number of
beneficiary’s document; bankCode, bank code; ispb, SPI participant’s Bra ilian
Payments System Identifier code; branch, branch number; number, account
number; and type, beneficiary’s account type.
transaction Transaction data: value, transaction value; code, transaction bank
authentication code; date, date on which the transaction takes place following
RFC 3339 standard/ISO 8601; and endToEnd, E2E identifier of the payment,
starting with the letter E (upper case), have 32 characters.
tags The tag field is the identification of the payment.
paymentValue Payment amount.

The type in the beneficiary object may return the following types: CONTA_CORRENTE, CONTA_POUPANCA,
CONTA_PAGAMENTO [CURRENT_ACCOUNT, SAVINGS_ACCOUNT, PAYMENT_ACCOUNT].

4.2.3.1.2 Beneficiary - Branch and Account

Parameters
Field Description Mandatory
workspace_id Client’s uni ue id in the Workspace created and follows Yes
UUID v4 standard of RFC 4122.

2023 – 07 V1.1
88
Confidential

Accounts Payment Hub– API User Guide

Request
Field Description Mandatory
Id Payment identification id and follows UUID v4 standard of No
RFC 4122.
tags The tag field is the payment identification and must have No
a maximum of 20 characters and the number of tags must
not exceed 5.
remittanceInformation Information field must be filled in whenever the paying No
user enters some additional information in a payment, to
be sent to the recipient. The maximum field length is 138
characters.
Beneficiary Beneficiary data: name, beneficiary name; Yes
documentType, type of beneficiary (CPF- Individual,
CNPJ- Legal Entity); documentNumber, number of
beneficiary’s document; bankCode, bank code; ispb, SPI
participant’s Bra ilian Payments System Identifier code;
branch, branch number; number, account number; and
type, beneficiary’s account type.
paymentValue Payment value Yes

It is allowed in the branch and account pix transfer API to insert alphanumeric digits into the paying user’s
account.

The client may indicate the bankCode or ISPB, never both.

2023 – 07 V1.1
89
Confidential

Accounts Payment Hub– API User Guide

Response – Status 201

Field Description
id Payment identification id
workspaceId Client’s uni ue id in the Workspace created.
debitAccount Branch number and account for direct debit
status Payment status.
remittanceInformation Additional information field of a pix transfer
nominalValue Nominal/declared value of the payment.
totalValue Total value of payment.
Payer Payer data: name, name of the payer registered in the workspace;
documentType, type of payer registered in the workspace (CPF - Individual,
CNPJ - Legal Entity); and the documentNumber, the payer’s document
number.
beneficiary Beneficiary data: name, beneficiary name; documentType, type of beneficiary
(CPF- Individual, CNPJ- Legal Entity); documentNumber, number of
beneficiary’s document; bankCode, bank code; ispb, SPI participant’s Bra ilian
Payments System Identifier code; branch, branch number; number, account
number; and type, beneficiary’s account type.
transaction Transaction data: value, transaction value; code, transaction bank
authentication code; date, date on which the transaction takes place following
RFC 3339 standard/ISO 8601; and endToEnd, E2E identifier of the payment,
starting with the letter E (upper case), have 32 characters.
tags The tag field is the identification of the payment.
paymentValue Payment amount.

4.2.3.1.3 QR Code

Parameters
Field Description Mandatory

2023 – 07 V1.1
90
Confidential

Accounts Payment Hub– API User Guide

workspace_id Client’s uni ue id in the Workspace created and follows Yes

UUID v4 standard of RFC 4122.

Request
Field Description Mandatory
id Payment identification id No
tags The tag field is the payment identification and must have No
a maximum of 20 characters and the number of tags must
not exceed 5.
remittanceInformation Information field must be filled in whenever the paying No
user enters some additional information in a payment, to
be sent to the recipient. The maximum field length is 138
characters.
qrCode Sequence of characters that corresponds to the QR Code Yes
made available to the payer. It is the sequence of
characters that would be read by the QR Code reader, and
should provide the return of the payer's data after
consulting the DICT. This functionality is possible for both
static QR Code and dynamic QR Code. In the Pix
arrangement, this is the same sequence generated and/or
read by the Pix Copy and Paste functionality. This field
must be in UTF-8 format.
paymentValue Payment value. Yes
ibgeTownCode Code based on IBGE Table of Municipalities Codes, which No
presents the list of Brazilian municipalities associated with
a 7-digit composite code, the first two of which refer to
the Federation Unit code. (Retrieved from the
municipality service (QRCODE)).
paymentDate Payment date. No

2023 – 07 V1.1
91
Confidential

Accounts Payment Hub– API User Guide

Response – Status 201

Field Description
id Payment identification id
workspaceId Client’s uni ue id in the Workspace created.
debitAccount Branch number and account for direct debit
status Payment status.
qrCode QR Code data.
ibgeTownCode IBGE Municipality Codes.
qrCodeIdentification Txld identification code.
remittanceInformation Additional information field in a payment, to be sent to the recipient.
dueDate Due date.
nominalValue Nominal/declared value of the payment.
deductedValue Value deducted from payment, for example: deductions and discounts.
addedValue Additional payment value, for example: interest and fines.
totalValue Total value of payment.
payer Payer data: name, name of the payer registered in the workspace;
documentType, type of payer registered in the workspace (CPF - Individual,
CNPJ - Legal Entity); and the documentNumber, the payer’s document
number.
beneficiary Beneficiary data: name, beneficiary name; documentType, type of beneficiary
(CPF- Individual, CNPJ- Legal Entity); documentNumber, number of
beneficiary’s document; bankCode, bank code; ispb, SPI participant’s Bra ilian
Payments System Identifier code; and type, beneficiary’s account type.
transaction Transaction data: value, transaction value; code, transaction bank
authentication code; date, date on which the transaction takes place following
RFC 3339 standard/ISO 8601; and endToEnd, E2E identifier of the payment,
starting with the letter E (upper case), have 32 characters.
tags The tag field is the identification of the payment.

2023 – 07 V1.1
92
Confidential

Accounts Payment Hub– API User Guide

paymentValue Payment amount.

Interest, Fine, Discount and Reduction are applicable to the dynamic and expiring QR Code only.

Static QRCode has no expiration date.

When something unexpected happens in the POST, we have the error statuses:

▪ 400 - Client information error

▪ 401 - Unauthorized/Authenticated
▪ 403 - Unauthorized
▪ 404 - Information not found
▪ 406 - The target resource does not have a current representation that would be acceptable
▪ 415 - Format not supported by this method on target resource.
▪ 422 - Entity does not process/inappropriate
▪ 500 - Server Error, Application is out

Response – Status 400

Field Description Mandatory

2023 – 07 V1.1
93
Confidential

Accounts Payment Hub– API User Guide

_errorCode Error code. Yes

_message Error message with a maximum of 30 characters. Yes
_details Detail of the error message with a maximum of 100 Yes
characters.
_timestamp Date and time the error occurred, following RFC 3339 Yes
standard, ISO 8601.
_traceId Trace id is the unique identifier among all calls where we Yes
trace all transactions.
_errors The _errors object has additional information about the No
error:
▪ _code – Specific error code;
▪ _field – Identification of the field with error;
▪ _message – error message description.

The other Status Code follows the same pattern as the 400 Bad Request status.

4.2.3.2 PATCH (Makes payment of a Pix)

To make payment of a pix transfer, it is necessary to call endpoint PATCH (https://trust-

open.api.santander.com.br/management_payments_partners/v1/workspaces/{workspace_id}/pix_pay
ments/{pix_payment_id}). In this endpoint, it is possible to make a transfer through DICT key, QR Code
and Branch and Account (beneficiary), below are the input and output fields of the API for the different
means of transfer:

4.2.3.2.1 Chave DICT

Parameters
Field Description Mandatory

2023 – 07 V1.1
94
Confidential

Accounts Payment Hub– API User Guide

workspace_id Client’s uni ue id in the Workspace created and follows Yes

UUID v4 standard of RFC 4122.
pix_payment_id Payment identification id, follows UUID v4 standard of Yes
RFC 4122.

Request
Field Description Mandatory
paymentValue Payment value. Yes
status Payment status AUTHORIZED to release the payment. Yes
debitAccount Branch number and account for direct debit No

Response – Status 200

Field Description
id Payment identification id
workspaceId Client’s uni ue id in the Workspace created.
debitAccount Branch number and account for direct debit
status Payment status.
rejectReason Reason for rejecting the payment.
dictCodeType Type of Pix key, which it may be: CPF, CNPJ, MOBILE PHONE, EMAIL or EVP.
dictCode Pix key.
remittanceInformation Additional information field of a pix transfer.
nominalValue Nominal/declared value of the payment.
totalValue Total value of payment.
payer Payer data: name, name of the payer registered in the workspace;
documentType, type of payer registered in the workspace (CPF - Individual,
CNPJ - Legal Entity); and the documentNumber, the payer’s document
number.
beneficiary Beneficiary data: name, beneficiary name; documentType, type of beneficiary
(CPF- Individual, CNPJ- Legal Entity); documentNumber, number of

2023 – 07 V1.1
95
Confidential

Accounts Payment Hub– API User Guide

beneficiary’s document; bankCode, bank code; ispb, SPI participant’s Bra ilian
Payments System Identifier code; branch, branch number; number, account
number; and type, beneficiary’s account type.
transaction Transaction data: value, transaction value; code, transaction bank
authentication code; date, date on which the transaction takes place following
RFC 3339 standard/ISO 8601; and endToEnd, E2E identifier of the payment,
starting with the letter E (upper case), have 32 characters.
tags The tag field is the identification of the payment.
paymentValue Payment amount.

4.2.3.2.2 Beneficiary – Branch and Account

Parameters
Field Description Mandatory
workspace_id Client’s uni ue id in the Workspace created and follows Yes
UUID v4 standard of RFC 4122.
pix_payment_id Payment identification id, follows UUID v4 standard of Yes
RFC 4122.

Request
Field Description Mandatory
paymentValue Payment value. Yes
status Payment status AUTHORIZED to release the payment. Yes
debitAccount Branch number and account for direct debit No

2023 – 07 V1.1
96
Confidential

Accounts Payment Hub– API User Guide

Response – Status 200

Field Description
id Payment identification id
workspaceId Client’s uni ue id in the Workspace created.
debitAccount Branch number and account for direct debit
status Payment status.
rejectReason Reason for rejecting the payment.
remittanceInformation Additional information field of a pix transfer.
nominalValue Nominal/declared value of the payment.
totalValue Total value of payment.
payer Payer data: name, name of the payer registered in the workspace;
documentType, type of payer registered in the workspace (CPF - Individual,
CNPJ - Legal Entity); and the documentNumber, the payer’s document
number.
beneficiary Beneficiary data: name, beneficiary name; documentType, type of beneficiary
(CPF- Individual, CNPJ- Legal Entity); documentNumber, number of
beneficiary’s document; bankCode, bank code; ispb, SPI participant’s Bra ilian
Payments System Identifier code; branch, branch number; number, account
number; and type, beneficiary’s account type.
transaction Transaction data: value, transaction value; code, transaction bank
authentication code; date, date on which the transaction takes place following
RFC 3339 standard/ISO 8601; and endToEnd, E2E identifier of the payment,
starting with the letter E (upper case), have 32 characters.
tags The tag field is the identification of the payment.
paymentValue Payment amount.

4.2.3.2.3 QR Code

Parameters
Field Description Mandatory

2023 – 07 V1.1
97
Confidential

Accounts Payment Hub– API User Guide

workspace_id Client’s uni ue id in the Workspace created and follows Yes

UUID v4 standard of RFC 4122.
pix_payment_id Payment identification id, follows UUID v4 standard of Yes
RFC 4122.

Request
Field Description Mandatory
paymentValue Payment value. Yes
status Payment status AUTHORIZED to release the payment. Yes
debitAccount Branch number and account for direct debit No

Response – Status 200

Field Description
id Payment identification id
workspaceId Client’s uni ue id in the Workspace created.
debitAccount Branch number and account for direct debit
status Payment status.
rejectReason Reason for rejecting the payment.
qrCode QR Code data.
ibgeTownCode IBGE Municipality Codes.
qrCodeIdentification Txld identification code.
remittanceInformation Additional information field in a payment, to be sent to the recipient.
dueDate Due date.
nominalValue Nominal/declared value of the payment.
deductedValue Value deducted from payment, for example: deductions and discounts.
addedValue Additional payment value, for example: interest and fines.
totalValue Total value of payment.
payer Payer data: name, name of the payer registered in the workspace;
documentType, type of payer registered in the workspace (CPF - Individual,

2023 – 07 V1.1
98
Confidential

Accounts Payment Hub– API User Guide

CNPJ - Legal Entity); and the documentNumber, the payer’s document

number.
beneficiary Beneficiary data: name, beneficiary name; documentType, type of beneficiary
(CPF- Individual, CNPJ- Legal Entity); documentNumber, number of
beneficiary’s document; bankCode, bank code; ispb, SPI participant’s Bra ilian
Payments System Identifier code; and type, beneficiary’s account type.
transaction Transaction data: value, transaction value; code, transaction bank
authentication code; date, date on which the transaction takes place following
RFC 3339 standard/ISO 8601; and endToEnd, E2E identifier of the payment,
starting with the letter E (upper case), have 32 characters.
tags The tag field is the identification of the payment.
paymentValue Payment amount.

When something unexpected happens in the PATCH, we have the error statuses:

▪ 400 - Client information error

▪ 401 - Unauthorized/Authenticated
▪ 403 - Unauthorized
▪ 404 - Information not found
▪ 406 - The target resource does not have a current representation that would be acceptable
▪ 410 - The destination resource is no longer available on the source server
▪ 422 - Entity does not process/inappropriate
▪ 429 - The user sent too many requests in a given period
▪ 500 - Server Error, Application is out
▪ 501 - The server does not support the functionality required to fulfill the request

Response – Status 400

Field Description Mandatory
_errorCode Error code. Yes
_message Error message with a maximum of 30 characters. Yes

2023 – 07 V1.1
99
Confidential

Accounts Payment Hub– API User Guide

_details Detail of the error message with a maximum of 100 Yes

characters.
_timestamp Date and time the error occurred, following RFC 3339 Yes
standard, ISO 8601.
_traceId Trace id is the unique identifier among all calls where we Yes
trace all transactions.
_errors The _errors object has additional information about the No
error:
▪ _code – Specific error code;
▪ _field – Identification of the field with error;
▪ _message – description of the error message.

The other Status Code follows the same pattern as the 400 Bad Request status.

4.2.3.3 GET (Query by ID the data/status of payment of a Pix)

To check the payment status in the POST or PATCH, it is necessary to call endpoint GET (https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/{workspace_id}/pix_pay
ments/{pix_payment_id}).

In the GET parameters, the Workspace id and payment id fields are mandatory:

Parameters
Field Description Mandatory
workspace_id Client’s uni ue id in the Workspace created and follows Yes
the UUID v4 standard of RFC 4122.
pix_payment_id Payment identification id, follows the UUID v4 standard of Yes
RFC 4122.

GET response is the same as POST and PATCH.

2023 – 07 V1.1
100
Confidential

Accounts Payment Hub– API User Guide

4.2.3.4 GET (Paginated query of payment data/status)

To carry out a paginated query of payment status in a date range, it is necessary to call endpoint GET
(https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/{workspace_id}/pix_pay
ments). This query helps the client when carrying out their reconciliations for the payment of the pix
transfer.

Parameters (Filters)
Field Description Value Mandatory
workspace_id Unique client id of a registered - Yes
workspace
_limit Maximum total that each page will - No
bring in the query.
_offset Records being shifted in the query. - No
_sort Filter for paginated query, if nothing is - No
sent, ‘desc’ standard.
initialDate Query start date, YYYY-MM-DD (Year- YYYY-MM-DD No
Month-Day) standard.
finalDate Query final date, YYYY-MM-DD (Year- YYYY-MM-DD No
Month-Day) standard.
Status Transactional status filter that can be PENDING_VALIDATION No
called in the API. READY_TO_PAY
PENDING_CONFIRMATION
PAYED
REJECTED

Response – Status 200

Field Description Mandatory

2023 – 07 V1.1
101
Confidential

Accounts Payment Hub– API User Guide

_limit It is the maximum total number of records that each page Yes
will bring in the query, with a minimum of one (1) and a
maximum of one hundred (100) records per page.
_offset It is the offset record of the query. Yes
_pageNumber It is the page number in the query. Yes
_pageElements It is the amount of record on the query page. Yes
_totalPages It is the total number of pages for this query. Yes
_totalElements It is the total number of records reported in this query. Yes

_content It brings all POST and PATCH response data. Yes

The Status Code: Bad Request follows the same error pattern presented above and for the other status
codes it also follows the same pattern.

2023 – 07 V1.1
102
Confidential

Accounts Payment Hub– API User Guide

4.2.4 Field by Field Tax

With the Payments API you can pay municipal, state or federal field by field taxes. Learn about all the
payments that can be made through our APIs by clicking here.

A simple way for your company to pay field by field taxes such as GARE ICMS, GARE ITCMD, DARF and
GPS.

4.2.4.1 POST (Initiates the payment of a field by field tax)

To initiate a field by field tax payment, it is necessary to call the endpoint POST (https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/taxes_by
_fields_payments), having the following input and output fields:

4.2.4.1.1 GARE ICMS

Parameters
Field Description Mandatory
workspace_id Client’s uni ue id in the Workspace created and follows the UUID Yes
v4 standard of RFC 4122.

Request
Field Description Mandatory
Id Payment id and follows the UUID v4 standard of RFC 4122. No
taxType Type of tax. Enum: GARE, DARF and GPS. Yes

2023 – 07 V1.1
103
Confidential

Accounts Payment Hub– API User Guide

city City. Accepts up to 25 characters (letters, numbers and special No

characters).
stateAbbreviation State abbreviation No
paymentDate Payment date. Format: YYY-MM-DD. No
Tags The tag field is the payment identification and must have a No
maximum of 20 characters and the number of tags must not
exceed 5.
field02 Due date. Format: YYYY-MM-DD. No
field03 Revenue code. Accepts up to 4 integer numeric characters. Yes
field04 State Registration. Accepts up to12 integer numeric characters. No
field05 CPF or CNPJ. Accepts up to14 integer numeric characters. Yes
field06 Active Debt Enrollment or Tag Number. Accepts up to12 integer No
numeric characters.
field07 Reference. Format: YYYY-MM. No
field08 AIIM No. or DEICMEME No. or Installment No.. Accepts up to 9 No
integer numeric characters.
field09 Revenue Amount (Nominal or Adjusted). Accepts up to15 decimal Yes
numeric characters.
field10 Interest on Arrears. Accepts up to 15 decimal numeric characters. No
field11 Late Payment Fine or Infringement Fine. Accepts up to 15 decimal No
numeric characters.
field12 Financial Accrual. Accepts up to 15 decimal numeric characters. No
field13 Attorney’s Fees. Accepts up to 5 decimal numeric characters. No
field15 Taxpayer. Accepts up to 50 characters (letters, numbers and No
special characters).
field16 Address. Accepts up to 38 characters (letters, numbers and No
special characters).
field17 Telephone.Accepts up to 14 characters. Format: (DDD)-12345- No
6789.

2023 – 07 V1.1
104
Confidential

Accounts Payment Hub– API User Guide

field18 CNAE. Accepts up to 8 integer numeric characters. No

field19 Note. Accepts up to 30 characters (letters, numbers and special No
characters).

Depending on the revenue code, other fields may become mandatory.

Response – Status 201

Field Description
Id Payment identification id
workspaceId Client’s uni ue id in the Workspace created.
debitAccount Branch number and account for direct debit
Status Payment status.
rejectReason Reason for rejecting the payment.
Tags The tag field is the identification of the payment.
taxDescription Tax description.
City City.
stateAbbreviation State abbreviation.
accountingDate Accounting date of payment.
field02 Due date.
field03 Revenue code.
field04 State Registration.
field05 CPF or CNPJ.
field06 Active Debt Enrollment or Tag Number.
field07 Reference.
field08 AIIM No. or DEICMEME No. or Installment No.
field09 Revenue Amount (Nominal or Adjusted).
field10 Interest on Arrears.

2023 – 07 V1.1
105
Confidential

Accounts Payment Hub– API User Guide

field11 Late Payment Fine or Infringement Fine.

field12 Financial Accrual.
field13 Attorney’s Fees.
field15 Taxpayer.
field16 Address.
field17 Telephone.
field18 CNAE.
field19 Note.
Transaction Transaction data: value, transaction value; code, transaction bank authentication
code; date, date on which the transaction takes place following RFC 3339
standard;; ISO 8601.
paymentValue Payment amount.

Fields such as field01 and field14, depending on the revenue code, may return in the transaction filled or
null.

4.2.4.1.2 GARE ITCMD

Parameters
Field Description Mandatory
workspace_id Client’s uni ue id in the Workspace created and follows Yes
UUID v4 standard of RFC 4122.

Request
Field Description Mandatory
Id Payment identification id and follows UUID v4 standard of RFC No
4122.

2023 – 07 V1.1
106
Confidential

Accounts Payment Hub– API User Guide

taxType Type of tax. Enum: GARE, DARF and GPS. Yes

city City. Accepts up to 25 characters (letters, numbers and special No
characters).
stateAbbreviation State abbreviation. No
paymentDate Payment date. Format: YYYY-MM-DD. No
Tags The tag field is the payment identification and must have a No
maximum of 20 characters and the number of tags must not
exceed 5.
field01 Taxpayer. Accepts up to 50 characters (letters, numbers and No
special characters).
field02 Due date. Format: YYYY-MM-DD. No
field03 Revenue code. Accepts up to 4 integer numeric characters. Yes
field04 Declaration number. Accepts up to 12 integer numeric characters. No
field05 CNPJ or CPF. Accepts up to 14 integer numeric characters. Yes
field06 Active Debt Enrollment or Tag Number. Accepts up to 12 integer No
numeric characters.
field10 Interest on Arrears. Accepts up to 15 decimal numeric characters. No
field11 Late Payment Fine or Infringement Fine (Nominal or Adjusted). No
Accepts up to 15 decimal numeric characters.
field12 Financial Accrual. Accepts up to 15 decimal numeric characters. No
field13 Attorney’s Fees. Accepts up to 5 decimal numeric characters. No
field16 Address. Accepts up to 38 characters (letters, numbers and No
special characters).
field17 Telephone. Accepts up to 14 characters. Format: (DDD)-12345- No
6789.
field18 ZIP CODE. Accepts up to 8 integer numeric characters. No
field19 Note. Accepts up to 30 characters (letters, numbers and special No
characters).

2023 – 07 V1.1
107
Confidential

Accounts Payment Hub– API User Guide

Depending on the revenue code, other fields may become mandatory.

Response – Status 201

Field Description
id Payment identification id
workspaceId Client’s uni ue id in the Workspace created.
debitAccount Branch number and account for direct debit
status Payment status.
rejectReason Reason for rejecting the payment.
tags The tag field is the identification of the payment.
taxDescription Tax description.
city City.
stateAbbreviation State abbreviation.
field01 Taxpayer.
field02 Due date.
field03 Revenue code.
field04 Declaration number.
field05 CNPJ or CPF.
field06 Active Debt Enrollment or Tag Number.
field10 Interest on Arrears.
field11 Late Payment Fine or Infringement Fine (Nominal or Adjusted).
field12 Financial Accrual.
field13 Attorney’s Fees.
field16 Address.
field17 Telephone.
field18 ZIP CODE.
field19 Note.

2023 – 07 V1.1
108
Confidential

Accounts Payment Hub– API User Guide

paymentValue Payment amount.

accountingDate Accounting date of payment.
transaction Transaction data: value, transaction value; code, transaction bank authentication
code; date, date on which the transaction takes place following RFC 3339 standard;
ISO 8601.

Fields such as field07, field08, field09, field14 and field15 depending on the revenue code, may return in
the transaction filled or null.

4.2.4.1.3 DARF

Parameters
Field Description Mandatory
workspace_id Client’s uni ue id in the Workspace created and follows UUID v Yes
standard of RFC 4122.

Request
Field Description Mandatory
id Payment identification id and follows UUID v4 standard of RFC 4122. No
taxType Type of tax. Enum: GARE, DARF and GPS. Yes
city City. Accepts up to 25 characters (letters, numbers and special No
characters).
stateAbbreviation State abbreviation. No
paymentDate Payment date. Format: YYYY-MM-DD. No
tags The tag field is the payment identification and must have a maximum No
of 20 characters and the number of tags must not exceed 5.

2023 – 07 V1.1
109
Confidential

Accounts Payment Hub– API User Guide

field01 Company Name/ Telephone. Accepts up to 50 characters (letters, No

numbers and special characters).
field02 Calculation Period. Format: YYYY-MM-DD. No
field03 CPF or CNPJ number. Accepts up to 14 integer numeric characters. Yes
field04 Revenue code. Accepts up to 4 integer numeric characters. Yes
field05 Reference number. Accepts up to 17 integer numeric characters. No
field06 Due date. Format: YYYY-MM-DD. Yes
field07 Principal value. Accepts up to 15 decimal numeric characters. Yes
field08 Fine value. Accepts up to 15 decimal numeric characters. No
field09 Amount of Interest and/or Charges DL-1.025/69. Accepts up to 15 No
decimal numeric characters.

Response – Status 201

Field Description
id Payment identification id
workspaceId Client’s uni ue id in the Workspace created.
debitAccount Branch number and account for direct debit
status Payment status.
rejectReason Reason for rejecting the payment.
tags The tag field is the identification of the payment.
taxDescription Tax description.
city City.
stateAbbreviation State abbreviation.
field01 Company Name/ Telephone.
field02 Calculation Period.
field03 CPF or CNPJ number.
field04 Revenue code.
field05 Reference number.

2023 – 07 V1.1
110
Confidential

Accounts Payment Hub– API User Guide

field06 Due date.

field07 Principal value.
field08 Fine value.
field09 Amount of Interest and/or Charges DL-1.025/69.
paymentValue Payment amount.
accountingDate Accounting date of payment.
transaction Transaction data: value, transaction value; code, transaction bank authentication
code; date, date on which the transaction takes place following RFC 3339 standard;
ISO 8601.

Fields such as field10, field11, field12, field13, field14, field15, field16, field17, filed18 and field19 depending
on the revenue code, may return in the transaction filled or null.

4.2.4.1.4 GPS

Parameters
Field Description Mandatory
workspace_id Client’s uni ue id in the Workspace created and follows Yes
UUID v4 standard of RFC 4122.

Request
Field Description Mandatory
id Payment identification id and follows UUID v4 standard of No
RFC 4122.
taxType Type of tax. Enum: GARE, DARF and GPS. Yes
city City. Accepts up to 25 characters (letters, numbers and No
special characters).

2023 – 07 V1.1
111
Confidential

Accounts Payment Hub– API User Guide

stateAbbreviation State abbreviation. No

paymentDate Payment date. Format: YYYY-MM-DD. No
tags The tag field is the payment identification and must have No
a maximum of 20 characters and the number of tags must
not exceed 5.
field01 Name or Company Name / Phone / Address. Accepts up No
to 40 characters (letters, numbers and special characters).
field03 Code of Payment. Accepts up to4 integer numeric Yes
characters.
field04 Reference period. Formato YYYY-MM. Yes
field05 Identifier. Accepts up to 15 integer numeric characters. Yes
field06 Social Security Amount. Accepts up to 15 decimal numeric Yes
characters.
field09 Other Entities Amount. Accepts up to 15 decimal numeric No
characters.
field10 ATM/Fine and Interest. Accepts up to 15 decimal numeric No
characters.

Response – Status 201

Field Description
id Payment identification id
workspaceId Client’s uni ue id in the Workspace created.
debitAccount Branch number and account for direct debit
status Payment status.
rejectReason Reason for rejecting the payment.
tags The tag field is the identification of the payment.
taxDescription Tax description.
city City.
stateAbbreviation State abbreviation.

2023 – 07 V1.1
112
Confidential

Accounts Payment Hub– API User Guide

field01 Name or Company Name / Phone / Address.

field03 Code of Payment.
field04 Reference period.
field05 Identifier.
field06 Social Security Amount.
field09 Other Entities Amount.
field10 ATM/Fine and Interest.
paymentValue Payment amount.
accountingDate Accounting date of payment.
transaction Transaction data: value, transaction value; code, transaction bank authentication
code; date, date on which the transaction takes place following RFC 3339 standard;
ISO 8601.

Fields such as field02, field07, field08, field11, field12, field13, field14, field15, filed16, field17, field18 and
field19, depending on the revenue code, may return in the transaction filled or null.

2023 – 07 V1.1
113
Confidential

Accounts Payment Hub– API User Guide

When something unexpected happens in the POST, we have the error statuses:

▪ 400 - Client information error

▪ 401 - Unauthorized/Authenticated
▪ 403 - Unauthorized
▪ 404 - Information not found
▪ 406 - The target resource does not have a current representation that would be acceptable
▪ 422 - Entity does not process/inappropriate
▪ 429 - User sent too many requests in a given period
▪ 500 - Server error, Application is out
▪ 501 - The server does not support the functionality required to fulfill the request

Response – Status 400

Field Description Mandatory
_errorCode Error code. Yes
_message Error message with a maximum of 30 characters. Yes
_details Detail of the error message with a maximum of 100 Yes
characters.
_timestamp Date and time the error occurred, following RFC 3339 Yes
standard, ISO 8601.
_traceId Trace id is the unique identifier among all calls where we Yes
trace all transactions.
_errors The _errors object has additional information about the No
error:
▪ _code – Specific error code;
▪ _field – Identification of the field with error;
▪ _message – error message description.

The other Status Code follow the same pattern as 400 Bad Request status.

2023 – 07 V1.1
114
Confidential

Accounts Payment Hub– API User Guide

4.2.4.2 PATCH (Makes payment of a field by field tax)

To make a payment of a field by field tax, it is necessary to call endpoint PATCH (https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/taxes_by
_fields_payments/:taxes_by_fields_payment_id), with the following input and output fields:

4.2.4.2.1 GARE ICMS

Parameters
Field Description Mandatory
workspace_id Client’s uni ue id in the Workspace created and follows Yes
UUID v4 standard of RFC 4122.
taxes_by_fields_payment_id Payment identification id, follows UUID v4 standard of Yes
RFC 4122.

Request
Field Description Mandatory
debitAccount Branch number and account for direct debit No
Status Payment status AUTHORIZED to release the payment. Yes

Response – Status 200

Field Description
id Payment identification id
workspaceId Client’s uni ue id in the Workspace created.
debitAccount Branch number and account for direct debit
status Payment status.
rejectReason Reason for rejecting the payment.
tags The tag field is the identification of the payment.
taxDescription Tax description.
city City.

2023 – 07 V1.1
115
Confidential

Accounts Payment Hub– API User Guide

stateAbbreviation State abbreviation.

accountingDate Accounting date of payment.
field02 Due date.
field03 Revenue code.
field04 State Registration.
field05 CPF or CNPJ.
field06 Active Debt Enrollment or Tag Number.
field07 Reference.
field08 AIIM No. or DEICMEME No. or Installment No..
field09 Revenue Amount (Nominal or Adjusted).
field10 Interest on Arrears.
field11 Late Payment Fine or Infringement Fine.
field12 Financial Accrual.
field13 Attorney’s Fees.
field15 Taxpayer.
field16 Address.
field17 Telephone.
field18 CNAE.
field19 Note.
transaction Transaction data: value, transaction value; code, transaction bank authentication
code; date, date on which the transaction takes place following RFC 3339 standard;
ISO 8601.
paymentValue Payment amount.

Field such as field01 and field14, depending on the revenue code, may return in the transaction filled or
null.

2023 – 07 V1.1
116
Confidential

Accounts Payment Hub– API User Guide

4.2.4.2.2 GARE ITCMD

Parameters
Field Description Mandatory
workspace_id Client’s uni ue id in the Workspace created and follows Yes
UUID v4 standard of RFC 4122.
taxes_by_fields_payment_id Payment identification id, follows UUID v4 standard of Yes
RFC 4122.

Request
Field Description Mandatory
debitAccount Branch number and account for direct debit No
status Payment status AUTHORIZED to release the payment. Yes

Response – Status 200

Field Description
id Payment identification id
workspaceId Client’s uni ue id in the Workspace created.
debitAccount Branch number and account for direct debit
status Payment status.
rejectReason Reason for rejecting the payment.
tags The tag field is the identification of the payment.
taxDescription Tax description.
city City.
stateAbbreviation State abbreviation.
field01 Taxpayer.
field02 Due date.
field03 Revenue code.
field04 Declaration number.

2023 – 07 V1.1
117
Confidential

Accounts Payment Hub– API User Guide

field05 CNPJ or CPF.

field06 Active Debt Enrollment or Tag Number.
field10 Interest on Arrears.
field11 Late Payment Fine or Infringement Fine (Nominal or Adjusted).
field12 Financial Accrual.
field13 Attorney’s Fees.
field16 Address.
field17 Telephone.
field18 ZIP CODE.
field19 Note.
paymentValue Payment amount.
accountingDate Accounting date of payment.
transaction Transaction data: value, transaction value; code, transaction bank authentication
code; date, date on which the transaction takes place following RFC 3339 standard;
ISO 8601.

Fields such as field07, field08, field09, field14 and field15, depending on the revenue code, may return in
the transaction filled or null.

4.2.4.2.3 DARF

Parameters
Field Description Mandatory
workspace_id Client’s uni ue id in the Workspace created and follows Yes
UUID v4 standard of RFC 4122.
taxes_by_fields_payment_id Payment identification id, follows UUID v4 standard of Yes
RFC 4122.

2023 – 07 V1.1
118
Confidential

Accounts Payment Hub– API User Guide

Request
Field Description Mandatory
debitAccount Branch number and account for direct debit No
status Payment status AUTHORIZED to release the payment. Yes

Response – Status 200

Field Description
id Payment identification id
workspaceId Client’s uni ue id in the Workspace created.
debitAccount Branch number and account for direct debit
status Payment status.
rejectReason Reason for rejecting the payment.
tags The tag field is the identification of the payment.
taxDescription Tax description.
city City.
stateAbbreviation State abbreviation.
field01 Company Name/ Telephone.
field02 Calculation Period.
field03 CPF or CNPJ number.
field04 Revenue code.
field05 Reference number.
field06 Due date.
field07 Principal value.
field08 Fine value.
field09 Amount of Interest and/or Charges DL-1.025/69.
paymentValue Payment amount.
accountingDate Accounting date of payment.

2023 – 07 V1.1
119
Confidential

Accounts Payment Hub– API User Guide

transaction Transaction data: value, transaction value; code, transaction bank authentication
code; date, date on which the transaction takes place following RFC 3339 standard;
ISO 8601.

Fields such as field10, field11, field12, field13, field14, field15, field16, field17, filed18 and field19 depending
on the revenue code, may return in the transaction filled or null.

4.2.4.2.4 GPS

Parameters
Field Description Mandatory
workspace_id Client’s uni ue id in the Workspace created and follows Yes
UUID v4 standard of RFC 4122.
taxes_by_fields_payment_id Payment identification id, follows UUID v4 standard of Yes
RFC 4122.

Request
Field Description Mandatory
debitAccount Branch number and account for direct debit No
status Payment status AUTHORIZED to release the payment. Yes

Response – Status 200

Field Description

2023 – 07 V1.1
120
Confidential

Accounts Payment Hub– API User Guide

id Payment identification id
workspaceId Client’s uni ue id in the Workspace created.
debitAccount Branch number and account for direct debit
status Payment status.
rejectReason Reason for rejecting the payment.
tags The tag field is the identification of the payment.
taxDescription Tax description.
city City.
stateAbbreviation State abbreviation.
field01 Name or Company Name / Phone / Address.
field03 Code of Payment.
field04 Reference period.
field05 Identifier.
field06 Social Security Amount.
field09 Other Entities Amount.
field10 ATM/Fine and Interest.
paymentValue Payment amount.
accountingDate Accounting date of payment.
transaction Transaction data: value, transaction value; code, transaction bank authentication
code; date, date on which the transaction takes place following RFC 3339 standard;
ISO 8601.

Fields such as field02, field07, field08, field11, field12, field13, field14, field15, filed16, field17, field18 and
field19, depending on the revenue code, may return in the transaction filled or null.

When something unexpected happens in the PATCH, we have the error statuses:

▪ 400 - Client information error

2023 – 07 V1.1
121
Confidential

Accounts Payment Hub– API User Guide

▪ 401 - Unauthorized/Authenticated
▪ 403 - Unauthorized
▪ 404 - Information not found
▪ 406 - The target resource does not have a current representation that would be acceptable
▪ 410 - The target resource is no longer available on the source server
▪ 422 - Entity does not process/inappropriate
▪ 429 - The user sent too many requests in a given period
▪ 500 - Server error, Application is out
▪ 501 - The server does not support the functionality required to fulfill the request

Response – Status 400

Field Description Mandatory
_errorCode Error code. Yes
_message Error message with a maximum of 30 characters. Yes
_details Detail of the error message with a maximum of 100 Yes
characters.
_timestamp Date and time the error occurred, following RFC 3339 Yes
standard, ISO 8601.
_traceId Trace id is the unique identifier among all calls where we Yes
trace all transactions.
_errors The _errors object has additional information about the No
error:
▪ _code – Specific error code;
▪ _field – Identification of the field with error;
▪ _message – error message description.

The other Status Code follows the same pattern as 400 Bad Request status.

2023 – 07 V1.1
122
Confidential

Accounts Payment Hub– API User Guide

4.2.4.3 GET (Query by ID the data/status of payment of a tax)

To check the payment status in the POST or PATCH, it is necessary to call endpoint GET (https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/taxes_by
_fields_payments/:taxes_by_fields_payment_id).

In GET parameters, Workspace id and payment id fields are mandatory:

Parameters
Field Description Mandatory
workspace_id Client’s uni ue id in the Workspace created and follows Yes
UUID v4 standard of RFC 4122.
taxes_by_fields_payment_id Payment identification id, follows UUID v4 standard of Yes
RFC 4122.

The GET response is the same as POST and PATCH.

4.2.4.4 GET (Paginated query of payment data/status)

To carry out a paginated query of payment statuses in a date range, it is necessary to call endpoint GET
(https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/taxes_by
_fields_payments). This query helps the client when carrying out reconciliations for the payment of a field
by field tax.

Parameters (Filtros)
Field Description Value Mandatory
workspace_id Unique client id of a registered - Yes
workspace.
_limit Maximum total that each page will - No
bring in the query.

2023 – 07 V1.1
123
Confidential

Accounts Payment Hub– API User Guide

_offset Records being shifted in the query. - No

_sort Filter for paginated query if nothing is - No
sent, ‘desc’ standard.
initialDate Start date of the query, YYYY-MM-DD YYYY-MM-DD No
(Year-Month-Day) standard.
finalDate Final date of the query, YYYY-MM-DD YYYY-MM-DD No
(Year-Month-Day) standard.
status Transactional status filter that can be PENDING_VALIDATION No
called in the API. READY_TO_PAY
PENDING_CONFIRMATION
PAYED
REJECTED

Response – Status 200

Field Description Mandatory
_limit It is the maximum total number of records that each page Yes
will bring in the query, with a minimum of one (1) and a
maximum of one hundred (100) records per page.
_offset It is the offset record of the query. Yes
_pageNumber It is the page number of the query. Yes
_pageElements It is the number of records on the query page. Yes
_totalPages It is the total number of pages for this query. Yes
_totalElements It is the total number of records reported in this query. Yes

_content It brings all POST and PATCH response data. Yes

2023 – 07 V1.1
124
Confidential

Accounts Payment Hub– API User Guide

The Status Code: Bad Request follows the same error pattern presented above and for the other status
code it also follows the same pattern.

4.2.5 Vehicle Debts

With the Payment API with vehicle debts you may query and pay IPVA, DPVAT and Licensing. Learn about
all the payments that can be made through our APIs by clicking here.

4.2.5.1 GET (Queries debts of a renavam)

To query a vehicle debt, it is necessary to call endpoint GET (https://trust-

open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/available
_vehicle_taxes), check below the available filters and the response:

Parameters (Filtros)
Field Description Mandatory
workspace_id Client’s uni ue id in the Workspace created and follows UUID v4 Yes
standard of RFC 4122.
renavam Renavam number. Accepts up to12 integer numeric characters. Yes
stateAbbreviation State abbreviation. Yes
_limit Maximum total that each page will bring in the query. No
_offset Records being shifted in the query. No

2023 – 07 V1.1
125
Confidential

Accounts Payment Hub– API User Guide

_sort Filter for paginated uery if nothing is sent, ‘desc’ standard. No

For now, we only have available Renavam for the state of Minas Gerais (MG).

Response – Status 200

Field Description
_limit It is the maximum total number of records that each page will bring in the query,
with a minimum of one (1) and a maximum of one hundred (100) records per page.
_offset It is the offset record of the query.
_pageNumber It is the page number of the query.
_pageElements It is the number of records on the query page.
_totalPages It is the total number of pages for this query.
_totalElements It is the total number of records reported in this query.
_content It brings the renavam data:
renavam: Renavam number;
taxType: Type of vehicle debt. Enum: IPVA, DPVAT, LICENSING;
exerciseYear: Exercise Year;
stateAbbreviation: State abbreviation;
licensePlate: License Plate;
owner: Owner’s name;
dueDate: Due date;
value: Amount payable;
typeQuota: Type of quota.

2023 – 07 V1.1
126
Confidential

Accounts Payment Hub– API User Guide

4.2.5.2 POST (Starts payment of a vehicle debt)

To initiate a payment of a vehicle debt, it is necessary to call endpoint POST (https://trust-

open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/vehicle_t
axes_payments), having the following input and output fields:

Parameters
Field Description Mandatory
workspace_id Client’s uni ue id in the Workspace created and follows UUID v Yes
standard of RFC 4122.

Request
Field Description Mandatory
id Payment identification id and follows UUID v4 standard of RFC 4122. No
renavam Renavam number. Accepts up to 12 integer numeric characters. Yes
taxType Type of vehicle debt. Enum: IPVA, DPVAT, LICENSING. Yes
exerciseYear Exercise Year. Format: YYYY. Yes
stateAbbreviation State abbreviation. Yes
docType Type of document. Enum: CPF, CNPJ. No
documentNumber Document number. Accepts up to 14 integer numeric characters. No
quotaType Type of quota. Enum: SINGLE, SIGNLE_WITH_DISCOUNT, FIRST, Yes
SECOND, THIRD, FOURTH, FIFTH, SIXTH.
paymentDate Payment date. Format: YYYY-MM-DD. No
tags The tag field is the payment identification and must have a No
maximum of 20 characters and the number of tags must not exceed
5.

2023 – 07 V1.1
127
Confidential

Accounts Payment Hub– API User Guide

Response – Status 201

Field Description
id Payment identification id
workspaceId Client’s uni ue id in the Workspace created.
debitAccount Branch number and account for direct debit
status Payment status.
rejectReason Reason for rejecting the payment.
tags The tag field is the identification of the payment.
owner Owner’s name.
licensePlate License plate.
quotaType Type of quota.
stateAbbreviation State abbreviation.
renavam Renavam number.
taxType Type of vehicle debt.
exerciseYear Exercise year.
documentType Type of document.
documentNumber Document number.
Quotas Brings the quota data: dueDate: Due date; value: Amount payable; payed: Checks
if the quota has already been paid or not; quotaType: Quota type. Enum: SINGLE,
SIGNLE_WITH_DISCOUNT, FIRST, SECOND, THIRD, FOURTH, FIFTH, SIXTH.
paymentDate Payment date. Format: YYYY-MM-DD.
transaction Transaction data: value, transaction value; code, transaction bank authentication
code; date, date on which the transaction takes place following RFC 3339 standard;
ISO 8601.
paymentValue Payment amount.

Th Own r fi d ha orr s onds o h own r’s na , for IPVA/LICENSING returns null.

2023 – 07 V1.1
128
Confidential

Accounts Payment Hub– API User Guide

When something unexpected happens in the POST, we have the error statuses:

▪ 400 - Client information error

▪ 401 - Unauthorized/Authenticated
▪ 403 - Unauthorized
▪ 404 - Information not found
▪ 406 - The target resource does not have a current representation that would be acceptable
▪ 422 - Entity does not process/inappropriate
▪ 429 - The user sent too many requests in a given period
▪ 500 - Server Error, Application is out
▪ 501 - The server does not support the functionality required to fulfill the request

Response – Status 400

Field Description Mandatory
_errorCode Error code. Yes
_message Error message with a maximum of 30 characters. Yes
_details Detail of the error message with a maximum of 100 Yes
characters.
_timestamp Date and time the error occurred, following RFC 3339 Yes
standard, ISO 8601.
_traceId Trace id is the unique identifier among all calls where we Yes
trace all transactions.

2023 – 07 V1.1
129
Confidential

Accounts Payment Hub– API User Guide

_errors The _errors object has additional information about the No

error:
▪ _code – Specific error code;
▪ _field – Identification of the field with error;
▪ _message – error message description.

The other Status Code follows the same pattern as the 400 Bad Request status.

4.2.5.3 PATCH (Makes payment of a vehicle debt)

To make a payment of a vehicle debt, it is necessary to call endpoint PATCH (https://trust-

open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/vehicle_t
axes_payments/:vehicle_tax_id), with the following input and output fields:

Parameters
Field Description Mandatory
workspace_id Client’s unique id in the Workspace created and follows Yes
UUID v4 standard of RFC 4122.
vehicle_tax_id Payment identification id, follows UUID v4 standard of Yes
RFC 4122.

Request
Field Description Mandatory
debitAccount Branch number and account for direct debit No
status Payment status AUTHORIZED to release the payment. Yes

Response – Status 200

Field Description
id Payment identification id
workspaceId Client’s uni ue id in the Workspace created.

2023 – 07 V1.1
130
Confidential

Accounts Payment Hub– API User Guide

debitAccount Branch number and account for direct debit

status Payment status.
rejectReason Reason for rejecting the payment.
tags The tag field is the identification of the payment.
Owner Owner’s name
licensePlate License plate
quotaType Quota type.
stateAbbreviation State abbreviation.
renavam Renavam number.
taxType Type of vehicle debt.
exerciseYear Exercise year
documentType Document type
documentNumber Document number
quotas Brings the quota data: dueDate: Due date; value: Amount payable; payed: Checks
if the quota has already been paid or not; quotaType: Quota type. Enum: SINGLE,
SIGNLE_WITH_DISCOUNT, FIRST, SECOND, THIRD, FOURTH, FIFTH, SIXTH.
paymentDate Payment date. Format: YYYY-MM-DD.
transaction Transaction data: value, transaction value; code, transaction bank authentication
code; date, date on which the transaction takes place following RFC 3339 standard;
ISO 8601.
paymentValue Payment amount.

When something unexpected happens in the PATCH, we have the error statuses:

▪ 400 - Client information error

▪ 401 - Unauthorized/Authenticated
▪ 403 - Unauthorized
▪ 404 - Information not found
▪ 406 - The target resource does not have a current representation that would be acceptable
▪ 410 - The destination resource is no longer available on the source server

2023 – 07 V1.1
131
Confidential

Accounts Payment Hub– API User Guide

▪ 422 - Entity does not process/inappropriate

▪ 429 - The user sent too many requests in a given period
▪ 500 - Server Error, Application is out
▪ 501 - The server does not support the functionality required to fulfill the request

Response – Status 400

Field Description Mandatory
_errorCode Error code. Yes
_message Error message with a maximum of 30 characters. Yes
_details Detail of the error message with a maximum of 100 Yes
characters.
_timestamp Date and time the error occurred, following RFC 3339 Yes
standard, ISO 8601.
_traceId Trace id is the unique identifier among all calls where we Yes
trace all transactions.
_errors The _errors object has additional information about the No
error:
▪ _code – Specific error code;
▪ _field – Identification of the field with error;
▪ _message – error message description.

The other Status Code follows the same pattern as the 400 Bad Request status.

2023 – 07 V1.1
132
Confidential

Accounts Payment Hub– API User Guide

4.2.5.4 GET (Queries by ID the payment data/status of a vehicle debt)

To check the payment status in the POST or PATCH, it is necessary to call endpoint GET (https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/vehicle_t
axes_payments/:vehicle_tax_id).

In GET parameters, the Workspace id and payment id fields are mandatory:

Parameters
Field Description Mandatory
workspace_id Client’s uni ue id in the Workspace created and follows Yes
UUID v4 standard of RFC 4122.
vehicle_tax_id Payment identification id, follows UUID v4 standard of Yes
RFC 4122.

The GET response is the same as POST and PATCH.

4.2.5.5 GET (Paginated query of payment data/status)

To carry out a paginated query of payment statuses in a date range, it is necessary to call endpoint GET
(https://trust-
open.api.santander.com.br/management_payments_partners/v1/workspaces/:workspace_id/vehicle_t
axes_payments). This query helps the client when carrying out reconciliations for the payment of a vehicle
debt.

Parameters (Filtros)
Field Description Value Mandatory

2023 – 07 V1.1
133
Confidential

Accounts Payment Hub– API User Guide

workspace_id Unique client id of a registered - Yes

workspace.
_limit Maximum total that each page will - No
bring in the query.
_offset Records being shifted in the query. - No
_sort Filter for paginated query if nothing is - No
sent, ‘desc’ standard.
initialDate Start date of the query, YYYY-MM-DD YYYY-MM-DD No
(Year-Month-Day) standard.
finalDate Final date of the query, YYYY-MM-DD YYYY-MM-DD No
(Year-Month-Day).
status Transactional status filter that can be PENDING_VALIDATION No
called in the API. READY_TO_PAY
PENDING_CONFIRMATION
PAYED
REJECTED

Response – Status 200

Campo Descrição Obrigatório
_limit It is the maximum total number of records that each page Yes
will bring in the query, with a minimum of one (1) and a
maximum of one hundred (100) records per page.
_offset It is the offset record of the query. Yes
_pageNumber It is the page number of the query. Yes
_pageElements It is the number of records on the query page. Yes
_totalPages It is the total number of pages for this query. Yes
_totalElements It is the total number of records reported in this query. Yes

_content It brings all POST and PATCH response data. Yes

2023 – 07 V1.1
134
Confidential

Accounts Payment Hub– API User Guide

The Status Code: Bad Request follows the same error pattern presented above and for the other status
code it also follows the same pattern.

4.3 Payment schedules

In the payment hub, the solution is 24x7, respecting the accounting date of the available products. In the
case of Payment APIs, it is as follows:

▪ Payment of bank slips: 11:50pm Santander and 11:50pm Other Banks;

▪ Collection payment with bar codes: 11pm;
▪ Sending Pix (Branch/Account and Key): 24x7;
▪ Payment of Pix QRCode: 24x7;
▪ Taxes (GARE, GPS and DARF): 11pm;
▪ Renavam MG: It is unavailable from 2am to 4am from Monday to Saturday and from 00:00 to 7am
on Sundays.

2023 – 07 V1.1
135
Confidential

Accounts Payment Hub– API User Guide

4.4 Receipts
In the Payments API, both the client develops his/her own receipt according to the data returned from
the API (bank authentication returns in the API as well as in CNAB), when he/she can pick up the 2nd copy
of the receipt through the Corporate Internet Banking (IB), the availability is immediate at IB after
payment.

Path to obtain the Receipt: IB > Pagamentos/Pix/Transferências > 2ª Via Comprovante > Consultar
Comprovantes > Realizar Filtros Desejados [IB > Payments/Pix/Transfers > 2nd Receipt Copy > Consult
Receipts ? Perform Desired Filters]:

Example:

2023 – 07 V1.1
136
Confidential

Accounts Payment Hub– API User Guide

5. Version history

Version Date Change

V1.0 December/2022 Official version
V1.1 July/2023 Functional changes and inclusion of Renavam products, field by
field tax, reconciliation API, DDA and Webhook DDA

2023 – 07 V1.1
137
Confidential

Accounts Payment Hub– API User Guide

2023 – 07 V1.1
138
Confidential

Accounts Payment Hub– API User Guide

2023 – 07 V1.1
139