Confidential

Collection Hub– API User Guide

Collection API
API – USER GUIDE
Confidential

Collection Hub– API User Guide

1. Overview.................................................................................................................................................4

1.1 Advantages ...................................................................................................................................................4

2. Onboarding .............................................................................................................................................7

2.1 Developer Portal ...........................................................................................................................................7

2.2 Technical Documentation (SWAGGER).......................................................................................................16
2.3 Certificates ..................................................................................................................................................16
2.4 Access Credential ........................................................................................................................................16
2.6.1 OAuth 2 ...............................................................................................................................................17
2.6.2 Access Token.......................................................................................................................................17
2.5 API Servers ..................................................................................................................................................21
2.6 Sandbox ......................................................................................................................................................22
2.7 Production Environment ............................................................................................................................22
2.8 Collection Postman .....................................................................................................................................22
3. Setup Vision ..........................................................................................................................................26

3.1 HTTP Methods ............................................................................................................................................26

3.2 Status HTTP return code .............................................................................................................................26
3.3 Workspaces ................................................................................................................................................27
3.3.1 Workspace Creation ...........................................................................................................................28
3.3.2 Workspace List Query .........................................................................................................................31
3.3.3 Workspace Unit Query .......................................................................................................................32
3.3.4 Workspace Maintenance ....................................................................................................................32
3.3.5 Deleting a Workspace .........................................................................................................................32
4. Transaction ...........................................................................................................................................40

4.1 BANK SLIP - POST ........................................................................................................................................40

4.2 BANK SLIP - GET (Sonda) .............................................................................................................................45
4.3 BILLS - GET – Payment slips inquiry ............................................................................................................46
4.4 BANK SLIP - PATCH......................................................................................................................................51
4.5 WEBHOOK...................................................................................................................................................54
4.6 PDF Bill Collection Generation ....................................................................................................................58
5. Notes – POST (Payment slips Registration) ..........................................................................................60

6. Notes – PATCH (Payment slips Instructions) ........................................................................................68

7. Script in case of Errors during validations ............................................................................................73

2024 – 04 V2.1
1
Confidential

Collection Hub– API User Guide

The objective of this material is to present the concepts of the Billing APIs,
Onboarding, methods of use, technical documentation and business rules, as
well as examples of use.

2024 – 04 V2.1
2
Confidential

Collection Hub– API User Guide

OVERVIEW

2023 – 05 V2.0
3
Confidential

Collection Hub– API User Guide

1. Overview

The Santander Collection API is a service developed to facilitate the management of our customers'
receipts, simplifying the registration of bank slips, regardless of the company's business model.
API (Application Programming Interface) can be understood as a set of norms, standards and protocols
that allow two services to communicate.

This documentation has been structured to support people responsible for developing and adapting the
systems of Santander client companies, who wish to operate Collection through our APIs.

1.1 Advantages

• Connection standardization, as all systems that will use the service know exactly which fields,
parameters and routes to send or receive and which are the possible responses;
• Provide integration between systems built in different languages in an agile, secure and fully
compatible manner;
• Possess authentication layers generating access security in use;
• 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.

2023 – 05 V2.0
4
Confidential

Collection Hub– API User Guide

ONBOARDING

2023 – 05 V2.0
5
Confidential

Collection Hub– API User Guide

2. Onboarding

The Billing API is indicated for companies that needs to register their bills in an automated, fast and secure way,
directly from their management system or through an electronic connection between the company and its
customers (e-commerce).

For the use of the API, we provide customers with self-service through the Developer Portal, where it is possible
to obtain technical documentation, perform tests in SandBox, register certificates and generate credentials for
using the service (Sandbox and Production):

In order to use the Collection slip registration service via API, it is necessary to subscribe to Santander Cobrança,
through the contracting of an agreement. If you already have an active billing agreement, you can go directly to
the Developer Portal access step.

If you do not have a Billing Agreement, you can access Internet Banking for Legal Entities or the Santander
Empresas APP and contract it through the option Cobrança e Recebimentos > Convênio de Cobrança > Contratar
Convênio, or directly with your Manager.

Important: to operate the Billing Through API, it is necessary that the agreement has the parameter “Entrada
Online” enabled. If in doubt, contact your manager or Corporate Customer Service.

2.1 Developer Portal

The Developer Portal must be accessed through the link https://developer.santander.com.br
In this environment you will be able to view and consume all the APIs published by Santander.

Only the Internet Banking Local Platform Master User has immediate access to the application creation area within
the Developer Portal. The Master user can also invite other users, giving them permission to create applications on
the company’s behalf. To do so, simply send the invitation in the “Members” area”.

It is necessary that the Master User has the Santander ID (Token Device) enabled;

In order for the Master User to have access to two or more companies within the Developer Portal, it is necessary
log in for the different companies, so they will be associated with the accounts.

Step 1 – Obtaining the API Credentials

2023 – 05 V2.0
7
 Confidential

Collection Hub– API User Guide

To operate through our API, it’s necessary to obtain the API Credentials (ClientID and ClientSecret) specific for
Collection Product.

You should obtain the credentials by accessing our Developer Portal and registering your Security Certificate
(.PEM, .CER or .CRT) and choosing the Collection API (Emissão de Boletos).
There is two ways to enter in our Developer Portal: Master User or External User

- Log in at our DevPortal as an Internet Banking Local Platform Master user (user needs to have a Token assigned):

1 – Master User access https://developer.santander.com.br/ and click in Entrar;

2 – Click in “Acesse com sua conta PJ”;

3 – Use your Internet Banking credentials to connect;

4 – Once logged, select the “Produção” environment, Click in Aplicações > Criar Nova Aplicação;

5 – Select “Sou Desenvolvedor” and create an API Application. It’ll be required to give an app name, upload your Security Certificate and
select our API (Emissão de Boletos);

6 – Click in “Enviar” and wait the processing. If the process went well, the API credentials will be available up to 5 minutes in “Minhas
Aplicações”.

- Log in at our DevPortal as an external user (needs to receive an invitation from a Master company’s user):

When logged in our DevPortal, the Master user can send an invitation to external users. This way, this person will be able to create API APPs
on behalf of that company and receive their Credentials (ClientID and ClientSecret).

1 – External user access https://developer.santander.com.br/ and click in Cadastrar;

2 – Inform all the required data to complete the registration;

3 - Once the registration is completed and the Master sent the invitation, accept it by clicking in Produção > Verificar Convites;

4 – Select “Produção” environment, Click in Aplicações > Criar Nova Aplicação;

5 – Select “Sou Desenvolvedor” and create an API Application. It’ll be required to give an app name, upload your Security Certificate and
select our API (Emissão de Boletos);

6 - Click in “Enviar” and wait the processing. If the process went well, the API credentials will be available up to 5 minutes in “Minhas
Aplicações”.

2023 – 05 V2.0
8
Confidential

Collection Hub– API User Guide

2023 – 05 V2.0
9
Confidential

Collection Hub– API User Guide

2023 – 05 V2.0
10
Confidential

Collection Hub– API User Guide

2023 – 05 V2.0
11
Confidential

Collection Hub– API User Guide

2023 – 05 V2.0
12
Confidential

Collection Hub– API User Guide

2023 – 05 V2.0
13
Confidential

Collection Hub– API User Guide

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

2023 – 05 V2.0
14
Confidential

Collection Hub– API User Guide

2023 – 05 V2.0
15
Confidential

Collection Hub– API User Guide

2.2 Technical Documentation (SWAGGER)

SWAGGER is the technical documentation and it is an Open Source application that helps developers in defining,
creating, documenting and 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, data
received, data returned, HTTP codes and authentication methods, among others.
SWAGGER is available on our Developer Portal and should be used in addition to this manual.
2.3 Certificates
Digital certificate is an electronic document that contains data of the individual or legal entity that uses it, serving
as a virtual identity that confers legal validity and aspects of digital security in digital transactions.
This file is used to authenticate Billing API operations (Creation of Workspace(s), records, queries and command of
bank slip instructions) carried out by the client.
It is important to emphasize that Banco Santander has no relationship with these companies and that the list only seeks to illustrate
those that meet the security requirements. Based on the information and characteristics provided below, the customer must acquire a
certificate in order to be able to integrate with our Billing API.

The requirements for the certificates are:

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

• We accept A1 type certificates;
• 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.4 Access Credential

With the certificate registered in the bank's systems (through our Developer Portal) access credentials are
generated, which are composed of two 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;

2023 – 05 V2.0
16
Confidential

Collection Hub– API User Guide

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
(cliente_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 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.

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.

2.6.2 Access Token

To generate an Access Token and make calls to our Billing APIs, follow the steps below:

I. Certificate importation

In Postman, access Settings:

2023 – 05 V2.0
17
Confidential

Collection Hub– API User Guide

Access the tab Certificates and click on Add Certificate:

Fill in the field Host with the desired URL:

trust-sandbox.api.santander.com.br (Sandbox)
trust-open.api.santander.com.br (Production environment)

Import CRT file + KEY file, or PFX + Senha and then, click on Add:

2023 – 05 V2.0
18
Confidential

Collection Hub– API User Guide

II. JWT Generation

In the endpoint POST, enter:

https://trust-sandbox.api.santander.com.br/auth/oauth/v2/token (Sandbox environment)

https://trust-open.api.santander.com.br/auth/oauth/v2/token (Production environment)

Click on the tab body, select x-www-form-urlencoded and complete with the information:

KEY Value
client_id Obtained through the Developer Portal
client_secret Obtained through the Developer Portal
grant_type client_credentials

Note: Pay attention to the information filled in the fields above. There must be no blank spaces before or after the entered
values.

By clicking on Send, the JWT will be generated in the “access_token” field:

III. Including the JWT in the API call

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

Click on the Headers tab and include the header X-Application-Key (client_id):

2023 – 05 V2.0
19
Confidential

Collection Hub– API User Guide

Important! The above step must be performed on all Headers, for each EndPoint consumed.

After these steps, just make calls to the Billing EndPoints, according to the desired action. The process will be the
same for all other EndPoints.
If the 401 error is displayed, generate a new JWT and replace it in the “Authorization” tab, as shown in steps 2 and
3.

2023 – 05 V2.0
20
Confidential

Collection Hub– API User Guide

2.5 API Servers

WORKSPACES
POST and GET: workspace creation and query
Sandbox: https://trust-sandbox.api.santander.com.br/collection_bill_management/v2/workspaces
Production: https://trust-open.api.santander.com.br/collection_bill_management/v2/workspaces/

GET, PATCH and DELETE: workspace query, change and deletion

Sandbox: https://trust-sandbox.api.santander.com.br/collection_bill_management/v2/workspaces/{WORKSPACE_ID}
Production: https://trust-open.api.santander.com.br/collection_bill_management/v2/workspaces/{WORKSPACE_ID}

BANK SLIP
POST and PATCH: registration and alteration of Payment slips
Sandbox: https://trust-sandbox.api.santander.com.br/collection_bill_management/v2/workspaces/{WORKSPACE_ID}/bank_slips
Production: https://trust-open.api.santander.com.br/collection_bill_management/v2/workspaces/{WORKSPACE_ID}/bank_slips

GET (SONDA): Query payment slips registered via API

Sandbox: https://trust-sandbox.api.santander.com.br/collection_bill_management/v2/workspaces/{WORKSPACE_ID}/bank_slips/{BANK_SLIP_ID}
Production: https://trust-open.api.santander.com.br/collection_bill_management/v2/workspaces/{WORKSPACE_ID}/bank_slips/{BANK_SLIP_ID}

POST: PDF Bill Collection generation:

Production: https://trust-open.api.santander.com.br/collection_bill_management/v2/bills/{bankNumber}.{covenantCode}/bank_slips

BILLS
GET - Consult payment slip details registered in the agreement – Our Number:
Sandbox: https://trust-sandbox.api.santander.com.br/collection_bill_management/v2/bills?beneficiaryCode=1234567&bankNumber=1234567890123
Production: https://trust-open.api.santander.com.br/collection_bill_management/v2/bills?beneficiaryCode=1234567&bankNumber=1234567890123

GET – Consult payment slip details registered in the agreement – Your Number:
Sandbox: https://trust-sandbox.api.santander.com.br/collection_bill_management/v2/bills?beneficiaryCode=1234567
&clientNumber=123456789012345&dueDate=2023-01-01&nominalValue=3.45
Production: https://trust-open.api.santander.com.br/collection_bill_management/v2/bills?beneficiaryCode=1234567
&clientNumber=123456789012345&dueDate=2023-01-01&nominalValue=3.45

GET - Query details of a payment slip registered in the agreement, by Type:

Sandbox: https://trust-sandbox.api.santander.com.br/collection_bill_management/v2/bills/{bill_id}?tipoConsulta=default
Production: https://trust-open.api.santander.com.br/collection_bill_management/v2/bills/{bill_id}?tipoConsulta=default

2023 – 05 V2.0
21
Confidential

Collection Hub– API User Guide

2.6 Sandbox
To access the Sandbox, simply login to the Developer Portal, create your application and access your credentials.
With them, you will have access to our development environment, the Sandbox. There you can download our
Collection Postman and integrate the Sandbox directly into your system to explore our APIs.

2.7 Production Environment

To gain access to our production environment and register and query payment slips, you only need to have an
active billing agreement with Santander (with the Online Input parameter enabled). access the Developer Portal
(https://developer.santander.com.br/), register the security certificate and obtain the credentials (Client ID and
Client Secret).
Note: In this environment, tariffs may be applied, if the events (records/instructions) occur in the PRODUCAO
environment/environment, according to the current negotiation. Contact your manager for more information.

2.8 Collection Postman

A Collection is a set of API requests that can be organized and executed together. It includes all the information
needed to make an API call, such as URL/EndPoints, parameters, headers, request body, etc.
Our Collection Postman brings together all of our Token, Workspace and Payment slips related EndPoints and is
available for download from our Developer Portal.
Example of Collection Postman from Billing, after being imported into Postman:

Some data is displayed on our EndPoints between {keys}.

This means that in that section, the Endpoint expects to receive specific information, which may or may not be
variable. In the example above, note that the Endpoint waits for the WORKSPACE_ID information to perform a
query for a specific Workspace.

2023 – 05 V2.0
22
Confidential

Collection Hub– API User Guide

To perform the query, simply enter the expected content and proceed with the operation:

2023 – 05 V2.0
23
Confidential

Collection Hub– API User Guide

SETUP

2023 – 05 V2.0
24
Confidential

Collection Hub– API User Guide

3. Setup Vision

In order to access the system and consume the Billing APIs, one or more Workspaces must be registered.
Workspace is a prerequisite for accessing the Billing Hub via API.

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 (Consultation);

• POST - Used to add/create a record;
• DELETE - Used to remove certain information;
• PATCH - Used to change specific information of a certain record.

3.2 Status HTTP return code

In the HTTP protocol there is also the use of return codes that are standardized for a better
understanding when a request was successful or unsuccessful.
Statuses consist of 3 digits:

• 200 - Successful request

• 400 - Customer information error
• 500 - Server Error, Application is out
And each of them can unfold into more specific ones.:

• 201 - Request successful, resource created

• 204 - The server successfully fulfilled the request and there is no additional content
• 401 - Unauthorized/Authenticated
• 403 - Not Authorized
• 404 - Information not found
• 406 - Target resource does not have a current representation that would be acceptable
• 409 - The request cannot be completed due to a target resource conflict
• 415 - Format not supported by this method on target resource.
• 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.

2023 – 05 V2.0
26
Confidential

Collection Hub– API User Guide

3.3 Workspaces
In the client system environment, the Billing Hub user can make up to 4 (four) types of calls in the
Workspace:

• POST – Creating a Workspace

• GET – Workspace query by ID/Workspace list query
• PATCH – Maintenance of a Workspace
• DELETE – Deletion of a Workspace

2023 – 05 V2.0
27
Confidential

Collection Hub– API User Guide

3.3.1 Workspace Creation

To operate Santander Billing through an API, the company will need to create a Workspace.
In this environment, the Collection agreements to be operated and the settings related to the Webhook (optional)
must be indicated.
The billing agreement(s) indicated in the Workspace must be associated with the same CNPJ root whose credentials
(Client ID and Client Secret) were obtained, after uploading the Security Certificate on our Customer Portal
Developer.

To create a Workspace in the Billing Hub, you need to consume the endpoint POST/workspaces.
Sandbox: https://trust-sandbox.api.santander.com.br/collection_bill_management/v2/workspaces
Production: https://trust-open.api.santander.com.br/collection_bill_management/v2/workspaces/

Request
Field Description Mandatory
Id Unique Workspace identification code in UUID (universally unique No
identifier) format. Field not mandatory, however, if not sent, an
identification code will be automatically generated and will be returned
in the response.
type Workspace classification, the literal “BILLING” must be inserted. Yes

covenants > code List of numerical identification codes for Billing agreements to be Yes
recorded in the Workspace. If the field is sent without identification
codes, the Workspace will be created, but without associated
agreements.
description Workspace description, can be up to 30 characters long. No
webhookURL Destination URL for payment notices No
bankSlipBillingWebhookActive Option used to configure the reception of notices of payments made No
through payment slip (typeable line or Barcode)
pixBillingWebhookActive Option used to configure receipt of notices for payments made via No
QRCode PIX

Workspace Example with Webhook Workspace example without Webhook

{ {
"type": "BILLING", "type": "BILLING",
"description": "Workspace de Cobrança", "description": "Workspace de Cobrança",
"covenants": [ "covenants": [
{ {
"code": "1234567" "code": "1234567"
} }
], ],
"webhookURL": "https://www.suaurl.com.br", }
"bankSlipBillingWebhookActive": true,
"pixBillingWebhookActive": false
}

Important:

2023 – 05 V2.0
28
Confidential

Collection Hub– API User Guide

- To use the payment slips registration API of the Billing HUB, it is mandatory that the agreements to be used for
the registration are previously registered in a Workspace;

- The agreements must compulsorily belong to the same CNPJ root associated with the access credential, obtained
after registering the security certificate in the Developer Portal;

- If an invalid code is sent in the list of agreements or one that does not belong to the CNPJ root associated with the
access credential, the error “10057 – Error when trying to validate the agreements” will be returned;

- If an empty list of agreements is sent, the error “10058 – Agreement is invalid” will be returned.

- Only the first Workspace registered for each agreement will really sensitize the Webhook notification settings in
the Billing agreements (payment by Payment slip | payment by QRCode).

By creating just one Workspace, the company will already be able to carry out its billing operations.

It is possible to associate the same agreement in more than one Workspace, observing the following rules:

Criação Workspace 1

code: 1 code: 2 code: 3

bankSlipBillingWebhookActive: true
pixBillingWebhookActive: true
webhookURL: http://suaurl123.com.br

Action - Creation of the first Workspace for agreements 1, 2 and 3, with the configuration of the Webhook for the URL
http://suaurl123.com.br
Result - Since this is the first Billing API Workspace created for agreements 1, 2 and 3, we will record the settings related to
sending the Webhook for payments via payment slip and payments via QRcode (Bolepix) in the indicated agreements/Codes.

Criação Workspace 2

code: 1 code: 2 code: 3 code: 4

bankSlipBillingWebhookActive: true
pixBillingWebhookActive: false
webhookURL: http://suaurl123abcde.com.br

Action - Creation of a new Workspace, with the indication of the same agreements registered in Workspace 1, with the
addition of the agreement/code 4, indicating another URL for receiving the Webhook (http://suaurl123abcde.com.br) and with
changes in the rules of shipping.
Result - The Workspace will be successfully registered by the API, however the settings related to the notifications
(bankSlipBillingWebhookActive and pixBillingWebhookActive) of this new Workspace will not be changed for agreements 1, 2
and 3. For these, the rules will remain according to the registration of the first Workspace.
For agreement 4, we will record the settings indicated in the agreement.

Summary - For agreements 1, 2 and 3, we will send the payments Webhook to both registered URLs (http://suaurl123.com.br
and http://suaurl123abcde.com.br), both for payments made via Payment slip and via QRCode. (bolepix).
For agreement 4, we will send the Webhook only to the URL http://suaurl123abcde.com.br, and only for payments made via
Payment slip.

2023 – 05 V2.0
29
Confidential

Collection Hub– API User Guide

Response – Status 201 Workspace Created

Field Description Mandatory
id Unique Workspace identification code in UUID (universally unique Yes
identifier) format. Field not mandatory, however, if not sent, an
identification code will be automatically generated and will be
returned in the response.
status The status field returns to indicate whether the Workspace is ATIVO, Yes
INATIVO or SUSPENSO.
type Workspace Rating. Yes
convenants > code List of numerical identification codes for Billing agreements to be Yes
recorded in the Workspace. If the field is sent without identification
codes, the Workspace will be created, but without associated
agreements.
description Workspace description. No
webhookURL Destination URL for payment notices No
bankSlipBillingWebhookActive Current configuration of receipt of payment notices made through No
payment slip (Digitable Line or Barcode)
pixBillingWebhookActive Current configuration of receipt of payment notices made via No
QRCode PIX

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 3339, ISO Yes
8601 standard.
_traceId Trace id is the unique identifier among all calls where we trace all Yes
transactions.
_errors The _errors field has additional information about the error: No
▪ _code – specific error code;
▪ _field – Error field identification with up to 50 characters;
▪ _message* – error message description up to 100 characters.

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

2023 – 05 V2.0
30
Confidential

Collection Hub– API User Guide

3.3.2 Workspace List Query

To make the Workspaces paged/list query, it is necessary to consume the endpoint GET/workspaces. In this API
there are two main fields: _pageable* dealing with pagination and _content* that brings the Workspace data.

Sandbox: https://trust-sandbox.api.santander.com.br/collection_bill_management/v2/workspaces
Production: https://trust-open.api.santander.com.br/collection_bill_management/v2/workspaces/

Response – Status 200 Consulta Lista de Workspace

Field Description Mandatory
_limit It is the maximum total that each page will bring in the query, with a Yes
minimum of 1 (one) Workspace and a maximum of 50 (fifty)
Workspaces per page.
_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 field _content* brings all the Workspace data mentioned above: workspace_id, creationDate*, status, type*,
description, covenants. The Status Code Bad Request follows the same error pattern presented above and for the
other status codes it also follows the same pattern.

To navigate between the pages obtained in the search result, just add a Query Param (in Postman's Params tab)
called _page, with the value of the desired page. Ex. Key = _page Value = 2
To bring a larger number of results per page, use the Query Param _limit, indicating the desired number as in the
Value field.

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 3339, ISO Yes
8601 standard.
_traceId Trace id is the unique identifier among all calls where we trace all Yes
transactions.
_errors The _errors field has additional information about the error: No
▪ _code – specific error code;
▪ _field – Error field identification with up to 50 characters;
▪ _message* – error message description up to 100 characters.

2023 – 05 V2.0
31
Confidential

Collection Hub– API User Guide

3.3.3 Workspace Unit Query

To do a Workspace unitary query, you need to consume the endpoint GET/workspaces/{WORKSPACE_ID}.

WORKSPACES | GET, PATCH and DELETE:

Sandbox: https://trust-sandbox.api.santander.com.br/collection_bill_management/v2/workspaces/{WORKSPACE_ID}
Production: https://trust-open.api.santander.com.br/collection_bill_management/v2/workspaces/{WORKSPACE_ID}

Response – Status 200 Consulta Workspace Id

Field Description Mandatory
id The Id field is unique to the client in the Workspace created and Yes
follows the UUID v4 standard of RFC 4122.
status The status field returns to indicate whether the Workspace is ATIVO, Yes
INATIVO or SUSPENSO.
type Workspace Rating. Yes
covenants List of numerical identification codes for Collection agreements. Yes

description Workspace description. No

creationDate Workspace creation date. Yes
tags Workspace identification tag. No

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

3.3.4 Workspace Maintenance

To maintain/update the Workspace, it is necessary to consume the endpoint PATCH/workspaces/{WORKSPACE_ID}.

WORKSPACES | GET, PATCH and DELETE:

Sandbox: https://trust-sandbox.api.santander.com.br/collection_bill_management/v2/workspaces/{WORKSPACE_ID}
Production: https://trust-open.api.santander.com.br/collection_bill_management/v2/workspaces/{WORKSPACE_ID}

Request
Field Description Mandatory
covenants List of numerical identification codes for Collection agreements. Yes

description Workspace description and can be up to 30 characters long No

3.3.5 Deleting a Workspace

To delete a Workspace it is necessary to consume the DELETE/workspaces/{WORKSPACE_ID} endpoint.

Just send the {workspace_id} and the response will return Status Code 204 Resource Deleted.

2023 – 05 V2.0
32
Confidential

Collection Hub– API User Guide

TRANSACTION

2023 – 05 V2.0
33
Confidential

Collection Hub– API User Guide

4. Transaction

After registering with Workspace, the customer will be able to call the transactions available in the Billing Hub.
The transaction flow basically occurs through three methods: POST, PATCH and GET. POST is used to register
payment slips. PATCH is used to command instructions to payment slips, changing/updating their data. GET is
used to query payment slips registered in up to D+2 of the registry (Probe Consultation, where it is possible to
consult all registered data of a payment slip) and also to consult the status and other data of registered,
settled and downloaded in the agreement.

4.1BANK SLIP - POST

To start recording a payment slip, it is necessary to call the POST endpoint, having the following input and
output fields:

Sandbox: https://trust-sandbox.api.santander.com.br/collection_bill_management/v2/workspaces/{WORKSPACE_ID}/bank_slips
Production: https://trust-open.api.santander.com.br/collection_bill_management/v2/workspaces/{WORKSPACE_ID}/bank_slips

Request
Field Description Mandatory Format/Content Notes
Unique sequential number
nsuCode per Agreement/Date Yes X(20) 1

nsuDate Date of generated NSU Yes YYYY-MM-DD 2

Environment for processing Yes
environment TESTE/PRODUCAO 3
payment slip registration
Identification code of the Yes
agreement in which the
covenantCode 9(09) 4
payment slip must be
registered
Original payer document type Yes
payer/documentType CPF/CNPJ 5
of the payment slip
Original payer document Yes
payer/documentNumber 9(15) 6
number of the payment slip
Full name or corporate name Yes
payer/name of the original payer of the X(40) -
payment slip
Address of the original payer Yes
payer/address X(40) -
of the payment slip
Neighborhood of the original Yes
payer/neighborhood X(30) -
payer of the payment slip

2023 – 05 V2.0
40
Confidential

Collection Hub– API User Guide

City of the original payer of Yes

payer/city X(20) -
the payment slip
UF of the original payer of the Yes
payer/state X(02) -
payment slip
CEP of the original payer of Yes
payer/zipCode 9(08) -
the payment slip
Payment slip final beneficiary
beneficiary/documentType No CPF/CNPJ 7
document type
Document number of the
beneficiary/documentNumber final beneficiary of the No 9(15) 7
payment slip
Full name or corporate name
beneficiary/name of the final beneficiary of the No X(40) 7
payment slip
bankNumber Our number Yes 9(13) 8
clientNumber Your number No X(15) 9
dueDate Payment slip due date Yes YYYY-MM-DD -
issueDate Payment slip issuance date Yes YYYY-MM-DD -
participantCode participant control No X(25) 10
Nominal value of the
nominalValue Yes 9(13)V99 -
payment slip
Type of payment slip
documentKind Yes note 11 11
document
Type of discount to be
discount/type No note 12 12
granted for the payment slip
Value of the first discount to
discountOne/value be granted for the payment No 9(13)V99 12
slip
Deadline for the first discount
discountOne/limitDate to be granted for the No YYYY-MM-DD 12
payment slip
Value of the second discount
discountTwo/value to be granted for the No 9(13)V99 12
payment slip

2023 – 05 V2.0
41
Confidential

Collection Hub– API User Guide

Deadline for the second

discountTwo/limitDate discount to be granted for the No YYYY-MM-DD 12
payment slip
Value of the third discount to
discountThree/value be granted for the payment No 9(13)V99 12
slip
Deadline for the third
discountThree/limitDate discount to be granted for the No YYYY-MM-DD 12
payment slip
Percentage of fine per month
finePercentage No 9(03)V99 -
to be applied for payment slip
Number of days after the
expiration of the payment slip
fineQuantityDays No 9(02) -
in which the fine must start to
be applied
Percentage of interest per
interestPercentage month to be applied to the No 9(03)V99 -
payment slip
Amount of rebate to be
deductionValue No 9(13)V99 -
granted for the payment slip
protestType type of protest No note 13 13
Number of days to issue a
protestQuatityDays protest after the due date of No 9(02) 13
the payment slip
Number of days for a
writeOffQuantityDays payment slip to be written off No 9(02) 14
after the due date
paymentType Payment slip payment type Yes note 15 15
Number of partials to be
attributed to the payment slip
parcelsQuantity No 9(02) 16
in case of “Partial” payment
type

2023 – 05 V2.0
42
Confidential

Collection Hub– API User Guide

Type of amount to be defined

for minimum and maximum
for payment, in case of

valueType payment type “Divergente” No note 17 17

or “Par”

Minimum amount or
9(10)V99999
minValueOrPercentage percentage for payment slip No 18
payment
Maximum value or
9(10)V99999
maxValueOrPercentage percentage for payment slip No 19
payment
Percentage of IOF to be
iofPercentage collected in the payment slip No 9(03)V99999 20
settlement
Sharing code registered in the
sharing/code Beneficiary's agreement, No 21
X(02)
indicates the current account
that will receive the credit
sharing/value Amount that will be shared No 9(13)V99 22
per account
Type of DICT key (PIX) to be
key/type No Note 23 23
linked to the payment slip
DICT key (PIX) to be linked to
key/dictKey No X(77) 24
the payment slip

txId QR Code Identification Code No 25

X(35)
(TXID)
messages Messages to be included in No 26
X(100)
the payment slip

In the output area, all fields sent in the input and the following additional fields will be returned:
Response – Status 200
Field Description
barCode Barcode generated for the payment slip
digitableLine Digital line generated for payment slip
entryDate Date of entry/registration of the payment slip at the Bank
qrCodePix QRCode PIX code assigned to the payment slip
qrCodeUrl QRCode PIX URL assigned to the payment slip

Note: The “qrCodePix” and “qrCodeUrl” fields will only be returned if the Payment slip SX (PIX).

2023 – 05 V2.0
43
Confidential

Collection Hub– API User Guide

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

▪ 400 - Customer information error

▪ 401 - Unauthorized/Authenticated
▪ 403 - Not Authorized
▪ 404 - Information not found
▪ 406 - The target resource does not have a current representation that would be acceptable
▪ 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 the error occurs, following the RFC 3339, ISO 8601 Yes
standard
_traceId Trace id is the unique identifier among all calls where we trace all Yes
transactions
_errors The _errors field has additional information about the error: No
▪ _code – Specific error code;
▪ _field – Error field identification with up to 50 characters;
▪ _message* – error message description up to 100 characters.

2023 – 05 V2.0
44
Confidential

Collection Hub– API User Guide

4.2BANK SLIP - GET (Sonda)

To start querying a payment slip, it is necessary to call the endpoint GET:

Sandbox: https://trust-sandbox.api.santander.com.br/collection_bill_management/v2/workspaces/{WORKSPACE_ID}/bank_slips/{BANK_SLIP_ID}
Production: https://trust-open.api.santander.com.br/collection_bill_management/v2/workspaces/{WORKSPACE_ID}/bank_slips/{BANK_SLIP_ID}

The following fields must be indicated in the {BANK_SLIP_ID}, separated by a dot:

Request
Field Description Mandatory Format/Content Notes
Unique sequential number
nsuCode per Agreement/Date Yes X(20) 1

nsuDate Date of generated NSU Yes YYYY-MM-DD 2

Environment for processing
environment Yes TESTE/PRODUCAO 3
payment slip registration
Identification code of the
agreement in which the
covenantCode Yes 9(09) 4
payment slip must be
registered
bankNumber Our number Yes 9(13) 16

Example:

https://trust.open.api.santander.com.br/collection_bill_management/v2/workspaces/78b8d614-ec19-4b16-
9f91-cdb63d329123/bank_slips/123.2022-09-16.P.123456.123

This query is intended to confirm the payment slip registration and can be carried out within D+2 of the date
on which the payment slip was registered with the Bank, once the payment slip registration is located, all
payment slip data will be returned (The GET response is the same as the registration POST).

2023 – 05 V2.0
45
Confidential

Collection Hub– API User Guide

4.3 BILLS - GET – Payment slips inquiry

BILLS – GET - Query simple detail of a payment slip – Our Number:

Sandbox: https://trust-
sandbox.api.santander.com.br/collection_bill_management/v2/bills?beneficiaryCode=1234567&bankNumber=1234567890123

Production: https://trust-
open.api.santander.com.br/collection_bill_management/v2/bills?beneficiaryCode=1234567&bankNumber=1234567890123

BILLS – GET - Query simple detail of a payment slip – Your Number:

Sandbox: https://trust-sandbox.api.santander.com.br/collection_bill_management/v2/bills?beneficiaryCode=1234567
&clientNumber=123456789012345&dueDate=2023-01-01&nominalValue=1234567890123.45

Production: https://trust-open.api.santander.com.br/collection_bill_management/v2/bills?beneficiaryCode=1234567
&clientNumber=123456789012345&dueDate=2023-01-01&nominalValue=1234567890123.45

BILLS – GET - Query details of a payment slip by query type:

Sandbox: https://trust-sandbox.api.santander.com.br/collection_bill_management/v2/bills/{bill_id}?tipoConsulta=default

Production: https://trust-open.api.santander.com.br/collection_bill_management/v2/bills/{bill_id}?tipoConsulta=default

Query simple detail of a billing payment slip – Our Number (GET): used to query the simple detail of a
payment slip using the information from the beneficiary's health insurance code and our payment slip
number.

Query simple detail of a collection payment slip – Your Number (GET): used to query the simple detail
of a payment slip using information from the beneficiary's health insurance code, its payment slip
number, payment slip expiration date and payment slip face value.

Query details of a payment slip by query type (GET): used to query details of a payment slip through
the beneficiary's health insurance code and our payment slip number by type:
1. Default
2. Duplicate
3. Bankslip
4. Write-Offs/Settlements
5. Registry

2023 – 05 V2.0
46
Confidential

Collection Hub– API User Guide

To perform a simple query by Your Number/Our Number using Postman, follow these steps:
1. Open Postman.
2. Select the GET method and enter the EndPoint URL.

- To query the details of a payment slip using our number, you must send the following query
parameters:
beneficiaryCode: Beneficiary agreement code
bankNumber: Code Our Payment slip number

- To query the detail of a payment slip by its number, it is necessary to send the following query
parameters:
beneficiaryCode: Beneficiary agreement code
clientNumber: Code Your Payment slip number
dueDate: Payment slip due date (Format YYYY-MM-DD)
nominalValue: Nominal Value of the Payment slip (With two decimal places separated by a dot ‘.’)

3. In the “Authorization” tab, select the “OAuth 2.0” type. In the “Token” field, enter the obtained token.
4. In the ”Headers” tab, add the header “X-Application-Key” assigning the same value used in the
client_id.
5. Finally, click on “Send” to get the answer.

Figure 6. Example query for our number using Postman.

2023 – 05 V2.0
47
Confidential

Collection Hub– API User Guide

Figure 7. Example query by your number using Postman.

To perform a query by TYPE using Postman, follow these steps::

1. Open Postman.
2. 2. Select the GET method and enter the EndPoint URL.
To query the details of a payment slip by type of query, you must send the following data:
bill_id (Path Parameter): Payment slip search key containing Beneficiary agreement code and Our Number,
separated by dot “.” Example: 3554899.2022318

tipoConsulta (Query Parameter): Type of query to be carried out.

Non-mandatory data. If not informed, the default API return (Default type) will be defined. allowed values:
1. default: Standard search, bringing only basic payment slip data
2. duplicate: Data search for issue of duplicate payment slip
3. bankslip: Search for complete payment slip data
4. settlement: Search for payment slip write-off/settlement information
5. registry: Registry information search in the payment slip

3. On the “Authorization” tab, select the “OAuth 2.0” type. In the “Token” field, enter the token
obtained.

4. In the ”Headers” tab, add the header “X-Application-Key” assigning the same value used in the
client_id of the token generation in section 4.

5. Finally click Send to get the answer.

2023 – 05 V2.0
48
Confidential

Collection Hub– API User Guide

Figure 10. Example of default call (Default).

Object “_pageable”

Contains information to identify if there are more records to query and will be returned when the query is
performed by Your Number/Our Number. It has the following properties:
“_moreElements”: Indicates if there are more records from the current “page”, returns the value “true” if there is and
“false” if not.

Object “_content”: It will indicate the payment slip information located:

Figure 11. Example of object “_content”.

List of possible statuses in the payment slips status query:
▪ ATIVO (active)
▪ BAIXADO (write-off)
▪ LIQUIDADO (paid)
▪ LIQUIDADO PARCIALMENTE (partially paid)

2023 – 05 V2.0
49
Confidential

Collection Hub– API User Guide

Status Details:

ATIVO (ACTIVE)

The Active status will be displayed when querying:

- Open invoices (unpaid), which are active in the Billing base, overdue or due;
- Bills that were paid via digital line or barcode on the same day of the appointment.

For payments made on the same day using a digital line or barcode, there will be an indication of an “baixa operacional
supplement on the GET routes by Nosso Número and by Seu número.

The next day, the paid invoice will show the status Settled or Partially Settled.

BAIXADO (WRITE-OFF)

The BAIXADO status will be displayed when querying:

- Bills write-off (canceled) according to instructions registered at the time of transfer, configured in the Billing
Agreement or after protest;
- Bills paid via PIX QRCode (Bolepix).

When payment is made using the PIX QRCode (Bolepix), the invoice will be write-off (canceled) immediately.

Through the GET query Endpoints by Nosso Número, Seu Número and Settlement, it is possible to consult additional
information on the status of the bills.
For the Downloaded status, there will be an indication whether the Write-Off occurred due to payment via PIX,
Automatic Write-Off, Write-Off as instructed, etc.

LIQUIDADO (PAID)

The Settled status will be displayed when checking invoices that have been paid via digital line or barcode (full
settlement of the invoice amount) in the previous days. This status will only be displayed from
D+1 of payment.

LIQUIDADO PARCIALMENTE (PARTIALLY PAID)

The Partially Settled status will be displayed when checking invoices that have been paid via digital line or barcode
(partial settlement of the invoice value) in the previous days. This status will only be displayed after D+1 of payment.

Note:
After being BAIXADO or LIQUIDADO, the invoices remain available for consultation in our database according to the
deadlines below:

BAIXADO invoices are eliminated from the active consultation base after 15 to 30 days of cancellation.
LIQUIDADO invoices are eliminated from the consultation database after 30 to 45 days of settlement.

2023 – 05 V2.0
50
Confidential

Collection Hub– API User Guide

4.4 BANK SLIP - PATCH

To change payment slip data, it is necessary to call the PATCH endpoint with the following input and output
fields:

Sandbox: https://trust-sandbox.api.santander.com.br/collection_bill_management/v2/workspaces/{WORKSPACE_ID}/bank_slips
Production: https://trust-open.api.santander.com.br/collection_bill_management/v2/workspaces/{WORKSPACE_ID}/bank_slips

Request
Field Description Format/Content Notes
Change Maturity
dueDate YYYY-MM-DD 29

nominalValue Change Nominal Value 9(13)V99 30

PROTEST PROTESTAR
operation CANCEL_PROTEST CANCELAR_PROTESTO 31
WRITE-OFF BAIXAR

protestQuatityDays Change Number of Protest Days 9(02) 32

deductionValue Grant/Cancel/Change Rebate 9(13)V99 33

discountOne/value 9(13)V99
Grant/Cancel/Change 1st Discount 34
discountOne/limitDate YYYY-MM-DD
discountTwo/value 9(13)V99
Grant/Cancel/Change 2nd Discount 34
discountTwo/limitDate YYYY-MM-DD
discountThree/value 9(13)V99
Grant/Cancel/Change 3rd Discount 34
discountThree/limitDate YYYY-MM-DD
discountOne/value Grant/Cancel/Change Advance Discount Calendar 9(13)V99
35
discountOne/limitDate Days YYYY-MM-DD
discountOne/value Grant/Cancel/Change Business Day Advance 9(13)V99
35
discountOne/limitDate Discount YYYY-MM-DD
finePercentage 9(03)V99
Charge/Cancel/Change Late Fee 36
fineDate YYYY-MM-DD
Charge/Cancel/Change Interest per month due to
interestPercentage 9(03)V99 37
Delay
interestValue 9(03)V99
Grant/Cancel/Change Interest Tolerance 38
interestToleranceDate YYYY-MM-DD
minValueOrPercentage Change Minimum Percentage for Payment 9(10)V99999 39
maxValueOrPercentage Change Maximum Percentage for Payment 9(10)V99999 39
minValueOrPercentage Change Minimum Amount for Payment 9(13)V99 40
maxValueOrPercentage Change Maximum Payment Amount 9(13)V99 40

2023 – 05 V2.0
51
Confidential

Collection Hub– API User Guide

Number of days for a payment slip to be written off

writeOffQuantityDays 9(02) 41
after the due date
clientNumber Add/Delete/Change Your Number X(15) 42
participantCode Add/Delete/Change Participant Control X(25) 43

General Rules

Up to 10 instructions for the same payment slip may be sent in the same request, with the exception
of write-off, protest and protest cancellation instructions that need to be sent separately.
In the request, the number of the agreement (covenantCode) and our number (bankNumber) of the
payment slip must be informed and only the fields of the instructions that must be processed, according to
the table above.

In the exit area, the data of the Agreement, Our number and result will be returned:

Response – Status 200

Field Description
covenantCode Agreement number
bankNumber Our payment slip number
message Example: "Successfully made the change"

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

▪ 400 - Customer information error

▪ 401 - Not Authorized/Authenticated
▪ 403 - Not Authorized
▪ 404 - Information not found
▪ 406 - The target resource does not have a current representation that would be acceptable
▪ 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 the error occurs, following the RFC 3339, ISO 8601 Yes
standard
_traceId Trace id is the unique identifier among all calls where we trace all Yes
transactions
_errors The _errors field has additional information about the error: No
▪ _code – specific error code;
▪ _field – Error field identification with up to 50 characters;
▪ _message* – error message description up to 100 characters.

2023 – 05 V2.0
52
Confidential

Collection Hub– API User Guide

The following instructions are available in the Billing API:

Financial Instructions:
Grant/Change/Cancel Rebate
Grant/Change/Cancel 1st Discount
Grant/Change/Cancel 2nd Discount
Grant/Change/Cancel 3rd Discount
Grant/Change/Cancel Advance Discount on Calendar Days
Grant/Change/Cancel Advance Discount on Business Days
Charge/Change/Cancel Late Fee
Charge/Change/Cancel Interest per Month
Change Minimum Percentage for Payment
Change Maximum Percentage for Payment
Change Minimum Amount for Payment
Change Maximum Amount for Payment
Change Nominal Value (only for BCC and BDP document types)
Grant/Change/Cancel Interest Tolerance

Change Instructions:
Maturity Change
Change Number of Protest Days
Change the number of days off
Add/Change Your Number
Add/Change Participant Control

Protest Instructions:
Protest
Cancel Protest (Do not Protest, Stop and Cancel Protested Title)

Download Instructions:
Write-off

Details
- All instructions commanded via API through Patch are processed online at Santander and at PCR (Centralized
Receivables Platform), if accepted.

- Write-off and Maturity Extension Instructions commanded for invoices linked to the guarantee (Penhor) operation
(Pledge Collection) undergo internal validation, in hourly schedules (from 9:35 am to 6:35 pm).
If the statement is processed after the last grid time, it will be updated in nightly processing.

- Every instruction commanded for the bills and accepted by the Bank will be automatically reflected in the PIX QRCode,
if your bill is a Boleto SX/Bolepix.

- It is allowed to command instructions for bills that have been issued through any Santander channel (Internet Banking,
APP Empresas, CNAB, XML or API).

2023 – 05 V2.0
53
Confidential

Collection Hub– API User Guide

4.5 WEBHOOK
Webhooks create a kind of connection between two systems, so that one system can receive information from the
other as soon as a certain action takes place.
The purpose of the Cobrança Webhook is to provide customers with a notice of payment slips paid, containing essential
data on these payment slips and payments, so that it is possible to reconcile the settlements made.

This notice will be sent to the customer through a Push Notification and immediately. That is, as soon as a payment is
made (either through the typed line/bar code or through the Bolepix QRCode associated with the payment slip), a
notification will be sent.

Customers who choose to receive payment notices through the Webhook must configure this in the Billing Workspace,
informing the URL to which the notification should be directed and the type of transaction that should be sent:

- URL (webhookURL): http://cliente.com.br

- Payment of Payment slips (bankSlipBillingWebhookActive): true
- Payment by PIX (pixBillingWebhookActive): true or false

The fields will apply to all agreements registered in the Workspace list. That is, all agreements will receive payment
notices through the Webhook;

If the customer does not want to receive a Webhook for one or more agreements on the list, they must exclude them
from the Workspace and include them in a separate Workspace, without configuring a Webhook.

The customer can have several Workspaces with the same agreements, if he wants to enable Webhook for the same
agreement in different Workspaces, he must inform the same configuration, changing only the URL, if he/she wants.

Webhook – Notice
Field Description Format Size Domain
message Message code alphanumeric 12 WBHKPAGEST
PAGAMENTO
function Function* alphanumeric 15
ESTORNO
Payment type SANTANDER
paymentType alphanumeric 20 OUTROS BANCOS
PIX
issueDate Issuance Notification Date alphanumeric 10 YYYY-MM-DD
Date Time of YYYY-MM-DD-
paymentDate alphanumeric 26
payment/operational write-off HH.MM.SS.NNNNNN
Payment bank/operational
bankCode numeric 4
write-off (code COMPE)
AGENCIAS
AUTO_ATENDIMENTO
INTERNET BANKING
CORRESPONDENTE
Payment channel BANCARIO FISICO
paymentChannel alphanumeric 40
CENTRAL DE ATENDIMENTO
ARQUIVO ELETRONICO
DDA
CORRESPONDENTE
BANCARIO DIGITAL

2023 – 05 V2.0
54
Confidential

Collection Hub– API User Guide

ESPECIE
Means of payment DEBITO EM CONTA
paymentKind alphanumeric 30
CARTAO DE CREDITO
CHEQUE
covenant Agreement Code numeric 9
TP Contract person CPF
typeOfPersonAgreement alphanumeric 4
CNPJ
agreementDocument Document number numeric 14
bankNumber Our number numeric 13
clientNumber Your number alphanumeric 15
participantCode Participant Control alphanumeric 25
txId TXID - code. PIX tracking alphanumeric 35
TP Original Payer Person CPF
payerDocumentType alphanumeric 4
CNPJ
payerDocumentNumber Original Paying Document numeric 15
payerName Original Paying Name alphanumeric 40
TP Person Final Beneficiary CPF
finalBeneficiaryrDocumentType alphanumeric 4
CNPJ
finalBeneficiaryDocumentNumber Final Beneficiary Document numeric 15
finalBeneficiaryName Final Beneficiary Name alphanumeric 40
dueDate Due date alphanumeric 10 YYYY-MM-DD
nominalValue Nominal value numeric 15,2
payedValue Amount paid numeric 15,2
interestValue Interest calculated on payment numeric 15,2
fine Fine calculated on payment numeric 15,2
deductionValue Amount of discount granted numeric 15,2
rebateValue Amount of Rebate granted numeric 15,2
iofValue Collected IOF amount numeric 15,2

Important:
Customers who choose to receive payment notifications through the Webhook must carry out this configuration in the
Billing Workspace, providing the URL to receive notifications.

The settings will apply to all agreements registered in the Workspace list.
If the customer does not want to receive Webhook for one or more agreements on the list, they must exclude them
from the Workspace and include them in a separate Workspace, without Webhook configuration.

Customers covered by Circular 3,978/2020 have a Webhook with a composition different from that indicated above.
For more details, consult your Cash Specialist.

Webhook notifications for payments made at Santander (except through the Caixa and Corban channels) and at other
banks through the Digitible Line and Bar Code represent effective confirmation of payment of the invoices, without the
possibility of a refund.
For the Caixa and Corban Santander channels, it will be possible to cancel the payment of invoices on the same day of
payment. If a chargeback occurs, a chargeback (estorno) Webhook will be sent to the company.

Webhook notifications for payments made using PIX QRCode (Bolepix) represent effective confirmation of payment of
the bill. In other words, the payment was identified and the invoice was downloaded immediately.

2023 – 05 V2.0
55
Confidential

Collection Hub– API User Guide

Receiving more than one Webhook notification with the PAYMENT “function” for the same bill will not necessarily mean
that there has been more than one payment for this bill.
In other cases, it is possible that the lack of response from the company's server confirming the successful reception of
our notification triggers new attempts on the Bank's side to send this notification.

We recommend that payment reconciliation is always complemented with detailed inquiry routes (GET), and/or through
our return files. It is important to have redundancy in conciliation methods. Notices related to payments made by
QRCode (Boleto SX/BolePix) can now be considered definitive when received.

The company's side must implement good practices related to URL settings:

• Make sure it is online, active and properly categorized at CISCO;

• URL must be https;
• URL with up to 350 characters;
• Allowed composition: "^https://[-a-zA-Z0-9@:%._\\\\+~#=/$¨&*()]{1,342}$"
• Release of ports 443 and 80;
• URL is able to receive POST with empty or filled body/header;
• URL is able to receive POST with CONTENT_TYPE application/json;
• Send an appropriate HTTP response to the Webhook sender, such as a 200 (OK) status code, to indicate that the
receipt was successful. Sending must be carried out immediately after receiving the message.
• Dealing with duplicate notifications;

Webhook example:

{
"message": "WBHKPAGEST",
"function": "PAGAMENTO",
"paymentType": "SANTANDER",
"issueDate": "2023-05-22",
"paymentDate": "2023-05-22-14.24.35.068123",
"bankCode": "0033",
"paymentChannel": "INTERNET BANKING",
"paymentKind": "DEBITO EM CONTA",
"covenant": "001234567",
"typeOfPersonAgreement": "CNPJ",
"agreementDocument": "12345678000134",
"bankNumber": "0000000001025",
"clientNumber": "123",
"participantCode": "exemplo webhook",
"txId": "",
"payerDocumentType": "CPF",

2023 – 05 V2.0
56
Confidential

Collection Hub– API User Guide

"payerDocumentNumber": "12345678901",
"payerName": "Joao da Silva",
"finalBeneficiaryrDocumentType": "",
"finalBeneficiaryDocumentNumber": "",
"finalBeneficiaryName": "",
"dueDate": "2023-05-22",
"nominalValue": 5,
"payedValue": 4.4,
"interestValue": 0,
"fine": 0,
"deductionValue": 0.5,
"rebateValue": 0.1,
"iofValue": 0
}

2023 – 05 V2.0
57
Confidential

Collection Hub– API User Guide

4.6 PDF Bill Collection Generation

To start generating and downloading a PDF invoice image, you must call the POST endpoint:
Production: https://trust-open.api.santander.com.br/collection_bill_management/v2/bills/{bill_id}/bank_slips

Available to generate invoices issued using any method (Internet Banking, APP Empresas, CNAB, XML and API) and any
type (Conventional and Boleto PIX), in PDF. To do this, it is enough that the bill is active and open at the bank's
database. Image generation is individual.

This is an independent service from the bill registration API. Therefore, access to the PDF is carried out in a separate call,
by indicating the following variables:

- At Endpoint: bill_id, composed of Our Number.Agreement or Typeable Line

- In the body: Document (CPF/CNPJ) of the Payer

Important: It will not be possible to expose the link to the end customer.
The Beneficiary must download the PDF from the link provided by the service (download will be available for 5 minutes).
After this period, the beneficiary will be able to make a new call to the Endpoint to obtain a new link.

Request: body
Field Description Mandatory
payerDocumentNumber Payer document (CPF/CNPJ) Sim

Response – Status 200

field Description Mandarory
link Link to download de PDF Yes

2023 – 05 V2.0
58
Confidential

Collection Hub– API User Guide

Notes

2023 – 05 V2.0
59
Confidential

Collection Hub– API User Guide

5. Notes – POST (Payment slips Registration)

Note 1: NSU (nsuCode):

Identification number of the call/operation informed by the Beneficiary in the POST and also used in
the GET as a key for consulting the payment slip.

The NSU must be unique (must not be repeated) per date/agreement.

• When the environment (environment) for processing is test "TESTE", the literal "TST" must be
informed in the first 3 positions, plus the numbering of the NSU.

In the GET (SONDA) the same NSU used in the POST to register the payment slip must be sent.

Note 2: NSU Date (nsuDate):

It is the date of sending the NSU in the payment slip record.

Note 3: Environment:

The following domains must be sent, according to the processing environment for the registration of
the payment slip:

• PRODUCAO (production): Indicates that the payment slip must be registered normally with
the Bank
• TESTE (Test): Indicates that the request is being sent for testing purposes only, the payment
slip will not be registered with the Bank.

Note 4: Covenant Code (covenantCode):

Numeric identification code of the agreement in which the payment slip must be registered, the
agreement must belong to the same root as the CNPJ authenticated in the Token for the POST/GET
call and must be previously registered in the Workspace.

Note 5: Type of Document - Payer and Final Beneficiary (documentType):

Field that will indicate the type of document that will be informed to the payer and the final
beneficiary. The consistency of the type of document is carried out against the number of the
informed document, if the verifying digit of the document is invalid, the registration of the payment slip
will be rejected.
Inform:

o CPF
o CNPJ

2023 – 05 V2.0
60
Confidential

Collection Hub– API User Guide

Note 6: Payer's CPF/CNPJ (payer/documentNumber):

The Original Payer is the Individual or Legal Entity that will receive the payment slip, it is the debtor of
the debt and has signed the commercial commitment with the Original Beneficiary (payment slip
issuer).

The payer's document number is mandatory for registration of the payment slip, it is a numerical field,
which must be filled in with 11 characters when CPF and 14 characters when CNPJ, including zeros
on the left.

The Payer's document number cannot be the same as that of the Original Beneficiary or Final
Beneficiary, in the case of a legal entity the CNPJ root cannot be the same either, except for payment
slips of the type of document “Deposit and Contribution Payment slip”.

Note 7: Final Beneficiary (beneficiary):

Final Beneficiary is the recipient of the resource, in cases of collection agreement with third parties or
the holder of the deposit account or prepaid account recipient of the deposit or contribution.

Mandatory information when:

• In the case of payment slip negotiated with third parties;

• Payment slips whose final recipient of funds is different from the original beneficiary;
• Payment slips for deposit and contribution.

In compliance with BACEN Circular nº 3956/19, in order to enable its customers to issue the payment
slip when using the Santander Billing Agreement, it is mandatory to inform the Final Beneficiary data*
(Document and Name) in the registration and issuance of the payment slip, and the document
number entered for the beneficiary cannot be the same as the document number of the original
beneficiary (in the case of a legal entity, the CNPJ root cannot be the same either).

In case the payment slip falls under any of the above rules, it is mandatory to inform:

• Final Beneficiary document type (documentType):

o CPF
o CNPJ
• Document number (documentNumber)
• • Full name or Company name (name)

Note 8: Our Number/Nosso Número (bankNumber):

2023 – 05 V2.0
61
Confidential

Collection Hub– API User Guide

Numerical code of up to 13 positions, to identify the payment slip at the Bank. Mandatory information
for registration of the payment slip.

Note 9: Your Number/Seu Número (clientNumber):

Alphanumeric code of up to 15 positions, to identify the payment slip at the Company. Non-
mandatory information for payment slip registration.

Note 10: Participant Control Identification (participantCode):

Up to 25 characters alphanumeric field, optional for registration.

For customers who also use the CNAB, if informed, it will be returned in the return file, when the
payment slip is settled, facilitating reconciliation.

Note 11: Document Kind (documentKind):

Characterizes the origin of the commercial relationship between Beneficiary and Payer that originated
the registration of the collection payment slip. It must be informed in the payment slip record as
below:

DUPLICATA_MERCANTIL
DUPLICATA_SERVICO
NOTA_PROMISSORIA
NOTA_PROMISSORIA_RURAL
RECIBO
APOLICE_SEGURO
BOLETO_CARTAO_CREDITO
BOLETO_PROPOSTA
BOLETO_DEPOSITO_APORTE
CHEQUE
NOTA_PROMISSORIA_DIRETA
OUTROS

Specific Rules:

• Credit Card Payment Slip:

o The partial payment option is the default with up to 99 partial payments, allowing the
payment of any amount. The Beneficiary must deal with the partial settlement of the
payment slip;
o In order for the Credit Card payment slip to be written off, the Beneficiary must execute
the command to write off the payment slip when the next invoice is issued;
o The Beneficiary must register each credit card payment slip with a different Our

2023 – 05 V2.0
62
Confidential

Collection Hub– API User Guide

Number, always adding/deducting the remaining balance from the previous invoice. If
the Beneficiary does not have a new invoice to issue to the payer, it is recommended
that the latter leave the payment slip for the previous month open.
o No, fine, interest, discount, deduction, protest and negative payment slip instructions
are allowed and, if sent, they will be disregarded in the payment slip registration.

• Proposal Payment slip:

o The divergent payment option is default, allowing the payment of any amount. The
beneficiary must deal with the settlement for any amount in the payment slip;
o No, fine, interest, discount, deduction, protest and negative payment slip instructions
are allowed and, if sent, they will be disregarded in the payment slip registration.
• Deposit and Contribution Payment slip:
o The purpose of the Deposit and Contribution payment slip is to use the payment slip to
make a deposit into a current account or payment account. In this kind of document:
▪ Original Beneficiary: Company that contracted the collection service with the
bank, or company authorized to enable Final Beneficiaries.
▪ Payer: Holder of the current account or payment account that will receive the
financial resource.
▪ Final Beneficiary: Final recipient of the financial resources of the payment slip.
For this type, the payer must be the same as the final beneficiary.
o Pay attention to the consistencies that are performed:
▪ If the payment slip is registered with the final beneficiary's document equal to the
payer's document, the payment slip will have the registration accepted;
▪ If the customer registers the payment slip without the final beneficiary data, it will
be automatically assumed that the final beneficiary is the same as the payer;
▪ The original beneficiary, final beneficiary and original payer can have the same
documents;
▪ If the final beneficiary's document is different from the payer's document, the
payment slip registration will be rejected.
o For this type, the type of payment must be obligatorily as below:
▪ According to Registration: Does not allow changing value
▪ Divergent:

2023 – 05 V2.0
63
Confidential

Collection Hub– API User Guide

▪ Minimum Value 0.01 and Maximum Value 9999999.99 or

o Minimum Percentage 0.01 and Maximum Percentage 999.99% If a payment type other
than this is sent, the payment type “According to Registration” will automatically be
assumed.
o No discount, interest, fine and protest instructions are allowed. If these instructions are
sent, the payment slip will be registered without the instructions. Only the deduction
instruction is followed.
o If the payment slip is registered without a write-off period, it will be automatically
assumed to be written off 30 days after the expiration date.

Note 12: Discount (discount):

Type of discount to be granted for the payment slip, not being mandatory for registration:
Inform:

• ISENTO
• VALOR_DATA_FIXA
• VALOR_DIA_CORRIDO
• VALOR_DIA_UTIL

Up to three fixed discount occurrences (VALOR_DATA_FIXA) can be sent, being mandatory to

inform the value (value) and limitDate (limit date) for each one of them:

• The dates need to be increasing, not exceeding the due date of the payment slip;
• The amount of each of the discounts added to the amount of the rebate (if any) cannot be
equal to or greater than the face value of the payment slip.

For advance discounts (VALOR_DIA_CORRIDO and VALOR_DIA_UTIL) it is mandatory to inform

only the daily discount amount to be granted (value), the deadline will be the due date of the payment
slip.

Note 13: Protest Type (protestType):

Type of protest to be assigned to the payment slip, after the due date the protest will be issued
according to the number of days defined in the payment slip record (protestQuantityDays)
Inform:

• SEM_PROTESTO
• DIAS_CORRIDOS
• DIAS_UTEIS
• CADASTRO_CONVENIO

2023 – 05 V2.0
64
Confidential

Collection Hub– API User Guide

The number of days for protest (protestQuantityDays) is mandatory for protest types
DIAS_CORRIDOS and DIAS_UTEIS.

If the CADASTRO_CONVENIO option is indicated, the number of days previously registered in the
agreement will be assigned.

Note 14: Number of days for Automatic Write-Off (writeOffQuantityDays):

Number of days after the due date to write off the payment slip.
If zeros are entered, it will default to the profile of the beneficiary's health plan.

Note 15: Payment Type (paymentType):

Mandatory information that indicates the type of payment to be assigned to the payment slip:
Inform:

• REGISTRO: It will allow the payment slip to be paid only for the nominal value calculated
(interest, fine, discount and rebate);
• DIVERGENTE: It will allow the payment of the payment slip for a range of values, with a
minimum and maximum value/percentage defined in the registry;
• PARCIAL: It will allow up to 99 payments for the same payment slip, for a value range, with a
minimum and maximum value/percentage defined in the registry;

Note16: Parcels Quantity (parcelsQuantity):

Mandatory numerical field for payment slips where the type of payment “PARCIAL” was indicated,
indicates the number of payments that will be allowed for the same payment slip, with a maximum of
99.

Note 17: Value Type (valueType):

Mandatory field for payment slips where the type of payment “DIVERGENTE” or “PARCIAL” was
indicated. This field will define if the minimum and maximum values for payment slip payment will be
expressed in value or percentage.
Inform:

• PERCENTUAL
• VALOR

Note 18: Minimum amount or minimum percentage of the payment slip

(minValueOrPercentage):

Identifies the minimum amount or minimum percentage of the payment slip:

• When the type of value informed is PERCENTUAL, consider the following formatting
9(10)V99999
• When the type of value entered is VALOR, consider the following formatting 9(10)V99000

2023 – 05 V2.0
65
Confidential

Collection Hub– API User Guide

Note 19: Maximum value or maximum percentage of the payment slip

(maxValueOrPercentage):

Identifies the maximum value or maximum percentage of the payment slip:

• When the type of value informed is PERCENTUAL, consider the following formatting
9(10)V99999
• When the type of value entered is VALOR, consider the following formatting 9(10)V99000

Note 20: IOF (percentageIOF):

IOF is the acronym for Tax on Financial Operations, a tax to be collected on financial operations
involving credit, exchange, insurance, among others.

If the payment slip fits into operations where there is a need to collect IOF, the Bank can provide this
service, for this the Beneficiary must inform the percentage of IOF in the payment slip record, when it
is settled the Bank will deduct of the IOF for transfer to the responsible body.

There are also other ways to collect IOF in the settlement of payment slips:

Charges IOF on Registration:

It is also possible that the IOF percentage is fixed and is previously registered in the agreement, in
this case, if a different percentage is entered in the “percentageIOF” field during the registration of the
payment slip, it will be sovereign to the registration of the agreement.

Charges IOF in the Table:

In this modality, the Bank must inform the list of IOF rates that can be used. The customer must
inform in the first 2 positions of the field Our Number (bankNumber) the code referring to the tax rate.
Note: In this case, the payment slip will be registered with Our Number without the first 2 positions, as
they will be used exclusively for assigning the corresponding IOF rate.

Note 21: Sharing Code (sharing/code):

Credit sharing is a feature that allows the credit arising from the settlement of a payment slip to be
shared between up to 4 different current accounts.

Current accounts are associated with a receiver code, which must be previously registered in the
agreement to use the service.

2023 – 05 V2.0
66
Confidential

Collection Hub– API User Guide

Receiver codes must be indicated in the “code” field.

Note 22: Sharing Value (sharing/value):

Field that will indicate the amount to be shared between each of the current accounts associated with
the receiving codes.

The sum of the shared values must be equal to the nominal value of the payment slip.

Note 23: DICT Key Type (key/type):

Field used to indicate what type of PIX key the Beneficiary registered with Banco Santander.
It must be used in cases where the Beneficiary wants to link a PIX QRCode to the payment slip
(Boleto SX)
Inform:

• CPF
• CNPJ
• CELULAR
• EMAIL
• EVP

*Payment SX slips paid via QRCode can be consulted through the PIX Receipts API.
Later, the PIX Return functionality will also be available for BOLETO SX, when paid through
QRCode.

For more information, access the PIX API documentation through the Santander Developer Portal:
https://developer.santander.com.br/api/documentacao/pix

Note 24: DICT Key Code (key/dictKey):

Field used to indicate the PIX key code registered at Banco Santander to identify the Beneficiary and
the associated current account to receive the credits.

To issue the QR Code, the Beneficiary must have a valid key registered to receive PIX.

Note 25: QR Code identification code (txId):

Identification adopted and controlled by the Beneficiary if completed, if not completed, the Bank will
assign this identification automatically, according to the current system rule:

2023 – 05 V2.0
67
Confidential

Collection Hub– API User Guide

Date (DDMMYYYY)
Our number with 13 digits
Beneficiary Code with 9 digits
Environment (T) Test (P) Production with 1 digit
Collection System Acronym with 1 digit

This identification must be unique for each payment slip with a minimum of 26 characters and a
maximum of 35 alphanumeric characters. The characters accepted in this context are: A-Z, a-z, 0-9,
not containing blanks and nulls.

Note 26: Message (messages):

Messages to be printed on the payment slip, on the Payer's receipt.

They must be sent in list format with up to 45 texts with 100 characters.

Note 27: QRCode code (qrCodePix):

Code returned by Banco Santander so that the company can generate the Dynamic QRCode and
share the image or link with its payers to facilitate the payment.
The generation of the Dynamic QR Code image is the responsibility of the Beneficiary. Dynamic QR
Code generation standards follow the rules of the Central Bank.
Dynamic QRCodes can be read by your payer's Smartphone and the link used from any device.

Note 28: URL Code (qrCodeUrl):

Field made available to enable querying the status of the QRCode generated through an API.

6. Notes – PATCH (Payment slips Instructions)

Note 29: Change Due Date:

To change (advance or extend) the due date of the payment slip, inform the dueDate field in YYYY-
MM-DD format indicating the new due date.

2023 – 05 V2.0
68
Confidential

Collection Hub– API User Guide

Note 30: Change Nominal Value:

Instruction available only for payment slips whose type of document is BCC – Credit Card Payment
slip or BDP – Proposal Payment slip.

If the type of document is different from those mentioned above, the instruction will be rejected.

Inform:

• Nominal value (nominalValue)

Note 31: operation:

Option used for the following instructions:

• PROTESTO
• BAIXA
CANCELAR_PROTESTO

A protest can only be commanded for overdue payment slips.

The cancellation of the protest depends on the assessment of the notary responsible for the protest.

The beneficiary may send in the same request up to 10 instructions for the same payment slip, with
the exception of write-off, protest and protest cancellation instructions, which need to be sent
separately.

Note 32: Change Number of Protest Days:

Instruction available for payment slips in which a number of days for protest after expiration was
indicated in the record,
The number of protest days can be between 1 and 99. Indicate the desired number of days in the
“protestQuantityDays” field.

If the customer wants the payment slip to no longer be protested, he must send the protest
cancellation instruction.

Note 33: Grant/Cancel/Change Rebate:

To grant, cancel or change the deduction value of a payment slip, inform the “deductionValue” field.

To grant or change the deduction amount, inform the desired amount.

To cancel the discount amount, send the zero amount.

2023 – 05 V2.0
69
Confidential

Collection Hub– API User Guide

The rebate amount cannot be equal to or greater than the face value of the payment slip. If the
payment slip also has discount instructions, the amount of the rebate added to the amount of
discounts cannot be equal to or greater than the face value of the payment slip.

Note 34: Grant/Cancel/Change 1st, 2nd or 3rd Discount:

To grant or change the 1st, 2nd or 3rd discount, it is mandatory to send the fields:

• Type
• DiscountOne, DiscountTwo or DiscountThree
• Value
• LimitDate

To cancel the 1st, 2nd or 3rd discount, the following fields must be sent:

• Type
• DiscountOne, DiscountTwo or DiscountThree
• Value

The amount of discounts cannot be equal to or greater than the face value of the payment slip. If the
payment slip also has a rebate instruction, the value of the discounts added to the rebate value
cannot be equal to or greater than the face value of the payment slip.

The deadline for discounts must be less than the due date of the payment slip.

Note 35: Grant/Change/Cancel Early Bird Discount on Business/Mondays:

To grant or change a discount in advance on working/calendar days, the following fields must be
sent:

• Discount Type
• DiscountOne
• Value different from “0”

To cancel the discount in advance on working/calendar days, the following fields must be sent:

• Discount Type
• DiscountOne
• Value, which must be sent with “0”

The amount of discounts cannot be equal to or greater than the face value of the payment slip. If the
payment slip also has a rebate instruction, the value of the discounts added to the rebate value
cannot be equal to or greater than the face value of the payment slip.

Note 36: Charge/Cancel/Change Late Fee:

2023 – 05 V2.0
70
Confidential

Collection Hub– API User Guide

To grant or change the fine, inform:

• Value (finePercentage) other than “0”.

• Date of the Fine (FineDate) in YYYY-MM-DD format

For cancellation of the fine,

• Value (finePercentage) equals “0”.

The amount of the fine cannot exceed 60% of the face value of the payment slip.

The fine date cannot be less than the due date of the payment slip.

Note 37: Charge/Cancel/Change Interest per month due to Delay:

Enter the field: interestPercentage

To grant or change interest per month, inform the desired percentage.

For cancellation of interest per month, inform the zeroed field.

The amount of interest per month cannot exceed 60% of the nominal value of the payment slip.

Note 38: Grant/Cancel/Change Interest Tolerance:

To grant or change interest tolerance, send the fields:

• Value (interestValue) different from “0”

• Tolerance deadline (interestToleranceDate)

For cancellation of interest tolerance, send the field:

• Value (interestValue) equals “0”

Note 39: Change Minimum/Maximum Percentage for Payment

• To change the minimum percentage:

The minValueOrPercentage field must be informed other than 0.

Format: 9(10)V99999

Instruction not accepted for payment slips registered with the payment type “Conforme Registro”.

Instruction accepted only for payment slips whose minimum payment amount is registered as
“Percentual”.

2023 – 05 V2.0
71
Confidential

Collection Hub– API User Guide

• To change the maximum percentage:

The Field minValueOrPercentage must be informed different from 0.

Format: 9(10)V99999

Instruction not accepted for payment slips registered with the payment type “Conforme Registro”.

Instruction accepted only for payment slips whose maximum amount for payment is registered as
“Percentual”.

Note 40: Change Minimum/Maximum Amount for Payment

• • To change the minimum value:

The Field minValueOrPercentage must be informed different from 0.

Format: 9(13)V99

Instruction not accepted for payment slips registered with the payment type “Conforme Registro”.

Instruction accepted only for payment slips whose minimum payment amount is registered as “Valor”.

• To change the maximum value:

The Field minValueOrPercentage must be informed different from 0.

Format: 9(13)V99

Instruction not accepted for payment slips registered with the payment type “Conforme Registro”.

Instruction accepted only for payment slips whose maximum amount for payment is registered as
“Valor”.

Note 41: Number of days for a payment slip to be written off after the due date

Instruction to change the amount of payment slip write-off days after maturity.

Inform the number of days in the writeOffQuantityDays field, which must be between 1 and 99.

Note 42: Add/Delete/Change Your Number

Alphanumeric field of up to 15 positions, for identifying the payment slip in the company.
To include, exclude or change Your Number, indicate the “clientNumber” field.

If the field is received with more than 15 positions, the instruction will be rejected.

Only letters, numbers and spaces will be accepted in this field.

2023 – 05 V2.0
72
Confidential

Collection Hub– API User Guide

Special characters will not be accepted..

Note 43: Add/Delete/Change Participant Control

Alphanumeric field of up to 25 positions, for identifying the payment slip in the company. To add,
delete or change the Participant Control, indicate “participantCode”.

If the field is received with more than 25 positions, the instruction will be rejected.

Only letters, numbers and spaces will be accepted in this field. Special characters will not be
accepted.

For customers who also use the CNAB, if informed, it will be returned in the return file, when the
payment slip is settled, facilitating reconciliation.

7. Script in case of Errors during validations

In cases of error in requests, always review the following points:

• Validity of the certificate used, both to obtain credentials and to carry out requests;

• Check the correct indication of the Client ID and Client Secret in their respective fields (without spaces
after the value), as indicated in this manual;

• Make sure that the credentials used were obtained for the consumption of the Collection API (issuance
of payment slips)

• Validate if the X-Application-Key was correctly informed in the requests (body). This field must have the
same value as the Client Id and must be informed in all routes, with the exception of the Token route;

• Check if the URL indicated in the request is correct and make sure that they match the desired
environment (Sandbox, Production);

2023 – 05 V2.0
73
Confidential

Collection Hub– API User Guide

• Confirm that the Method (POST, GET, PATCH, DELETE) matches the desired operation, as indicated
in this manual;

• Make sure you are using a new/updated and correct token with no spaces;

• For tests via Postman or similar, always use the most up-to-date version of it;

• Verify the correct import of the certificate (Cert + Key or PFX + Password) in the Postman/company
software, and if the Santander Billing API URL was correctly indicated in the Host;

• If the above validations fail, generate new credentials in our Developer Portal and perform new tests.

• Pay attention to the structure of the fields to be sent to the bank for processing. They must be sent
exactly the same as those reported in this material and in the Collection Postman.

2023 – 05 V2.0
74
Confidential

Collection Hub– API User Guide

Error Messages
1- Errors in the registration and consultation of payment slips
1.1 Document Fields:

Código Field Description

1000 payer/documentType Payer document type is invalid. Valid options: CPF or CNPJ
1001 payer/documentNumber The document provided to the payer is invalid
1002 beneficiary/documentType Final payee document type is invalid. Valid options: CPF or CNPJ
1003 beneficiary/documentNumber The document entered for the final beneficiary is invalid

1.2 Lists Fields:

Código Field Description

1020 discount The amount of discounts is greater than the limit (3)
1021 sharing The number of shares is greater than the limit (4)
1022 messages The maximum amount of messages is 45
1023 messages Messages in positions: [X], have exceeded the size limit (100)
1024 sharing Shares at position: [X], Code and Value fields must be filled in

1.3 Value Fields:

Código Field Description

1040 valueType The value type is invalid. Valid options: PERCENTAGE, AMOUNT
1041 minimumValuePercentage / The minimum value/percentage cannot be greater than the
maximumValuePercentage maximum

2023 – 05 V2.0
75
Confidential

Collection Hub– API User Guide

1042 key/keyDictType Address key type is invalid. Valid options: CPF; CNPJ; CELULAR;
EMAIL; EVP
1043 bankNumber The bankNumber field cannot be equal to 0
1044 discount/type = null Invalid discount type. Valid options: ISENTO, VALOR DATA FIXA,
VALOR DIA CORRIDO, VALOR DIA UTIL
Discount/value = EXEMPT For the type of discount it is not possible to assign value
1045 discount/limitDate = EXEMPT For the type of discount it is not possible to assign a deadline
discount/limitDate = FIXED DATE For this type, it is necessary to inform the deadline for the discount
VALUE
discount/value = FIXED DATE VALUE For this type, it is necessary to inform the value for discount
1046
discount/type = FIXED DATE VALUE For this type, it is necessary to assign discounts
discount/type = CURRENT DAY For this type, it is necessary to assign discounts
VALUE/BUSINESS DAY VALUE
discount/discountsValue = CURRENT For this type, it is necessary to inform the value for discount
1047 DAY VALUE/BUSINESS DAY VALUE
discount/value = CURRENT DAY This type of discount allows only 1 item
VALUE/BUSINESS DAY VALUE
1048 paymentType Invalid protest type. Valid options: REGISTRO; DIVERGENTE;
PARCIAL
1049 protestType Invalid protest type. Valid options: SEM PROTESTO; DIAS CORRIDOS;
DIAS UTEIS; CADASTRO CONVENIO
1050 protest/quantityDay For this type of protest, it is necessary to inform the deadline
1052 covenantCode The covenantCode field cannot be equal to 0
1053 nsuCode nsuCode field cannot be equal to 0
1054 nsuCode For test environment (T), nsuCode must start with TST without 0
1055 parcelsQuantity The parcelsQuantity field cannot be filled in for the REGISTRO
payment type

1.4 Fields Configuration:

Código Field Description

1080 environment Invalid execution environment. Valid options: TESTE; PRODUCAO
1081 nsuCode For the test environment (T), the nsuCode must start as TST,
followed by the numbering
1082 nsuCode For production (P) environment, nsuCode must be numeric

2023 – 05 V2.0
76
Confidential

Collection Hub– API User Guide

2081 nsuCode For the test environment (T), the nsuCode must be TST /

2082 nsuCode For production (P) environment, nsuCode must be numeric

2083 ExecutionEnvironment Invalid environment type. Valid options:[P, T]

2084 bankslip_id Invalid bankslip_id key format

2085 bankNumber The bankNumber field cannot be equal to 0

2086 covenantCode The covenantCode field cannot be equal to 0

1.5 Physical Field Validations:

Código Campos Description

1090 All mandatory fields The field (" ") is mandatory
1091 All fields The character limit for the field (" ") is (" ")
0900 All numeric fields The field [field_name] only allows numeric values
0901 All alphanumeric fields Field [field_name] only allows alphanumeric values [and
(allowed_characters)]
0902 All date fields The field [name_field] only allows dates in the pattern YYY-MM-
DD, separated by a hyphen, example (2022-09-09)
0903 All value fields The field [name_field] only allows numerical values with 2 decimals
separated by a period. example (1000.00).
0904 All percent fields The field [name_field] only allows numbers with
[number_decimals] decimals separated by a period. example
(100.[example_number_decimals])
0905 All fields that only allow letters The field [field_name] only allows letters
0906 Zip code fields The field [name_field] only allows numbers with the zip code
pattern. example (00000-000)
0907 Email Fields The entered key does not have an email format
0908 PIX random key The random key entered does not have a valid format

Product Rules:

Código Description

2023 – 05 V2.0
77
Confidential

Collection Hub– API User Guide

0001 Our number already registered

00007 Invalid document type
00016 Invalid expiration date
00026 Maturity date greater than 10 years
00057 Incorrect payee zip code
00058 Incorrect CPF / CNPJ
00059 Reduction + Second Discount must be less than the value of the security
00060 Reduction + Third Discount must be less than the value of the title
00075 Second Discount greater than or equal to the security value
00076 Third Discount greater than or equal to the value of the title
00086 Date of the second Invalid discount
00087 Date of the third Invalid discount
00093 Title value not informed
00098 Invalid issue date
00100 Issuance date greater than the expiration date
00102 Payee address not informed
00103 City of the drawee not informed
00107 Wrong federation unit
00113 Invalid discount amount
00124 Payee zip code not found
00128 Invalid protest code
00145 Invalid document type
00147 Number of days for invalid protest
00160 Drawee's neighborhood not informed
00176 register not found
00199 Invalid drawer/guarantor document type
00200 CPF/CNPJ of the non-numeric drawer/guarantor
00201 Invalid CPF/CNPJ of the drawer/guarantor
00202 Invalid drawer/guarantor name
00391 Second non-numeric discount value
00393 Third non-numeric discount value
00398 Second discount not allowed
00399 Third discount not allowed
00408 Invalid first share value
00409 Invalid first share issuer code

2023 – 05 V2.0
78
Confidential

Collection Hub– API User Guide

00410 Invalid second share value

00411 Invalid second share issuer code
00412 Invalid third share value
00413 Invalid third share issuer code
00414 Value of the fourth invalid share
00415 Invalid fourth share issuer code
00416 Total share value different from title value
00422 inconsistent certificate
00423 Station is not from the agreement
00424 Unmarked agreement to exchange message for online entry
00425 Environment marked as test and NSU is not test
00426 Environment marked as production with test NSU
00427 Invalid face value for payment type
00428 Agreement is not active
00429 Invalid discount type
00430 Free with discount value
00431 Field our non-numeric number
00432 Invalid payment type
00433 Invalid discount deadline
00434 Invalid amount of partial payments
00444 Invalid value type
00464 Invalid minimum percentage, less than the minimum allowed
00465 Invalid minimum percentage, less than maximum allowed
00468 Invalid maximum percentage, less than allowed minimum
00469 Invalid maximum percentage, greater than the maximum allowed
00470 Invalid maximum percentage, less than the minimum informed
00473 Invalid minimum value for zeroed nominal value
00474 Invalid minimum value, greater than security value
00475 Invalid minimum value, greater than allowed
00479 Invalid maximum value, less than title value
00480 Invalid maximum value, less than the minimum value entered
00482 Minimum value must be greater than zeros
00483 Final beneficiary other than payer
00484 Address key type differs from 1,2,3,4 or 5
00485 Address key type differs from DICT register

2023 – 05 V2.0
79
Confidential

Collection Hub– API User Guide

00486 DICT addressing key must be informed for type of addressing key entered
00487 DICT addressing switch not located on base
00488 Agreement data does not match DICT addressing data
00489 Payer's root CNPJ cannot be the same as that of the original beneficiary
00490 Payer's root CNPJ cannot be the same as that of the final beneficiary
00491 CNPJ Root of the final beneficiary cannot be the same as that of the original beneficiary
00492 Payer's CPF cannot be the same as the original beneficiary's
00493 Payer's CPF cannot be the same as the final beneficiary's
00494 CPF of the final beneficiary cannot be the same as that of the original beneficiary
00495 Registration not allowed – Final Beneficiary with restriction
00496 TXID reported twice
00497 TXID entered incorrectly
00498 Unavailability in the generation of the QR Code Pix.
00499 Final beneficiary not informed in the payment slip record

2- Errors in payment slips instructions

2.1 Value fields:

Code Field Message

3040 operation For this type of operation there can be no other changes. Fields with
values: [fields]
3041 protestQuantityDay The number of protest days must be between 1 and 99 days

3042 writeOffQuantityDays The number of sick days must be between 1 and 90 days

3043 minValueOrPercentage Minimum value/percent cannot be zero

3044 maxValueOrPercentage Maximum value/percent cannot be zero

3045 discountX No discount should be entered when type 0 (EXEMPTED) is selected

3046 discount To change the amount of the discount, you must enter a value

3047 discount To change type 2 or 3, you must inform only the value and date in the field
discountOne - Remove date, leave only value
3048 discount.type To change discounts, it is necessary to inform the type

2.2 Physical field validations:

2023 – 05 V2.0
80
Confidential

Collection Hub– API User Guide

Code Field Message

3090 All fields No changes have been identified

3091 All fields Change limit is 10. Quantity requested: [X]

3092 finePercentage and fineDate To make the fine change effective, the finePercentage and fineDate fields
must be filled in
3093 limitDateWithoutInterest For interest cancellation, the limitDateWithoutInterest field must not be
filled in
3094 limitDateWithoutInterest The limitDateWithoutInterest field must be filled in

3095 interestValuePerDay The interestValuePerDay field must be filled in

2.3 Formats:

Code Field Message

900 Numeric The field [name_field] only allows numeric values

901 Alphanumeric Field [field_name] only allows alphanumeric values [and (allowed_characters)]

902 Date The field [name_field] only allows dates in the pattern YYY-MM-DD, separated by a
hyphen, example (2022-09-09)

903 Monetary The field [name_field] only allows numerical values with 2 decimals separated by a
period. example (1000.00).
904 Percentage The field [name_field] only allows numbers with [number_decimals] decimals
separated by a period. example (100.[example_number_decimals])
905 Letters The field [field_name] only allows letters

Product Rules:

CODE MESSAGE
002 Non-existent contract code
003 Protest or layoff instructions must not be sent together with other instructions
004 Our non-existent number
005 Invalid request type code entered

2023 – 05 V2.0
81
Confidential

Collection Hub– API User Guide

006 Error in the request to handle "Instructions Requested" - Invalid informed date
007 Error in the request to handle "Requested Instructions" - Invalid informed value
008 Error in the request to handle “Instructions Requested” - Invalid informed field
055 Agreement is not active
062 Payment slip FIDC cannot be written off
063 Unauthorized instruction for traded payment slips
065 Instruction already commanded, awaiting authorization
066 Instruction will be pending authorization by the Guarantees system
067 Payment slip negotiated, instruction not allowed
068 Payment slip under negotiation, release not allowed
069 Payment slip under negotiation, write-off not allowed
071 Instruction not allowed, payment slip already written
072 Instruction not allowed, payment slip already settled
088 Instruction not allowed, payment slip is not in the notary's office
099 There was an error, please try again or contact us – “Internal Code”
110 Instruction not accepted by the Discount system
158 Instruction not allowed, agreement is not active
159 Statement cannot be commanded for proposal payment slip
160 Statement cannot be commanded for credit card payment slip
161 The statement cannot be commanded to payment slip Cash In
164 Instruction cannot be commanded for deposit payment slip
169 Instruction rejected, payment slip in negotiation
208 Instruction not allowed, protest order already issued
209 Instruction not allowed, protest withdrawal in progress
210 Instruction not allowed, payment slip already sent to notary
211 Instruction not allowed, payment slip already protested
213 Instruction not allowed, payment slip is not due
214 Negotiated payment slip cannot be protested
215 Type of document cannot be protested
217 Payment slip negotiated, not protestable in this location
218 Payment slip not protestable in this location
222 Protest not allowed for payer
226 Office space is blocked
254 Change not allowed, payment slip has no protest instruction
255 Change not allowed, payment slip has no write-off instruction

2023 – 05 V2.0
82
Confidential

Collection Hub– API User Guide

256 Change not allowed, payment slip with write-off due to the agreement profile
257 Change not allowed, payment slip with protest cycle already started
304 Suspension not allowed, payment slip without protest order issued
352 Cancellation not allowed, payment slip without protest
355 Payment slip already has protest cancellation in progress
356 Cancellation not allowed, payment slip is not protested
401 Instruction not allowed for Assignment payment slip
402 Instruction not allowed for payment slip FIDC
451 Payment slip FIDC cannot be discounted
452 Payment slip FIDC cannot be discounted
453 "Instruction" value greater than or equal to the payment slip value
463 First discount date greater than the due date
464 Date second discount greater than due date
465 Third discount date greater than the due date
466 First discount date less than issue date
467 Date second discount less than issue date
468 Third discount date less than issue date
470 Fine date must be greater than due date
471 Interest date must be greater than maturity
476 Discount amount + prim. discount greater than or equal to the payment slip value
477 Discount amount + sec. discount greater than or equal to the payment slip value
478 Discount amount + third discount greater than or equal to the payment slip value
483 Discount value + day discount greater than or equal to the value of the bill
484 Rebate value + working day discount greater than or equal to the payment slip value
485 First Value discount + rebate greater than or equal to the payment slip value
486 First discount date greater than or equal to the second discount date
487 Instruction second discount without having the first
488 Date second discount less than or equal to the first
489 Date second discount greater than or equal to the third
490 Value according to discount + discount greater than or equal to the value of the bill
491 Discount value calendar days greater than or equal to the value of the ticket
492 Discount value calendar days + deduction greater than or equal to the value of the bill
493 Discount value working days greater than or equal to the value of the ticket
494 Discount value working days + deduction greater than or equal to the value of the bill
495 Instruction third discount without having the second

2023 – 05 V2.0
83
Confidential

Collection Hub– API User Guide

496 Third discount date less than or equal to the second

497 Value third discount + discount greater than or equal to the value of the bill
499 Interest percentage greater than “Maximum percentage allowed”
500 Instruction not allowed. Interest tolerance already exists
551 Portfolio does not allow change of minimum percentage
552 Payment slip under negotiation does not allow changing the minimum percentage
553 The instruction cannot be commanded for the payment slip with the payment type. conf. record
554 Payment slip has no minimum/maximum registered
555 Instruction not allowed, billet has a minimum value
556 Type of document requires a minimum percentage of 0.01%
557 Minimum percentage cannot be 0
558 Minimum percentage greater than 100%
560 Minimum percentage lower than the allowed standard
561 Minimum percentage greater than the allowed standard
562 Minimum percentage greater than the maximum percentage of the slip
563 Portfolio does not allow changing the maximum percentage
564 Payment slip under negotiation does not allow changing the maximum percentage
567 Instruction not allowed, payment slip has a maximum value
568 Type of document requires maximum percentage 999.99%
569 Maximum percentage less than 100%
570 Invalid maximum percentage, must be less than 999.99%
571 Maximum percentage less than the allowed standard
572 Maximum percentage greater than the default allowed
573 Maximum percentage less than the minimum percentage of the bill
574 Wallet does not allow change of minimum value
575 Ticket under negotiation does not allow change of minimum value
578 Instruction not allowed, billet has a minimum percentage
581 Minimum value cannot be zero
582 Minimum amount must be less than or equal to the maximum amount of the ticket
583 Minimum amount must be less than or equal to the face value of the bill
584 Wallet does not allow change of maximum amount
585 Ticket under negotiation does not allow changing the maximum amount
588 Instruction not allowed, billet has a maximum percentage
591 Maximum value must be greater than or equal to the minimum value
593 Maximum value must be greater than or equal to nominal value

2023 – 05 V2.0
84
Confidential

Collection Hub– API User Guide

594 Portfolio does not allow change of face value

595 Payment slip under negotiation does not allow change of face value
596 Type of document does not allow change of nominal value
597 Type of document does not allow zeroed nominal value
598 Face value cannot be zero for payment type
599 Invalid nominal value, less than the minimum allowed value
600 Invalid nominal value, greater than the maximum allowed value

2023 – 05 V2.0
85