API docs by Redocly

Flagship APIs (1.0.0)

Download OpenAPI specification:

Service Specification

Authentication

Generates an access token for authentication on secured endpoints.

For accessing secured endpoints it is necessary to generate an access token in first place. This is done through Keycloak. Be aware that the client must be configured on Keycloak in order to obtain access tokens. Further calls to secured endpoints must include the access token in the "Authorization" header as a bearer token. The format should be "Authorization: Bearer ".

Authorizations:
oAuth2ClientCredentials
path Parameters
realm
required
string

Name of the Keycloak's realm.

Request Body schema: application/x-www-form-urlencoded
required

Request body.

client_id
string

The client_id that was previously configured on Keycloak.

grant_type
string

Grant type used to obtain an acess token. Use the value "client_credentials".

client_secret
string

The secret associated with the client_id.

Responses

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY",
  • "expires_in": "36000,",
  • "refresh_expires_in": 0,
  • "token_type": "Bearer",
  • "not-before-policy": 0,
  • "scope": "profile email"
}

Payments

Inserts a new purchase made on a marketplace.

Synchronously handle requests for payment, the service receives the details relating to a recovery order by credit card, forwards the details to the financial Gateway and returns a response to the requester.

Authorizations:
oAuth2ClientCredentials
header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the concatenation of the fields, in the following order:
1 - sender.account.branch and sender.account.account or sender.account.accountId or;
2 - sender.account.client.taxIdentifier.taxId or;
3 -

  • If it's a MobilePhone transaction type: paymentInfo.mobilePayment.mobilePhone.phoneNumber and paymentInfo.mobilePayment.taxIdentifier.taxId.
  • If it's a CreditCard transaction type: paymentInfo.creditCard.creditCardToken.
  • If it's a InstantPayment transaction type: paymentInfo.instantPayment.alias.

4 - and totalAmount (integer part).
5 - and recipients.account.branch and recipients.account.account or recipients.account.accountId or recipients.account.mobilePhone.phoneNumber.
6 - and recipients.amount (integer part).

Request Body schema: application/json
required

Request body.

totalAmount
number

The total amount value. In case of instant payment, amount before applying any discounts or interest.

currency
string
Value: "BRL"

ISO 4217 - Only BRL is supported.

object (PaymentInfo)

Payment information. Note: billingAddress, creditCard, directDebit, mobilePayment, futureDate, mode, authorizationCode and billingNumber fields have been removed from the documentation.

object (Sender)
Array of objects (Recipient)

List of Recipient

externalIdentifier
string (ExternalIdentifier)

Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

callbackAddress
string

When this information is provided, then service returns informations about transaction asynchronously

Responses

Request samples

Content type
application/json
{
  • "totalAmount": "10",
  • "currency": "BRL",
  • "paymentInfo": {
    },
  • "sender": {
    },
  • "recipients": [
    ],
  • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83",
  • "callbackAddress": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Processes a new payment transaction between accounts using the sender account balance as fund source.

Synchronously handle requests for internal payment

Authorizations:
oAuth2ClientCredentials
header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the concatenation of the fields, in the following order: 1 - sender.account.branch and sender.account.accountNumber or sender.account.accountId or; 2 - client.taxId ; and recipient.account.branch and recipient.account.accountNumber or recipient.account.accountId, or recipient.mobilePhone.phoneNumber and recipient.amount(integer part)

Request Body schema: application/json
required

Request body.

totalAmount
required
number
currency
required
string
Enum: "BRL" "USD" "EUR" "AUD" "CAD" "GBP"

ISO 4217 de 3 letras

object (PaymentInfoInternalPayment)
required
object (SenderInternalPayment)

account or client must be informed.

object (AccountIdentifier)
required
Array of objects (RecipientInternalPayment)

List of Recipient

externalIdentifier
required
string (ExternalIdentifier)

Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

callbackAddress
string

When this information is provided, then service returns informations about transaction asynchronously

Responses

Request samples

Content type
application/json
{
  • "totalAmount": 0,
  • "currency": "BRL",
  • "paymentInfo": {
    },
  • "sender": {
    },
  • "myAccount": {
    },
  • "recipients": [
    ],
  • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83",
  • "callbackAddress": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Query payments.

This service enables to query payments by transactionId.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string

TransactionId to be queried

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the lower case http method name followed by the request path, using : as a separator. E.g. get:/v1/payments/123

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Query internal payments.

This service enables to query internal payments by transactionId.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string

TransactionId to be queried

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the lower case http method name followed by the request path, using : as a separator. E.g. get:/v1/payments/internal-payment/123

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Unlock a payment

Unlock a payment amount by transactionId

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string

The identification for transaction payment

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the concatenation of transactionId and externalIdentifier

Request Body schema: application/json
required

Request body.

externalIdentifier
string (ExternalIdentifier)

Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

Responses

Request samples

Content type
application/json
{
  • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Raise a full refund for one transaction.

Functionality responsible for reversing transactions involved in the "/v1/payments" API. Transactions involved are CreditCard, InternalTransfer and External.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string
Example: 33ec78fa-c80c-4f59-85df-3e51166aab34

Identifier of the transaction that will be subject to reversal

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the lower case http method name followed by the request path.

Request Body schema: application/json
reason
string

Cancellation message.

externalIdentifier
required
string (ExternalIdentifier)

Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

Responses

Request samples

Content type
application/json
{
  • "reason": "string",
  • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Raise a full refund for one transaction.

Functionality responsible for reversing transactions involved in the "/v1/payments/internal-payment" API. Transaction involved is InternalPayment.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string
Example: 33ec78fa-c80c-4f59-85df-3e51166aab34

Identifier of the transaction that will be subject to reversal

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the lower case http method name followed by the request path.

Request Body schema: application/json
reason
string

Cancellation message.

externalIdentifier
required
string (ExternalIdentifier)

Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

Responses

Request samples

Content type
application/json
{
  • "reason": "string",
  • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Mobile Phone Recharge

Carrier values list

Retrieve a list of recharge values according to country code and mobile area code

Authorizations:
oAuth2ClientCredentials
path Parameters
countryCode
required
string

Country code

areaCode
required
string

Mobile area code

carrierId
required
string

Carrier Code

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Retrieve a carrier list

Authorizations:
oAuth2ClientCredentials
path Parameters
countryCode
required
string
areaCode
required
string
header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Recharge a mobile phone number

Recharges a mobile phone number according to value and phone chosen.

Authorizations:
oAuth2ClientCredentials
path Parameters
accountId
required
string

Account identifier

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the concatenation of the fields, in the following order: accountId (path param), mobilePhone.phoneNumber and totalAmount (integer part)

Request Body schema: application/json
required

Request body.

object (MobilePhone)
totalAmount
required
number
carrierId
required
string
externalIdentifier
required
string (ExternalIdentifier)

Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

Responses

Request samples

Content type
application/json
{
  • "mobilePhone": {
    },
  • "totalAmount": 0,
  • "carrierId": "string",
  • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Accounts

Returns a list of account identifiers that are accessible by the calling integrator

This service allows each mediator to query accounts that are bound to a specific phone number or tax identifier. Note that either a phone number or a tax identifier must be sent as query params, but not both

Authorizations:
oAuth2ClientCredentials
query Parameters
phoneNumberCountry
string

Phone number country ISO code (eg. BRA)

phoneNumber
string

Phone number in international format, without the country code (eg. 11987654321)

taxIdCountry
string

Tax identifier country ISO code (eg. BRA)

taxId
string

Tax identifier value

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the concatenation of the query parameters, in the following order: phoneNumberCountry, phoneNumber, taxIdCountry, taxId. If a query param is not used for a request, just ignore it. E.g.: if phoneNumberCountry is BRA and phoneNumber is 11987654321, the value to be hashed is BRA11987654321

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Create a new account at MATERA Meios de Pagamento.

This service enables integrator to create account for their customers, an integrator can create shared and non-shared accounts, since their profile grant it.

Authorizations:
oAuth2ClientCredentials
header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the concatenation of externalIdentifier and taxId of client

Request Body schema: application/json
required

Request body.

externalIdentifier
required
string (ExternalIdentifier)

Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

required
object (BasicClient)
object (Endereco)
clientType
string (RequestClientType)
Enum: "PERSON" "CORPORATE" "FOREIGNER"

If the clientType attribute is not informed in the request, the value of other fields is used to determine its value:
When the additionalDetails attribute is informed:

  • additionalDetailsPerson.rg → PERSON
  • additionalDetailsCorporate.companyName → CORPORATE
  • If neither of both fields are informed → FOREIGNER
When the additionalDetails attribute is not informed, the value of taxId is used to determine whether it is PERSON or CORPORATE

required
Array of objects

List of Strings representing images of documents serialized using Base 64. Required field.

accountType
string
Value: "UNLIMITED_ORDINARY"

Only UNLIMITED_ORDINARY is supported.

object (AdditionalDetailsPerson)

Additional details for person accounts.

object (AdditionalDetailsCorporate)

When the account creation strategy is SYNCHRONOUS_SHARED or SYNCHRONOUS_NON_SHARED and the account is of type CORPORATE, only the first record in the list of representatives will be saved.

customData
string

Use this field for sending deviceId and geolocation information.

Responses

Request samples

Content type
application/json
{
  • "externalIdentifier": "25227177660",
  • "client": {
    },
  • "additionalDetailsCorporate": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Returns a list of account identifiers that can be accessed by the call integrator.

When the configuration phoneNumberIdentificationSupport is disable is possible create multiples accounts with the same mobile number, so this api return the list of accounts and the account holder each one account information. The mobile phone number on request can be concatenation with the Country ISO code (eg. BRA).

Authorizations:
oAuth2ClientCredentials
path Parameters
mobilePhoneNumber
required
string

Phone number in international format (eg. 11987654321), the country ISO code is optional and can be concatenation, if not informed the default is BRA (eg. BRA11987654321).

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the concatenation of the path parameters: mobilePhoneNumber. E.g.: BRA11987654321 or BRA11987654321

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Inactive checking account with provided account.

Deactivates the provided account, blocking further transactions on it.

Authorizations:
oAuth2ClientCredentials
path Parameters
accountId
required
string

Account identifier

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on accountId

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Update an account data.

This service enables integrator to manipulate and send further data related to the account.

Authorizations:
oAuth2ClientCredentials
path Parameters
accountId
required
string

Account identifier

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the concatenation of externalIdentifier and taxId of client

Request Body schema: application/json
required

Request body.

externalIdentifier
required
string (ExternalIdentifier)

Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

sharedAccount
boolean
required
object (ClientUpdate)
object (Client)
object (Endereco)
clientType
string (RequestClientType)
Enum: "PERSON" "CORPORATE" "FOREIGNER"

If the clientType attribute is not informed in the request, the value of other fields is used to determine its value:
When the additionalDetails attribute is informed:

  • additionalDetailsPerson.rg → PERSON
  • additionalDetailsCorporate.companyName → CORPORATE
  • If neither of both fields are informed → FOREIGNER
When the additionalDetails attribute is not informed, the value of taxId is used to determine whether it is PERSON or CORPORATE

Array of objects (Document)

List of Strings representing images of documents serialized using Base 64

accountType
string

ORDINARY/UNLIMITED_ORDINARY/COMMON/OVERDRAFT_PROTECTED

object (AdditionalDetailsPersonUpdate)

Additional details for person accounts.

object (AdditionalDetailsCorporateUpdate)

Required information when the account is setted as Corporate.

object (AdditionalDetailsForeigner)
object (MobilePhone)
ibkPwdHash
string
accountInternalTypeId
number

Responses

Request samples

Content type
application/json
{
  • "externalIdentifier": "25227177660",
  • "sharedAccount": false,
  • "client": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Query account data.

This service enables integrator for query account data. One integrator must have this access rights, and an integrator can only request data from an account created by them and for non-shared accounts.

Authorizations:
oAuth2ClientCredentials
path Parameters
accountId
required
string

Account identifier

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the accountId

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Inactive checking account with provided account and branch.

Deactivates the provided account, blocking further transactions on it.

Authorizations:
oAuth2ClientCredentials
path Parameters
branch
required
string

Branch number

account
required
string

Account number

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the concatenation of branch and account number

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Update an account data by branch and account.

this service enables integrator to manipulate and send further data related to the account.

Authorizations:
oAuth2ClientCredentials
path Parameters
branch
required
string

branch identification

account
required
string

account identification

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the concatenation of externalIdentifier and taxId of client

Request Body schema: application/json
required

Request body.

externalIdentifier
required
string (ExternalIdentifier)

Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

sharedAccount
boolean
required
object (ClientUpdate)
object (Client)
object (Endereco)
clientType
string (RequestClientType)
Enum: "PERSON" "CORPORATE" "FOREIGNER"

If the clientType attribute is not informed in the request, the value of other fields is used to determine its value:
When the additionalDetails attribute is informed:

  • additionalDetailsPerson.rg → PERSON
  • additionalDetailsCorporate.companyName → CORPORATE
  • If neither of both fields are informed → FOREIGNER
When the additionalDetails attribute is not informed, the value of taxId is used to determine whether it is PERSON or CORPORATE

Array of objects (Document)

List of Strings representing images of documents serialized using Base 64

accountType
string

ORDINARY/UNLIMITED_ORDINARY/COMMON/OVERDRAFT_PROTECTED

object (AdditionalDetailsPersonUpdate)

Additional details for person accounts.

object (AdditionalDetailsCorporateUpdate)

Required information when the account is setted as Corporate.

object (AdditionalDetailsForeigner)
object (MobilePhone)
ibkPwdHash
string
accountInternalTypeId
number

Responses

Request samples

Content type
application/json
{
  • "externalIdentifier": "25227177660",
  • "sharedAccount": false,
  • "client": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get account branch Data.

This service enables integrator for query account data by branch and account. One integrator must have this access rights, and an integrator can only request data from an account created by them and for non-shared accounts.

Authorizations:
oAuth2ClientCredentials
path Parameters
branch
required
integer

branch identification

account
required
integer <int64>

account identification

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the lower case http method name followed by the request path, using : as a separator. E.g. get:/v1/accounts/1/3232

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Remove phone number relationship with provided account.

this service enables integrator to manipulate and send further data related to the account.

Authorizations:
oAuth2ClientCredentials
path Parameters
accountId
required
string

Account identifier

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on accountId

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Update phone number linked to account.

this service enables integrator to manipulate and send further data related to the account.

Authorizations:
oAuth2ClientCredentials
path Parameters
accountId
required
string

Account identifier

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on accountId

Request Body schema: application/json
required

Request body.

object (MobilePhone)

Responses

Request samples

Content type
application/json
{
  • "mobilePhone": {
    }
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Query account statement.

This service enables integrator to query account statement. One integrator must have this access rights, and an integrator can only request statement to account created by them and for non-shared accounts.

Authorizations:
oAuth2ClientCredentials
path Parameters
accountId
required
string

Account identifier

query Parameters
start
string
ending
string
dateType
string
Enum: "ENTRY" "REALIZATION"
header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the accountId

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Query account statement.

This service enables integrator to query account statement. One integrator must have this access rights, and an integrator can only request statement to account created by them and for non-shared accounts. The V3 allows paged result.

Authorizations:
oAuth2ClientCredentials
path Parameters
accountId
required
string
Example: CCAb9323-E595-5ed9-a389-0938333b6fb1

Account Identification

query Parameters
startDateTime
required
string <date-time>
Example: startDateTime=2023-01-01T01:00:00

Start date for generating the statement

endDateTime
string <date-time>
Example: endDateTime=2023-12-31T23:59:59

Final date for generating the statement. If it is not informed, the system will show results considering the end date the same as the start date.

dateCategory
string
Enum: "ENTRY" "INCOMING"

Type of date filter. The ENTRY value considers records according to their posting date (creditDate) and INCOMING considers records according to their entry date (entryDate). Default = ENTRY.

pageSize
required
integer >= 1
Example: pageSize=25

Size of the pages as required. Number of items per page. Defined as 0 ≤ x ≤ 100, where x is the pageSize

pageNumber
required
integer >= 0
Example: pageNumber=3

Number of the current page as required. Page number (example: if I have 100 records and put the pageSize 2, will have from record 1 to 50 on page 0 (pageNumber =0) and from record 51 to 100 on page 1 (pageNumber =1))

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the lower case http method name followed by the request path, using as a separator. E.g. get:/v3/accounts/13E700E0-2372-A23A-8D90-57ACBEBDE46A/statement

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Raise a proposal to update an account overdraft protection.

Authorizations:
oAuth2ClientCredentials
path Parameters
accountId
required
string

Account identifier

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the overdraft amount(integer part)

Request Body schema: application/json
required

Request body.

overdraftAmount
number

Responses

Request samples

Content type
application/json
{
  • "overdraftAmount": 0
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Raise a proposal to update an account overdraft protection.

Authorizations:
oAuth2ClientCredentials
path Parameters
branch
required
string

branch identification

account
required
string

account identification

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the overdraft amount(integer part)

Request Body schema: application/json
required

Request body.

overdraftAmount
number

Responses

Request samples

Content type
application/json
{
  • "overdraftAmount": 0
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Perform a balance lock.

Service responsible for performing a balance lock according to the amount reported.

Authorizations:
oAuth2ClientCredentials
path Parameters
accountId
required
string

Transaction to be full refunded

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the concatenation of amount(integer part) and accountId

Request Body schema: application/json
required

Request body.

externalIdentifier
required
string (ExternalIdentifier)

Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

amount
number

Balance amount that should be blocked

reasonIdentifier
number

Reason why the Balance is being blocked

Responses

Request samples

Content type
application/json
{
  • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83",
  • "amount": 0,
  • "reasonIdentifier": 0
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Perform a balance unlock.

Perform balance unlock. The unlocking value is obtained through the transactionId.

Authorizations:
oAuth2ClientCredentials
path Parameters
accountId
required
string

Account identifier

transactionId
required
string

Balance lock identifier

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the concatenation of transactionId and accountId

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Perform payment reversal.

Functionality responsible for reversing transactions involved in the Withdraw APIs. Transactions involved are BankTransfer, External, Boleto and Utilities.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string
Example: 33ec78fa-c80c-4f59-85df-3e51166aab34

Identifier of the transaction that will be subject to reversal

accountId
required
string
Example: CCAb9323-E595-5ed9-a389-0938333b6fb1

Account Identification

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the lower case http method name followed by the request path.

Request Body schema: application/json
reason
string

Cancellation message.

externalIdentifier
required
string (ExternalIdentifier)

Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

Responses

Request samples

Content type
application/json
{
  • "reason": "string",
  • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Balance

Query account balance.

this service enables integrator to query account balance. One integrator must have this access rights, and an integrator can only request statement to account created by them and for non-shared accounts.

Authorizations:
oAuth2ClientCredentials
path Parameters
accountId
required
string

Account identifier

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the concatenation of accountId

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Query account balance.

this service enables integrator to query account balance. One integrator must have this access rights, and an integrator can only request statement to account created by them and for non-shared accounts.

Authorizations:
oAuth2ClientCredentials
path Parameters
accountId
required
string

Account identifier

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the concatenation of accountId

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Query account balance.

this service enables integrator to query account balance. One integrator must have this access rights, and an integrator can only request statement to account created by them and for non-shared accounts.

Authorizations:
oAuth2ClientCredentials
path Parameters
branch
required
integer

branch identification

account
required
integer <int64>

account identification

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the concatenation of branch and account number

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Query account balance.

this service enables integrator to query account balance. One integrator must have this access rights, and an integrator can only request statement to account created by them and for non-shared accounts.

Authorizations:
oAuth2ClientCredentials
path Parameters
branch
required
integer

branch identification

account
required
integer <int64>

account identification

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the concatenation of branch and account number

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Period balance inquiry

Authorizations:
None
path Parameters
accountId
required
string
Example: {{accountId}}
query Parameters
startDate
string
Example: startDate=2024-06-05
endDate
string
Example: endDate=2024-06-07
header Parameters
Authorization
string
Example: Bearer {{token}}
Transaction-Hash
string
Example: {{Hash}}

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Withdraw

Raise a request to withdraw an amount from MATERA Meios de Pagamento to a common Bank.

Using this service an integrator can raise a transaction for withdraw values from a MATERA Meios de Pagamento account to a common bank account.
Note: For cashouts of the InstantPayment type, the payer account details are retrieved based on the registered account information. The accountType attribute of the payer account, as informed to the SPI in the Pix arrangement, is mapped as follows

  • ORDINARY → TRAN (payment account)
  • OVERDRAFT_PROTECTED → CACC (checking account)
  • COMMON → CACC (checking account)
  • UNLIMITED_ORDINARY → TRAN (payment account)

Authorizations:
oAuth2ClientCredentials
path Parameters
accountId
required
string

account identification

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the concatenation of the fields, in the following order: totalAmount(integer part), and accountId, and 1 - if is BankTransfer type: bank and branch and account destination or; 2 - if is Boleto type: barcode or typeableLine; 3 - if is InstantPayment, it should also include withdrawInfo.instantPayment.recipient.pspId and withdrawInfo.instantPayment.recipient.taxIdentifier.taxId.

Request Body schema: application/json
required

Request body.

totalAmount
required
number

The value, before applying any discounts or interest, when the withdrawType is Boleto and Provider is CELCOIN. [interestAmount, fineAmount,discounts]

This field will be used after 2021-11-28 (required for book of messages 5.03.1 and beyond)

How to fill in the field
totalAmount Payment amount Option 1 - QR Code Reading (decoding service)
  * Static QR Code - if it has the staticQrcodeData.value field, otherwise the value informed by the user in the channel must be used.
  * Dynamic QR Code billing due date - dynamicQrcodeData.payload.value.final

Dynamic QR Code for immediate billing
  * Regular charge - When the dynamicQrcodeData.payload.valor.retirada structure is not returned, use the value of the field dynamicQrcodeData  .payload.valor.original.
If the dynamicQrcodeData.payload.value.modidadeAlteracao field is returned, the channel must allow the user to enter the Pix value.
  * Pix billign cashout - If the purpose of the transaction is Pix Cashout (transactionPurpose field equal to OTHR), the field value must be the same informed in the TransactionValuesDetails.cashValue.
  * Pix billing change of money - If the purpose of the transaction is Pix change of money (transactionPurpose field equal to GSCB), the value field must be the sum of the transactionValue + cashValue.

Option 2 - manual entry by user channel

mediatorFee
number
currency
required
string
Enum: "BRL" "USD" "EUR" "AUD" "CAD" "GBP"

ISO 4217 de 3 letras

required
object (WithdrawInfo)

Withdraw information. Note: ReloadPrepaid and External types have been removed. The external object has also been removed from the documentation.

externalIdentifier
required
string (ExternalIdentifier)

Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

Responses

Request samples

Content type
application/json
{
  • "totalAmount": 9999,
  • "mediatorFee": 0,
  • "currency": "BRL",
  • "withdrawInfo": {
    },
  • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Raise a request to withdraw an amount from MATERA Meios de Pagamento to a common Bank.

Using this service an integrator can raise a transaction for withdraw values from a MATERA Meios de Pagamento account to a common bank account, both accounts need to have the same Tax Identifier linked to them.
Note: For cashouts of the InstantPayment type, the payer account details are retrieved based on the registered account information. The accountType attribute of the payer account, as informed to the SPI in the Pix arrangement, is mapped as follows

  • ORDINARY → TRAN (payment account)
  • OVERDRAFT_PROTECTED → CACC (checking account)
  • COMMON → CACC (checking account)
  • UNLIMITED_ORDINARY → TRAN (payment account)

Authorizations:
oAuth2ClientCredentials
path Parameters
branch
required
integer

branch identification

account
required
integer <int64>

account identification

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the concatenation of the fields, in the following order: totalAmount(integer part), and branch and accountNumber, and 1 - if is BankTransfer type: bank and branch and account destination or; 2 - if is Boleto type: barcode or typeableLine; 3 - if is InstantPayment, it should also include withdrawInfo.instantPayment.recipient.pspId and withdrawInfo.instantPayment.recipient.taxIdentifier.taxId.

Request Body schema: application/json
required

Request body.

totalAmount
required
number

The value, before applying any discounts or interest, when the withdrawType is Boleto and Provider is CELCOIN. [interestAmount, fineAmount,discounts]

This field will be used after 2021-11-28 (required for book of messages 5.03.1 and beyond)

How to fill in the field
totalAmount Payment amount Option 1 - QR Code Reading (decoding service)
  * Static QR Code - if it has the staticQrcodeData.value field, otherwise the value informed by the user in the channel must be used.
  * Dynamic QR Code billing due date - dynamicQrcodeData.payload.value.final

Dynamic QR Code for immediate billing
  * Regular charge - When the dynamicQrcodeData.payload.valor.retirada structure is not returned, use the value of the field dynamicQrcodeData  .payload.valor.original.
If the dynamicQrcodeData.payload.value.modidadeAlteracao field is returned, the channel must allow the user to enter the Pix value.
  * Pix billign cashout - If the purpose of the transaction is Pix Cashout (transactionPurpose field equal to OTHR), the field value must be the same informed in the TransactionValuesDetails.cashValue.
  * Pix billing change of money - If the purpose of the transaction is Pix change of money (transactionPurpose field equal to GSCB), the value field must be the sum of the transactionValue + cashValue.

Option 2 - manual entry by user channel

mediatorFee
number
currency
required
string
Enum: "BRL" "USD" "EUR" "AUD" "CAD" "GBP"

ISO 4217 de 3 letras

required
object (WithdrawInfo)

Withdraw information. Note: ReloadPrepaid and External types have been removed. The external object has also been removed from the documentation.

externalIdentifier
required
string (ExternalIdentifier)

Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

Responses

Request samples

Content type
application/json
{
  • "totalAmount": 9999,
  • "mediatorFee": 0,
  • "currency": "BRL",
  • "withdrawInfo": {
    },
  • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Query withdraw transaction.

This service enables to query withdraw transactions by transactionId.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string

TransactionId to be queried

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the concatenation of the fields, in the following order: HTTP method in lower case, :, endpoint url and transactionId.

Example: get:/v1/accounts/withdraw/{transactionId}

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Return of completing transactions from external system

This endpoint is for completing transactions carried out in an external system to the Matera platform.

Authorizations:
oAuth2ClientCredentials
header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the lower case http method name followed by the request path and externalId, using : as a separator. E.g. post:/v2/callback/withdraw:F5DB4E89-E0B0-A1D4-891C-E5A076F1E43D

Request Body schema: application/json
required

Request body.

externalId
required
string
status
required
string
Enum: "COMPLETED" "ERROR"
object

Used only when status is COMPLETED

object

Used and required only when status is ERROR

Responses

Request samples

Content type
application/json
{
  • "externalId": "C1A1E105-BC3A-B5D3-6CC3-E03F26BB8487",
  • "status": "COMPLETED",
  • "report": {
    },
  • "error": {
    }
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Returns an instant payment received.

Authorizations:
oAuth2ClientCredentials
path Parameters
accountId
required
string
transactionId
required
string
header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the concatenation of amount(integer part), accountId, transactionId and returnReasonCode.

Request Body schema: application/json
required

Request body.

externalIdentifier
string (ExternalIdentifier)

Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

amount
required
number <= 99999999999999.98

Return amount.

additionalInformation
string <= 140 characters

Additional information in free form.

returnReasonCode
required
string

Return reason code. The return code must be obtained through the list of reasons returned through the service "GET /v1/instant-payments/{country}/return-codes"

mediatorFee
number >= 0

If it is a blocked Return, mediatorFee will be ignored and not charged.

Responses

Request samples

Content type
application/json
{
  • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83",
  • "amount": 1637.13,
  • "additionalInformation": "Devolução do excedente",
  • "returnReasonCode": "AM09",
  • "mediatorFee": 0
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Deposits

Raise a request to deposit an amount into an account.

Synchronously/Assynchronously (according to the parameterization) handle requests for deposits.

Authorizations:
oAuth2ClientCredentials
header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the concatenation of the fields, in the following order:
1 - If it's a CreditCard transaction type: paymentInfo.creditCard.creditCardToken
2 - recipients.account.branch and recipients.account.account or recipients.account.accountId
3 - recipients.amount (integer part)
4 - If it's a InstantPayment transaction type: paymentInfo.instantPayment.alias

Request Body schema: application/json
required

Request body.

required
object (PaymentInfoDeposit)

Payment information. Note: billingAddress, creditCard, directDebit, mobilePayment, futureDate, mode, authorizationCode and billingNumber fields have been removed from the documentation.

Array of objects (DeposityRecipient)

List of Recipient

externalIdentifier
string (ExternalIdentifier)

Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

callbackAddress
string

Responses

Request samples

Content type
application/json
{
  • "paymentInfo": {
    },
  • "recipients": [
    ],
  • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83",
  • "callbackAddress": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Perform a balance unlock.

Perform balance unlock. The unlocking value is obtained through the transactionId.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string

Transaction to be full unlocked

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the lower case http method name followed by the request path, using : as a separator. E.g. delete:/v1/accounts/deposits/123456/unlock

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Query deposit.

This service enables to query deposits by transactionId.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string

TransactionId to be queried

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the concatenation of the fields, in the following order: HTTP method in lower case, :, endpoint url and transactionId

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Query account deposits.

This service enables to query account deposits. This query could be filtered by transaction type, status and a date range.

Authorizations:
oAuth2ClientCredentials
path Parameters
accountId
required
string

Account for retrieve deposits

query Parameters
startDate
required
string

Used to indicate the starting date from date range query. Format: yyyy-MM-dd

endDate
required
string

Used to indicate the ending date from date range query. Format: yyyy-MM-dd

status
string

Transaction status (APPROVED/CREATED/CANCELED)

transactionType
required
string

Transaction type (Boleto/InstantPayment)

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Raise a full refund for one transaction.

Functionality responsible for reversing transactions involved in the Deposits API. Transactions involved are CreditCard and External.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string
Example: 33ec78fa-c80c-4f59-85df-3e51166aab34

Identifier of the transaction that will be subject to reversal

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the lower case http method name followed by the request path.

Request Body schema: application/json
reason
string

Cancellation message.

externalIdentifier
required
string (ExternalIdentifier)

Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

Responses

Request samples

Content type
application/json
{
  • "reason": "string",
  • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Pending Transaction Callback

Updates transaction status, may be used to receive returned information related to Boleto and Direct Debit.

It was designed to be the point of interaction with billing systems, after each update the external system should send an update with the new status.

Authorizations:
oAuth2ClientCredentials
header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

A valid OAuth2 access token.

Transaction-Hash
required
string

The hash for this transaction is based on the concatenation of the fields, in the following order: receivedAmount (integer part), transactionType, billingIdentifier.transactionId, status, recipient.accountId, recipient.amount (integer part)

Request Body schema: application/json
required

Request body.

receivedAmount
number

The received amount must not be informed for transactions with a canceled status.

object (BillingIdentifier)
status
required
string
Enum: "Fulfilled" "Partial" "Unfinished" "Canceled" "Overfilled"

The status of the transaction. The status must be informed. For status Fulfilled the value of receivedAmount must be the same of recipient.amount . For status Canceled the value of receivedAmount must be null. For status Partial and Unfinished the value of receivedAmount must be less than recipient.amount. For status Overfilled the value of receivedAmount must be greater than recipient.amount.

object (Recipient)

Recipient information. Note: account.branch, account.account, account.accountType, account.mobilePhone, order, historyCodeSender, historyCodeRecipient, historyCodeFeeRecipient, historyCodeFeeMediator, senderComment fields have been removed from the documentation. Currency is restricted to BRL only.

effectiveDate
string <date>
transactionType
required
string
Enum: "DirectDebit" "Boleto"
Array of objects (ExtraFee)
contract
string
rejectionReason
string

The rejection reason must be informed when the transaction is returned with a canceled status.

externalIdentifier
string (ExternalIdentifier)

Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

Responses

Request samples

Content type
application/json
{
  • "receivedAmount": 5.88,
  • "billingIdentifier": {
    },
  • "status": "Fulfilled",
  • "recipient": {
    },
  • "effectiveDate": "2019-08-24",
  • "transactionType": "DirectDebit",
  • "extraFees": [
    ],
  • "contract": "1661354488464",
  • "rejectionReason": "Registration canceled due to non-existent zip code",
  • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Updates transaction status, may be used to receive returned information related to Boleto and Direct Debit.

It was designed to be the point of interaction with billing systems, after each update the external system should send an update with the new status.
To control that the transaction is unique, this API uses idempotency through the externalIdentifier field.

  • The fields for the attributes billingIdentifier and recipient.account cannot be informed together in the same request.
  • For the recipient.account attribute only one argument (recipient.account.accountId or recipient.account.branch/recipient.account.account or recipient.account.mobilePhone) must be informed.

    • Authorizations:
    oAuth2ClientCredentials
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the concatenation of the fields, in the following order: receivedAmount (integer part), transactionType, billingIdentifier.transactionId (if not informed, ignore), status,

  • recipient.account.accountId or
  • recipient.account.branch and recipient.account.accountNumber or
  • recipient.account.mobilePhone.phoneNumber (if not informed recipient.account fields, ignore),
    recipient.amount (integer part)

    • Request Body schema: application/json
    required

    Request body.

    receivedAmount
    number

    The received amount must not be informed for transactions with a canceled status.

    object (BillingIdentifier)
    status
    required
    string
    Enum: "Fulfilled" "Partial" "Unfinished" "Canceled" "Overfilled"

    The status of the transaction. The status must be informed. For status Fulfilled the value of receivedAmount must be the same of recipient.amount . For status Canceled the value of receivedAmount must be null. For status Partial and Unfinished the value of receivedAmount must be less than recipient.amount. For status Overfilled the value of receivedAmount must be greater than recipient.amount.

    object (Recipient)

    Recipient information. Note: account.branch, account.account, account.accountType, account.mobilePhone, order, historyCodeSender, historyCodeRecipient, historyCodeFeeRecipient, historyCodeFeeMediator, senderComment fields have been removed from the documentation. Currency is restricted to BRL only.

    effectiveDate
    string <date>
    transactionType
    required
    string
    Enum: "DirectDebit" "Boleto"
    Array of objects (ExtraFee)
    contract
    string
    rejectionReason
    string

    The rejection reason must be informed when the transaction is returned with a canceled status.

    externalIdentifier
    required
    string (ExternalIdentifier)

    Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

    Responses

    Request samples

    Content type
    application/json
    {
    • "receivedAmount": 5.88,
    • "billingIdentifier": {
      },
    • "status": "Fulfilled",
    • "recipient": {
      },
    • "effectiveDate": "2019-08-24",
    • "transactionType": "DirectDebit",
    • "extraFees": [
      ],
    • "contract": "1661354488464",
    • "rejectionReason": "Registration canceled due to non-existent zip code",
    • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83"
    }

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Transactions

    Retrieves a list of transactions

    Given an account ID, returns a list of transactions according to the start and end dates, transaction status and one or more payment types

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string

    Eg: '6E341590-CC18-11EA-8B6E-0800200C9A66'

    query Parameters
    begin
    string <date>

    Date of begin of search. Eg: '2020-10-01'

    end
    string <date>

    Date of end of search. Eg: '2021-10-01'

    status
    string
    Enum: "CREATED" "APPROVED" "REJECTED" "CANCELING" "CANCELED" "PARTIAL" "EXPIRED" "TIMEOUT" "OVERFILLED" "UNFINISHED" "ERROR" "FATAL_ERROR" "AUTHORIZED" "CAPTURED"

    Select the Status of the transactions to be fetched

    paymentTypes
    Array of strings

    List of payment types separated by comma. Eg: 'Boleto, Deposit, AccountCreated'

    endToEndId
    string

    Unique identifier of the transaction generated by the system when performing the DICT query.

    hashNextPage
    string
    Example: hashNextPage=eyJpZCI6IlRSQU5TQUNUSU9OX0lENDgiLCJhY2NvdW50SWQiOiJBQ0NPVU5UX0lEIiwiZGF0ZSI6MTY0MTU1NjQ5OTI1Mn0=

    If was the first request, should not informed. From the second request the previous request will return the hash.

    pageLimit
    integer <int32> [ 1 .. 2147483646 ]
    Example: pageLimit=50

    Size of the page

    pageOrder
    string
    Enum: "DESC" "ASC"

    Order of records on page

    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path, using : as a separator. E.g. get:/v2/accounts/1CDD2D73-E641-8CF6-51AC-065F01CD7422/transactions

    Responses

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Retrieves a specific transaction

    Given an account ID and transaction ID, returns the corresponding transaction

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string

    Eg: '6E341590-CC18-11EA-8B6E-0800200C9A66'

    transactionId
    required
    string

    Eg: '62C219A0-CC27-11EA-8B6E-0800200C9A66'

    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path, using : as a separator. E.g. get:/v2/accounts/1CDD2D73-E641-8CF6-51AC-065F01CD7422/transactions/CDD2D73-E641-8CF6-51AC-065F01CD742

    Responses

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    It keeps going with the account creation process at MATERA Meios de Pagamento based on validation data via external system.

    It was designed to be the point of integration with MATERA Meios de Pagamento to keep going the account creation process based on the validation data via external system.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    transactionId
    required
    string

    Eg: '62C219A0-CC27-11EA-8B6E-0800200C9A66'

    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path, using : as a separator. E.g. post:/v1/transactions/28866001-233A-33E0-4BB0-0DB57ED32B94/validationBureauCallback

    Request Body schema: application/json
    required

    Request body.

    required
    object (ExternalApprovalMetadataRequest)
    required
    object (ExternalApprovalResults)

    Responses

    Request samples

    Content type
    application/json
    {
    • "metadata": {
      },
    • "results": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Instant Payments

    Service responsible for non-priority payments

    Scheduled financial operations, billing with due date and automatic debit. The system does not perform these operations, it just processes with non-priority. The caller is responsible for scheduling. This resource only accept 100 register per request.

    Authorizations:
    oAuth2ClientCredentials
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    It must be the concatenation of the result of each item [integer part of totalAmount] + [6 first digits of externalIdentifier] + [6 first digits of recipient.taxIdentifier.taxId]

    Request Body schema: application/json
    Array of objects (instantPaymentNonPriority) [ 1 .. 100 ] items

    Responses

    Request samples

    Content type
    application/json
    {
    • "instantPaymentNonPriority": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    List of PSPs.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    country
    required
    string
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Responses

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    List of codes and reasons for returning instant payments.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    country
    required
    string
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Responses

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Boleto

    Returns data from a specific boleto

    Given a boleto barccode/typeable line, payment date, expected face value and paying account, returns data about that boleto records and payment values, including interest and fines.

    Authorizations:
    oAuth2ClientCredentials
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash is calculated by the boleto barcode/typeable line

    Request Body schema: application/json
    required

    Request body.

    barcode
    string
    typeableLine
    string
    object (AccountIdentifier)

    Responses

    Request samples

    Content type
    application/json
    {
    • "barcode": "string",
    • "typeableLine": "string",
    • "payingAccount": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Bills

    Returns data from a specific boleto

    Given a boleto barcode/typeable line, payment date, expected face value and paying account, returns data about that boleto records and payment values, including interest and fines.

    Authorizations:
    oAuth2ClientCredentials
    query Parameters
    document
    required
    string

    Barcode or typeableline

    accountId
    string

    Account identifier. Required for querying boleto information through Matera DDA system.

    branchNumber
    string

    Branch number. Required for querying boleto information through Matera DDA system.

    accountNumber
    string

    Account number. Required for querying boleto information through Matera DDA system.

    phoneNumber
    string

    Phone number. Required for querying boleto information through Matera DDA system.

    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash is calculated by the boleto barcode/typeable line

    Responses

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Wallet

    Cards linked to an account

    Returns a list of cards linked to the account

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path, using : as a separator. E.g. get:/v1/wallet/22E4EFFD-AF54-EB08-0C4C-1C062D17086C/card

    Responses

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Add a new card to users wallet

    This service creates or updates a user's account by linking a new card

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path, and externalIdentifier, using : as a separator. E.g. post:/v1/wallet/22E4EFFD-AF54-EB08-0C4C-1C062D17086C/card:1CDD2D73-E641-8CF6-51AC-065F01CD7422

    Request Body schema: application/json
    required

    Request body.

    externalIdentifier
    required
    string (ExternalIdentifier)

    Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

    cardType
    required
    string
    Enum: "VISA" "MASTER" "VEGAS" "AMEX" "DINERS" "ELO" "VR"
    creditCardToken
    required
    string

    Responses

    Request samples

    Content type
    application/json
    {
    • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83",
    • "cardType": "VISA",
    • "creditCardToken": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Update alias to credit card.

    This service updates a alias to credit card

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    shortId
    required
    string
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on accountId, shortId and Alias if not null

    Request Body schema: application/json
    required
    alias
    string

    Responses

    Request samples

    Content type
    application/json
    {
    • "alias": "string"
    }

    Requests a new prepaid card.

    This service requests a new card for user account.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string

    Account identifier

    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on externalIdentifier and accountId

    Request Body schema: application/json
    required

    Request body.

    required
    object (Endereco)
    motherName
    string
    externalIdentifier
    required
    string (ExternalIdentifier)

    Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

    Responses

    Request samples

    Content type
    application/json
    {
    • "mailAddress": {
      },
    • "motherName": "string",
    • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83"
    }

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Delete a card from users wallet

    This service deletes a card from users wallet.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    creditCardToken
    required
    string

    CreditCardToken to be deleted

    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path, using : as a separator. E.g. delete:/v1/wallet/card/1CDD2D73-E641-8CF6-51AC-065F01CD7422

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Wallet card balance

    Retrieve the balance of card according account id and Card identifier

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    Example: CCAb9323-E595-5ed9-a389-0938333b6fb1

    Account Identification

    shortId
    required
    string
    Example: 1661354488464

    Card identifier

    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path, using : as a separator. E.g. get:/v1/wallet/22E4EFFD-AF54-EB08-0C4C-1C062D17086C/card/1661354488464/balance

    Responses

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Wallet card statement

    Retrieve the statement of card according account id and Card identifier

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    Example: CCAb9323-E595-5ed9-a389-0938333b6fb1

    Account Identification

    shortId
    required
    string
    Example: 979836f16500447da4bb791f1b1d1941

    Card identifier

    query Parameters
    startDate
    string <date>
    Example: startDate=2022-08-01

    Filter with start date

    endDate
    string <date>
    Example: endDate=2022-08-30

    Filter with final date

    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path, using : as a separator. E.g. get:/v1/wallet/22E4EFFD-AF54-EB08-0C4C-1C062D17086C/card/979836f16500447da4bb791f1b1d1941/statement

    Responses

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Wallet card withdraw

    Withdraws some amount from a specific card and adds that amount to the selected account.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    Example: CCAb9323-E595-5ed9-a389-0938333b6fb1

    Account Identification

    shortId
    required
    string
    Example: 979836f16500447da4bb791f1b1d1941

    Card identifier

    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path, amount(integer part) and externalIdentifier, using : as a separator. E.g. post:/v1/wallet/22E4EFFD-AF54-EB08-0C4C-1C062D17086C/card/979836f16500447da4bb791f1b1d1941/withdraw:10:25227177660

    Request Body schema: application/json
    required

    Request body.

    amount
    required
    number > 0.01

    Amount for withdraw.

    currency
    required
    string
    Enum: "BRL" "USD" "EUR" "AUD" "CAD" "GBP"

    Value's currency following ISO 4217 of three letters.

    externalIdentifier
    required
    string (ExternalIdentifier)

    Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

    Responses

    Request samples

    Content type
    application/json
    {
    • "amount": 1.25,
    • "currency": "BRL",
    • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83"
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Wallet prepaid card funds

    Raises a request to add funds to a prepaid card.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    Example: CCAb9323-E595-5ed9-a389-0938333b6fb1

    Account Identification

    shortId
    required
    string
    Example: 979836f16500447da4bb791f1b1d1941

    Card identifier

    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path, value(integer part) and externalIdentifier, using : as a separator. E.g. post:/v1/wallet/22E4EFFD-AF54-EB08-0C4C-1C062D17086C/prepaid/card/979836f16500447da4bb791f1b1d1941/funds:100:15227187460

    Request Body schema: application/json
    required

    Request body.

    value
    required
    number ( 0.01 .. 9999999999999 ]

    Amount to be added to the prepaid card.

    externalIdentifier
    required
    string (ExternalIdentifier)

    Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

    currency
    required
    string
    Enum: "BRL" "USD" "EUR" "AUD" "CAD" "GBP"

    Value's currency following ISO 4217 of three letters.

    Responses

    Request samples

    Content type
    application/json
    {
    • "value": 100.25,
    • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83",
    • "currency": "BRL"
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Cashin

    Makes a deposit (TED or TEF) to the recipient's account.

    Synchronously handle requests for cash in.

    Authorizations:
    oAuth2ClientCredentials
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the concatenation of the fields, in the following order: amount (integer part) and recipient.taxIdentifier.taxId

    Request Body schema: application/json
    required

    Request body.

    externalIdentifier
    required
    string (ExternalIdentifier)

    Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

    type
    string
    Enum: "TED" "TEF"

    CashIn Type

    amount
    required
    number

    CashIn request amount

    currency
    required
    string
    Enum: "BRL" "USD" "EUR" "AUD" "CAD" "GBP"

    Value's currency following ISO 4217 of three letters. Ex. "BRL" corresponds to Brazilian reais.

    registrationDate
    string <date>

    Date of registration in 'yyyy-mm-dd' format

    operationTimestamp
    string <date-time>

    Date and time of operation in 'yyyy-mm-ddTHH:mm:ssZ' format

    object (CashInOrigin)
    required
    object (CashInRecipient)

    Responses

    Request samples

    Content type
    application/json
    {
    • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83",
    • "type": "TED",
    • "amount": "59.90",
    • "currency": "BRL",
    • "registrationDate": "2024-02-23",
    • "operationTimestamp": "2024-02-23T10:10:00-03:00",
    • "origin": {
      },
    • "recipient": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Push Notifications

    Send push notifications

    This service sends push notifications to account mobile phone.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string

    Account identifier

    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on accountId

    Request Body schema: application/json
    required

    Request body.

    object (Message)

    Responses

    Request samples

    Content type
    application/json
    {
    • "message": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Side Account

    Create a new side account at MATERA Meios de Pagamento.

    This service creates a side account linked to a main account. Side account can be used for cashback, bonus, rewards, points, loyalty or even fund (where part of the amount is set aside separately from the main account). Only one side account can be created per classification for each main account. The id of the created side account will be your sideAccountId returned in response from this service. Operations on this side account must use this sideAccountId received.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string

    Main account identifier

    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the concatenation of (externalIdentifier) and (classificationId) and (accountId)

    Request Body schema: application/json
    required

    Request body.

    externalIdentifier
    required
    string (ExternalIdentifier)

    Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

    classificationId
    required
    string

    Responses

    Request samples

    Content type
    application/json
    {
    • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83",
    • "classificationId": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Inserts a new credit to a side account.

    This service inserts a new credit into a side account. This credit (money, bonus, rewards, points, etc) may have specific history codes. It can also be used for deposit transactions.

    Authorizations:
    oAuth2ClientCredentials
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the concatenation of the fields, in the following order: externalIdentifier and recipient.sideAccountId and recipient.amount (integer part) and recipient.historyCode

    Request Body schema: application/json
    required

    Request body.

    required
    Array of objects (CreditSideAccountTransactionRecipient)

    List of Recipient

    orderId
    string
    externalIdentifier
    required
    string (ExternalIdentifier)

    Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

    Responses

    Request samples

    Content type
    application/json
    {
    • "recipients": [
      ],
    • "orderId": "string",
    • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83"
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Inserts a new debit to a side account.

    This service inserts a new debit into a side account. This debit (money, bonus, rewards, points, etc) may have specific history codes. It can also be used for withdraw transactions.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    sideAccountId
    required
    string
    accountId
    required
    string
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the concatenation of the fields, in the following order: externalIdentifier, totalAmount(integer part) and historyCode.

    Request Body schema: application/json
    required

    Request body.

    externalIdentifier
    required
    string (ExternalIdentifier)

    Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

    totalAmount
    required
    number
    comment
    string
    historyCode
    string

    Responses

    Request samples

    Content type
    application/json
    {
    • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83",
    • "totalAmount": 0,
    • "comment": "string",
    • "historyCode": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Query side account statement.

    This service enables the query to side account statement.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    sideAccountId
    required
    string
    query Parameters
    start
    string <date>
    ending
    string <date>
    dateType
    string
    Default: "ENTRY"
    Enum: "ENTRY" "REALIZATION"
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path, using : as a separator. E.g. get:/v1/accounts/13E700E0-2372-A23A-8D90-57ACBEBDE46A/side-account/CDF2BC48-24FB-3AB3-0018-3FDA47D5BB0C/statement

    Responses

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Query side account balance.

    This service enables the query to side account balance.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    sideAccountId
    required
    string
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path, using : as a separator. E.g. get:/v1/accounts/13E700E0-2372-A23A-8D90-57ACBEBDE46A/side-account/CDF2BC48-24FB-3AB3-0018-3FDA47D5BB0C/balance

    Responses

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Full refund of transaction.

    Raise a full refund for one transaction.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    transactionId
    required
    string

    Transaction to be full refunded

    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path, using : as a separator. E.g. delete:/v1/accounts/side-account/cash-in/external/CDF2BC48-24FB-3AB3-0018-3FDA47D5BB0C

    Responses

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Full refund of transaction.

    Raise a full refund for one transaction.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    transactionId
    required
    string

    Transaction to be full refunded

    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path, using : as a separator. E.g. delete:/v1/accounts/side-account/cash-out/external/CDF2BC48-24FB-3AB3-0018-3FDA47D5BB0C

    Responses

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Raise a new payment from a side account.

    Processes a new payment transaction between side accounts using the sender account balance as fund source. Synchronously handle requests.

    Authorizations:
    oAuth2ClientCredentials
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the concatenation of the fields, in the following order: sender.sideAccount.sideAccountId, totalAmount (integer part), recipient.sideAccount.sideAccountId and recipient.amount (integer part). E.g.:

    sender.sideAccount.sideAccountId: 77E09007-CDDF-47AA-0425-25BA3960178E totalAmount: 10.5 recipient.sideAccount.sideAccountId: 4E749CC9-39D6-50DA-F636-8106240DB64E recipient.amount: 10.5

    Transaction-Hash calculated based on: 77E09007-CDDF-47AA-0425-25BA3960178E104E749CC9-39D6-50DA-F636-8106240DB64E10

    Request Body schema: application/json
    required

    Request body.

    externalIdentifier
    required
    string (ExternalIdentifier)

    Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

    totalAmount
    required
    number
    required
    object (SideAccountSender)
    required
    Array of objects (SideAccountRecipient)

    List of Recipient

    Responses

    Request samples

    Content type
    application/json
    {
    • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83",
    • "totalAmount": 0,
    • "sender": {
      },
    • "recipients": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Raise a new transfer from a side account.

    Processes a new transfer transaction between side accounts using the sender account balance as fund source. Synchronously handle requests.

    Authorizations:
    oAuth2ClientCredentials
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the concatenation of the fields, in the following order: sender.sideAccount.sideAccountId, totalAmount (integer part), recipient.sideAccount.sideAccountId and recipient.amount (integer part). E.g.:

    sender.sideAccount.sideAccountId: 77E09007-CDDF-47AA-0425-25BA3960178E totalAmount: 10.5 recipient.sideAccount.sideAccountId: 4E749CC9-39D6-50DA-F636-8106240DB64E recipient.amount: 10.5

    Transaction-Hash calculated based on: 77E09007-CDDF-47AA-0425-25BA3960178E104E749CC9-39D6-50DA-F636-8106240DB64E10

    Request Body schema: application/json
    required

    Request body.

    externalIdentifier
    required
    string (ExternalIdentifier)

    Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

    totalAmount
    required
    number
    required
    object (SideAccountSender)
    required
    Array of objects (SideAccountRecipient)

    List of Recipient

    Responses

    Request samples

    Content type
    application/json
    {
    • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83",
    • "totalAmount": 0,
    • "sender": {
      },
    • "recipients": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Perform a side account balance lock.

    This service perform a side account balance lock according to the amount reported.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    sideAccountId
    required
    string

    Side account identifier.

    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the concatenation of amount (integer part) and sideAccountId.

    Request Body schema: application/json
    required

    Request body.

    externalIdentifier
    required
    string (ExternalIdentifier)

    Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

    amount
    required
    number

    Side account balance amount that should be blocked.

    reasonIdentifier
    required
    integer <int32>

    Reason why the side account balance is being blocked.

    comment
    string

    Free description to be returned in the side account statement.

    Responses

    Request samples

    Content type
    application/json
    {
    • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83",
    • "amount": 0,
    • "reasonIdentifier": 0,
    • "comment": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Perform a side account balance unlock.

    This service perform a side account balance unlock. The unlocking value is obtained through the transactionId.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    sideAccountId
    required
    string

    Side account identifier.

    transactionId
    required
    string

    Balance lock TransactionId.

    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the concatenation of amount (integer part) and sideAccountId.

    Request Body schema: application/json
    required

    Request body.

    externalIdentifier
    required
    string (ExternalIdentifier)

    Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

    amount
    required
    number [ 0.01 .. 9999999999999 ]

    Side account balance amount that should be unblocked.

    comment
    string

    Free description to be returned in the side account statement.

    Responses

    Request samples

    Content type
    application/json
    {
    • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83",
    • "amount": 1986.12,
    • "comment": "free description"
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Aliases

    Alias registration.

    The registration alias is needed for receiving a Instant Payment in practical way. With the alias, instead of more than one informations to identify the account, the user can just inform the registration alias. It is possible to register 4 kinds of alias:

    • Tax Identifier
    • Mobile phone with country code. Ex: +5544997701000
    • E-mail address
    • Virtual Payment Address

    Each alias can only be linked to one account. Each natural person can register until 5 alias to the same account. Each legal person can register until 20 alias to the same account.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path and alias.name, using : as a separator. E.g. post:/v1/accounts/1CDD2D73-E641-8CF6-51AC-065F01CD7422/aliases:email@example.com

    Request Body schema: application/json
    required

    Request body.

    required
    object (AliasRequestAlias)
    externalIdentifier
    required
    string (ExternalIdentifier)

    Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

    Responses

    Request samples

    Content type
    application/json
    {
    • "alias": {
      },
    • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83"
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Query of alias associated with user.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    query Parameters
    aliasStatus
    string
    Enum: "IDENTITY_VALIDATION_PENDING" "CLEARING_REGISTRATION_PENDING" "ACTIVE" "EXCLUDED" "PENDING_DELETION" "REJECTED" "EXPIRED" "INVALID_KEY" "PENDING_PORTABILITY_CONFIRMATION" "PENDING_CLAIM_CONFIRMATION" "DONATED_FOR_PORTABILITY" "PORTABILITY_REQUESTED" "USER_CONFIRMATION_PENDING_PORTABILITY" "PENDING_PORTABILITY_DICT" "AWAITING_RETURN_PSP_DONOR" "UNSUCCESSFUL_PORTABILITY" "CANCEL_PORTABILITY_REQUEST" "CONFIRM_CLAIMING_PORTABILITY" "SUCCESSFUL_PORTABILITY" "PENDING_CLAIM_DICT" "CLAIM_AWAITING_RETURN_PSP_DONOR" "PENDING_VALIDATION_COMPLETE_CLAIM" "SUCCESSFUL_CLAIM" "UNSUCCESSFUL_CLAIM" "CANCEL_CLAIM_REQUEST" "OWNERSHIP_REQUESTED" "USER_KEY_OWNERSHIP_VALIDATION_PENDING" "DONOR_PSP_KEY_CONFIRMED" "DONOR_PSP_KEY_UNCONFIRMED" "CLAIM_RESOLUTION_PERIOD_CLOSED" "DONATED_BY_CLAIM" "CANCEL_PSP_DONOR_OWNERSHIP_CLAIM_ORDER" "PENDING_UPDATE" "PENDING_COMPLETE_CLAIM_DICT" "CANCEL_DONOR_CLAIM_REQUEST"
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Responses

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Query account data associated with the alias.

    Gets the current information about an Pix alias.

    The query of aliases is subject to the request rate-limiting policy, for this reason, it must be used when there is an intention to make a payment.

    Through the optional parameter, IncludeStatistics, it is possible to indicate whether anti-fraud counter information should be included in the response.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string

    Account ID related to the alias.

    country
    required
    string

    Country in which that alias belongs.

    alias
    required
    string <= 77 characters
    Example: example@matera.com

    Valid Pix alias that requires research.

    query Parameters
    includeStatistics
    boolean
    Default: false
    Example: includeStatistics=true

    Includes anti-fraud data in the response, returning the values in the personStatistics and aliasStatistics fields.

    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    X-EndToEndId
    string

    This field receives an EndToEndId for key queries in order to carry out payment flows within the scope of Open Finance. If the field is null, the system will use the usual buckets for querying.

    Responses

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Delete alias.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    alias
    required
    string
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path, using : as a separator. E.g. delete:/v1/accounts/1CDD2D73-E641-8CF6-51AC-065F01CD7422/aliases/email@matera.com

    deletionReason
    string (AliasDeletionReason)
    Value: "USER_REQUESTED"
    Example: USER_REQUESTED

    Reason for alias exclusion. If the reason is not provided, the USER_REQUESTED (Request made by the user) value will be used.

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Alias update

    Updates PIX key (alias) information based on account data. The behavior depends on the key type.

    For EVP Keys: Updates to all data (owner, branch, and account) are permitted using only the RFB_VALIDATION or BRANCH_TRANSFER reasons. Both reasons will perform a full update.

    For Other Key Types: The RFB_VALIDATION reason updates only the owner's name and trade name.

    Other reasons, such as BRANCH_TRANSFER or USER_REQUESTED, will update both the owner's data and account data.

    Compatibility and Reasons Table:

    Key Type Update Compatible Allowed Reason (Reason Type)
    CPF ✓ ALL
    CNPJ ✓ ALL
    PHONE ✓ ALL
    EMAIL ✓ ALL
    EVP ✓ RFB_VALIDATION/BRANCH_TRANSFER
    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    alias
    required
    string

    The addressing alias identification

    accountId
    required
    string
    Example: CCAb9323-E595-5ed9-a389-0938333b6fb1

    Account Identification

    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path and action, using colon(:) as a separator.

    E.g. post:/v1/accounts/xyz/aliases/key@email.com/update:update

    Request Body schema: application/json
    externalIdentifier
    required
    string (ExternalIdentifier)

    Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

    reason
    required
    string (AliasUpdateReason)
    Enum: "USER_REQUESTED" "RECONCILIATION" "BRANCH_TRANSFER" "RFB_VALIDATION"

    Operation reason to update alias.

    Responses

    Request samples

    Content type
    application/json
    {
    • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83",
    • "reason": "USER_REQUESTED"
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Alias verification code.

    Confirms the ownership of the alias.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    alias
    required
    string
    accountId
    required
    string
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path, using : as a separator. E.g. post:/v1/accounts/1CDD2D73-E641-8CF6-51AC-065F01CD7422/aliases/email@exemplo.com/otp-validation

    Request Body schema: application/json
    required

    Request body.

    externalIdentifier
    required
    string (ExternalIdentifier)

    Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

    verificationCode
    required
    string

    Verification code sent in the alias inclusion process.

    protocolId
    required
    string

    Alias ownership validation protocol.

    Responses

    Request samples

    Content type
    application/json
    {
    • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83",
    • "verificationCode": "546521",
    • "protocolId": "f541133c-6ef0-49b5-b443-6a1cc7b6b93e"
    }

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Claim alias portability.

    Creates portability claim based on the confirmation sent by the client.

    The table below defines the possibilities for ownership or portability of each key type:

    Compatible? OWNERSHIP PORTABILITY
    TAX_ID ✓
    PHONE ✓ ✓
    EMAIL ✓ ✓
    EVP
    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    alias
    required
    string
    accountId
    required
    string
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path, using : as a separator. E.g. post:/v1/accounts/1CDD2D73-E641-8CF6-51AC-065F01CD7422/aliases/email@matera.com/portability-claims

    Request Body schema: application/json
    required

    Request body.

    confirm
    required
    boolean

    Flag indicating the confirmation to create a portability claim.

    externalIdentifier
    required
    string (ExternalIdentifier)

    Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

    Responses

    Request samples

    Content type
    application/json
    {
    • "confirm": true,
    • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83"
    }

    Response samples

    Content type
    application/json
    {
    • "error": {
      }
    }

    Cancel portability claim.

    Cancel an addressing key portability claim linked to the given key which was opened by the claimer. The portability cancellation processing will be asynchronous and the return will be through the callback.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    alias
    required
    string
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path, using : as a separator. E.g. post:/v1/accounts/1CDD2D73-E641-8CF6-51AC-065F01CD7422/aliases/email@matera.com/cancel-portability-claims

    Request Body schema: application/json
    required

    Request body.

    externalIdentifier
    required
    string (ExternalIdentifier)

    Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

    reason
    required
    string (ClaimCancellationReason)
    Enum: "FRAUD" "USER_REQUESTED" "ACCOUNT_CLOSURE"

    Field indicating the reason of the claim cancellation request.

    Responses

    Request samples

    Content type
    application/json
    {
    • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83",
    • "reason": "FRAUD"
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Confirm/Deny portability.

    Confirm/Deny portability of the given key which is liked to a portability claim.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    alias
    required
    string
    accountId
    required
    string
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path and the field 'confirm' value, using : as a separator. E.g. post:/v1/accounts/1CDD2D73-E641-8CF6-51AC-065F01CD7422/aliases/email@example.com/portability-claim-responses:true

    Request Body schema: application/json
    required

    Request body.

    confirm
    required
    boolean

    Flag indicating the confirmation/deny portability.

    externalIdentifier
    required
    string (ExternalIdentifier)

    Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

    Responses

    Request samples

    Content type
    application/json
    {
    • "confirm": true,
    • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83"
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Creates or completes ownership claim process.

    Creates or completes ownership claim process based on the confirmation sent by the client. It's depends the key status:

    • PENDING_CLAIM_CONFIRMATION - If set confirm = true, will be created key ownership claim process.
    • PENDING_VALIDATION_COMPLETE_CLAIM - If set confirm = true, user will receive verification code by SMS or Email for validate key ownership.

    In both cases, if set confirm = false, the key ownership claim process will cancelled.

    The table below defines the possibilities for ownership or portability of each key type:

    Compatible? OWNERSHIP PORTABILITY
    TAX_ID ✓
    PHONE ✓ ✓
    EMAIL ✓
    EVP
    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    alias
    required
    string
    accountId
    required
    string
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path, using : as a separator. E.g. post:/v1/accounts/1CDD2D73-E641-8CF6-51AC-065F01CD7422/aliases/email@matera.com/ownership-claims

    Request Body schema: application/json
    required

    Request body.

    confirm
    required
    boolean

    Flag indicating the confirmation to create an ownership claim.

    externalIdentifier
    required
    string (ExternalIdentifier)

    Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

    reason
    string (CancellationReason)
    Enum: "FRAUD" "USER_REQUESTED" "ACCOUNT_CLOSURE"

    Field indicating the reason of the claim cancellation request. If confirm = false, the reason attribute must be informed.

    Responses

    Request samples

    Content type
    application/json
    {
    • "confirm": true,
    • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83",
    • "reason": "FRAUD"
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Cancel ownership claim.

    Cancel an ownership claim which was opened by the claimer. The claim cancellation processing will be asynchronous and the return will be through the callback.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    alias
    required
    string
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path, using: as a separator. E.g. post:/v1/accounts/1CDD2D73-E641-8CF6-51AC-065F01CD7422/aliases/example@matera.com/cancel-ownership-claims

    Request Body schema: application/json
    required

    Request body.

    externalIdentifier
    required
    string (ExternalIdentifier)

    Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

    reason
    required
    string (ClaimCancellationReason)
    Enum: "FRAUD" "USER_REQUESTED" "ACCOUNT_CLOSURE"

    Field indicating the reason of the claim cancellation request.

    Responses

    Request samples

    Content type
    application/json
    {
    • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83",
    • "reason": "FRAUD"
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Confirm/Deny ownership of an alias being claimed by another PSP.

    Confirm/Deny ownership of the given alias which is linked to an ownership claim.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    alias
    required
    string
    accountId
    required
    string
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path and the field 'confirm' value, using : as a separator. E.g. post:/v1/accounts/1CDD2D73-E641-8CF6-51AC-065F01CD7422/aliases/email@example.com/ownership-claim-responses:true

    Request Body schema: application/json
    required

    Request body.

    confirm
    required
    boolean

    Flag indicating if the ownership of an alias could be confirmed

    externalIdentifier
    required
    string (ExternalIdentifier)

    Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

    Responses

    Request samples

    Content type
    application/json
    {
    • "confirm": true,
    • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83"
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    QR Codes

    Static QRCode generation.

    Restrictions on field lenghts

    Besides the individual max lengths of the alias.alias, description and withdrawAgent fields, the sum of the lenghts of these fields are subject to rules regarding the overall QRCode lenght. This rule is dependent on which of these fields are present, as follows:

    These fields are also sharing the same space on the Qr Code arrangement of 77 characters, so when using both we have to calculate the max size of them according to the following rule: Max size = 77 - 2(Id of description data) - 2(Size of description data) - Size of the other field (minimum 1).
    For example, to use description 'my info': The alias max size would be 77-2-2-7 = 66 and 66 + 7 = 73 characters.
    Or to use the alias 'carlos@yahoo.com.br': The description info max size would be 77-2-2-19 = 54 and 54 + 19 = 73 characters. 

    <thead>
    <tr>
        <th>description</th>
        <th>withdrawAgent</th>
        <th>Restrictions</th>
    </tr>
</thead>
<tbody>
    <tr>
        <td>Not present</td>
        <td>Not present</td>
        <td><code>alias.alias</code> restricted to 77 characters.</td>
    </tr>
    <tr>
        <td>Present</td>
        <td>Not present</td>
        <td>Sum of lenghts of <code>alias.alias</code> and <code>description</code> restricted to 73
            characters.</td>
    </tr>
    <tr>
        <td>Not present</td>
        <td>Present</td>
        <td><code>alias.alias</code> restricted to 65 characters.</td>
    </tr>
    <tr>
        <td>Present</td>
        <td>Present</td>
        <td>Sum of lenghts of <code>alias.alias</code> and <code>description</code> restricted to 61
            characters.</td>
    </tr>
</tbody>

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path and alias.alias, using : as a separator. E.g. post:/v1/accounts/{accountId}/static-qrcode:email@example.com

    Request Body schema: application/json
    required

    Request body.

    required
    object (QRCodeAliasSpecification)

    Specification for QRCode image alias.

    object (QRCodeImageGenerationSpecification)

    Specification for QRCode image generation.

    amount
    number [ 0.01 .. 9999999999999 ]

    Payment amount. Maximum of 2 fraction digits allowed.

    description
    string <= 72 characters

    Description in free form.

    reference
    string <= 25 characters

    Receivable identifier used by receiver to identify the payment/collection.

    externalIdentifier
    required
    string (ExternalIdentifier)

    Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

    receiverTaxId
    string <= 14 characters

    Receiver Tax Id.

    recurrenceLocation
    string <= 77 characters

    Recurrence Location

    Responses

    Request samples

    Content type
    application/json
    {
    • "alias": {
      },
    • "imageGeneration": {
      },
    • "amount": 0.01,
    • "description": "Some description",
    • "reference": "5874885784584",
    • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83",
    • "receiverTaxId": "90792668000101",
    • "recurrenceLocation": "pix.example.com/rec/2353c790eefb11eaadc10242ac120002"
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    QRCode decoding.

    Authorizations:
    oAuth2ClientCredentials
    header Parameters
    Authorization
    required
    string
    Example: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjoiZXhhbXBsZSJ9.C74hRRU_233iQxVsR-4dZH5OGTZgExJAvOx7kUMJxhY

    A valid OAuth2 access token.

    Transaction-Hash
    required
    string

    The hash for this transaction is based on the lower case http method name followed by the request path and document field, using : as a separator. E.g. post:/v1/qrcode/decoding:00020101021126440014BR.GOV.BCB.PIX0122PSPKEY5204000053039865802BR5913PSPNAME6008BRASILIA6304DFE3

    Request Body schema: application/json
    required

    Request body.

    document
    required
    string <= 1000 characters

    QRCode Plain text Representation

    externalIdentifier
    required
    string (ExternalIdentifier)

    Identifier sent by the API caller, must be unique per transaction and per process. This field is used to control idempotency. If a previously executed transaction is submitted with a different ExternalIdentifier, it will be processed again. In batch processing scenarios, the ExternalIdentifier represents each individual item in the batch, not the entire batch operation.

    dateForPayment
    string <date>

    Desired payment date

    municipalityCode
    string

    Code based on the IBGE Municipality Code Table

    Responses

    Request samples

    Content type
    application/json
    {
    • "document": "00020101021126440014BR.GOV.BCB.PIX0122PSPKEY5204000053039865802BR5913PSPNAME6008BRASILIA6304DFE3",
    • "externalIdentifier": "e91df192-f71a-4e1d-8d6f-a66a0bd6ad83",
    • "dateForPayment": "2019-11-19",
    • "municipalityCode": "4105508"
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Limits

    List Branch Limits Deprecated

    Lists all accounts with established limits in the branch. Available until March 31st.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    branch
    required
    string

    Branch number.

    header Parameters
    Transaction-Hash
    required
    string

    Hash HmacSHA256 (method:path).

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    List Specific Account Limits Deprecated

    Retrieves limits and beneficiaries of a specific account.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    branch
    required
    string

    Branch number.

    account
    required
    string

    Account number.

    header Parameters
    Transaction-Hash
    required
    string

    Hash HmacSHA256. POST = (method:path:amount:limitType). GET = (method:path).

    Responses

    Response samples

    Content type
    application/json
    {
    • "limitId": "string",
    • "branch": "string",
    • "account": "string",
    • "limits": [
      ],
    • "favorites": [
      ]
    }

    Adjust Limits, Add Beneficiary, or Set Night Time Deprecated

    This endpoint performs three distinct functions depending on the limitType sent in the body: 1. Financial value adjustment (DAILY, NIGHTLY, etc). 2. Beneficiary Registration (FAVORED). 3. Night start definition (START_NIGHT_TIME).

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    branch
    required
    string

    Branch number.

    account
    required
    string

    Account number.

    header Parameters
    Transaction-Hash
    required
    string

    Hash HmacSHA256. POST = (method:path:amount:limitType). GET = (method:path).

    Request Body schema: application/json
    required
    One of
    limitType
    required
    string
    Enum: "DAILY" "NIGHTLY" "INSTANT_PAYMENT_CHANGE" "INSTANT_PAYMENT_CHANGE_NIGHTLY"

    Financial limit type to be adjusted.

    amount
    required
    string

    Transaction amount (use dot for cents, e.g., "10.05").

    externalIdentifier
    required
    string

    Unique external identifier.

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "limitType": "NIGHTLY",
    • "amount": "100",
    • "externalIdentifier": "uuid-example"
    }

    Response samples

    Content type
    application/json
    {
    • "transactionId": "string",
    • "account": "string",
    • "externalIdentifier": "string",
    • "amount": "string",
    • "lastUpdate": "string",
    • "status": "string",
    • "favoredId": "string"
    }

    Get limit filtered by Type Deprecated

    Retrieves the status of a specific limit type (e.g., DAILY, NIGHTLY).

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    branch
    required
    string
    account
    required
    string
    limitType
    required
    string
    Enum: "DAILY" "NIGHTLY" "INSTANT_PAYMENT_CHANGE" "INSTANT_PAYMENT_CHANGE_NIGHTLY" "FAVORED"

    The limit type to be consulted.

    header Parameters
    Transaction-Hash
    required
    string

    Hash HmacSHA256 (method:path).

    Responses

    Response samples

    Content type
    application/json
    {
    • "clientValue": 0,
    • "maxValue": "string",
    • "lastUpdate": "string"
    }

    Remove Beneficiary Deprecated

    Removes a beneficiary from the beneficiary list using the favoredId.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    branch
    required
    string
    account
    required
    string
    favoredId
    required
    string

    The beneficiary ID obtained in the listing.

    header Parameters
    Transaction-Hash
    required
    string

    Hash HmacSHA256 (method:path).

    Responses

    Response samples

    Content type
    application/json
    {
    • "transactionId": "string",
    • "account": "string",
    • "externalIdentifier": "string",
    • "amount": "string",
    • "lastUpdate": "string",
    • "status": "string",
    • "favoredId": "string"
    }

    Adjust Limit

    Adjust Limits

    Allows adjusting the transfer limit according to its type and adjusting the start of the night period.

    Authorizations:
    None
    path Parameters
    branch
    required
    string
    Example: {{branch}}
    account
    required
    string
    Example: {{account}}
    header Parameters
    Authorization
    any
    Example: Bearer {{token}}
    Transaction-Hash
    any
    Example: 90724c6b409151b9a08a4f869646e0649889852ed5f1f4f9e288083c73b0846d
    Request Body schema: application/json
    object

    At least one internal field must be provided

    object

    At least one internal field must be provided

    object

    At least one product must be provided

    object

    At least one field must be provided

    object

    Responses

    Request samples

    Content type
    application/json
    {
    • "limits": {
      },
    • "transactionFavoredLimit": {
      },
    • "transactionProductsLimit": {
      },
    • "cashInLimits": {
      },
    • "times": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "limitId": "account-de8783de-c06a-440b-a574-6b3857a0804d",
    • "accountId": "de8783de-c06a-440b-a574-6b3857a0804d",
    • "account": "11111",
    • "branch": "1",
    • "description": "1",
    • "limits": {
      },
    • "cashInLimits": {
      },
    • "transactionFavoredLimit": {
      },
    • "transactionProductsLimit": {
      },
    • "times": {
      },
    • "updatedAt": "2026-02-02T18:54:56.680Z",
    • "createdAt": "2026-01-21T19:11:27.534Z"
    }

    Add favored

    Favored Registration

    Allows registering an account or key as a favored beneficiary

    Authorizations:
    None
    path Parameters
    branch
    required
    string
    Example: {{branch}}
    account
    required
    string
    Example: {{account}}
    header Parameters
    Authorization
    any
    Example: Bearer {{token}}
    Transaction-Hash
    any
    Example: {{Hash}}
    Request Body schema: application/json
    One of
    type
    required
    string
    Enum: "alias" "bankAccount"

    Favored type

    Value: "bankAccount"
    required
    object

    Favored data

    nickname
    string or null

    Favored nickname

    Responses

    Request samples

    Content type
    application/json
    {
    • "type": "alias",
    • "data": {
      },
    • "nickname": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "favoredId": "5e2782f0-6h30-4f65-b020-5bnb4bf4dce8a",
    • "nickname": "DEMO",
    • "account": "111111",
    • "branch": "1",
    • "type": "bankAccount",
    • "data": {
      },
    • "updatedAt": "2026-02-02T19:15:53.668Z",
    • "createdAt": "2026-02-02T19:15:53.668Z",
    • "startDate": "2026-02-03T19:15:53.668Z"
    }

    List Favored beneficiaries for account and Branch

    Lists all accounts with established limits of the branch sent in the GET parameter of the request

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    branch
    required
    string
    Example: {{branch}}
    account
    required
    string
    Example: {{account}}
    query Parameters
    nextToken
    string
    Example: nextToken=eyJhY2NvdW50IjoiNDg3Mzc2IiwiYnJhbmNoIjoiMSIsImZhdm9yZWRJZCI6IjEyNTgyZmIxLWVkZGItNDNlYi05OGY2LWZmYzc5OWFhZjhjYyJ9
    pageSize
    integer
    Example: pageSize=1
    header Parameters
    Authorization
    string
    Example: Bearer {{token}}
    Transaction-Hash
    string
    Example: {{Hash}}

    Responses

    Response samples

    Content type
    application/json
    {
    • "favored": [
      ],
    • "count": 1,
    • "nextToken": "eyJmYXZv1mVkSWQiOiI1YzY3MzY5Yi1jNjBlLTQ4OWM...",
    • "hasMore": true
    }

    Get Favored

    Add favored

    Allows adding favored beneficiaries for the account limits.

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    branch
    required
    string
    Example: {{branch}}
    account
    required
    string
    Example: {{account}}
    favoredId
    required
    string
    Example: {{favoredId}}
    header Parameters
    Authorization
    string
    Example: Bearer {{token}}
    Transaction-Hash
    string
    Example: {{Hash}}

    Responses

    Response samples

    Content type
    application/json
    {
    • "favoredId": "9ce254b1-fe4a-4c67-93b7-5477e8778aea",
    • "account": "487376",
    • "branch": "1",
    • "type": "alias",
    • "data": {
      },
    • "startDate": "2026-01-28T14:54:18.022Z",
    • "updatedAt": "2026-01-27T14:54:18.022Z",
    • "createdAt": "2026-01-27T14:54:18.022Z"
    }

    Remove Favored

    Removes a favored beneficiary from the list. The item is removed by passing the branch, account, and favoredId as parameters.

    The favoredId must be obtained from the FAVORED listing

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    branch
    required
    string
    Example: {{branch}}
    account
    required
    string
    Example: {{account}}
    favoredId
    required
    string
    Example: {{favoredId}}
    header Parameters
    Authorization
    any
    Example: Bearer {{token}}
    Transaction-Hash
    any
    Example: {{Hash}}

    Responses

    Response samples

    Content type
    application/json
    { }

    List Branch Limits

    Lists all accounts with established limits of the branch sent in the GET parameter of the request

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    branch
    required
    string
    Example: {{branch}}
    query Parameters
    nextToken
    string
    pageSize
    string
    header Parameters
    Authorization
    string
    Example: Bearer {{token}}
    Transaction-Hash
    string
    Example: {{Hash}}

    Responses

    Response samples

    Content type
    application/json
    {
    • "limits": [
      ],
    • "count": 10,
    • "nextToken": "eyJicmFuY2giOiIxIiw....",
    • "hasMore": true
    }

    Limit by Branch and Account

    Obtains the limits of a branch and account passed in the GET request parameter

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    branch
    required
    string
    Example: {{branch}}
    account
    required
    string
    Example: {{account}}
    header Parameters
    Transaction-Hash
    any
    Example: {{Hash}}
    Authorization
    any
    Example: Bearer {{token}}

    Responses

    Response samples

    Content type
    application/json
    {
    • "limitId": "account-11111111-1111-1111-1111-111111111111",
    • "accountId": "11111111-1111-1111-1111-111111111111",
    • "account": "000001",
    • "branch": "1",
    • "description": "1 000001",
    • "limits": {
      },
    • "cashInLimits": {
      },
    • "transactionFavoredLimit": {
      },
    • "transactionProductsLimit": {
      },
    • "times": {
      },
    • "updatedAt": "2026-02-02T20:21:28.444Z",
    • "createdAt": "2026-01-21T19:11:27.534Z"
    }

    Income Reports

    Get income reports

    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    Example: {{accountId}}
    query Parameters
    year
    integer
    Example: year=2022
    header Parameters
    Authorization
    string
    Example: Bearer {{token}}
    Transaction-Hash
    string
    Example: {{Hash}}

    HmacSHA256 Hash (method:path).

    x-api-key
    string

    Responses

    Response samples

    Content type
    application/json
    {
    • "contentFile": "string",
    • "mimeType": "string"
    }

    Schedule Payments

    Cancel schedule payment.

    Authorizations:
    None
    path Parameters
    paymentId
    required
    any

    payment identification

    Responses

    Response samples

    Content type
    application/json
    {
    • "accountId": "string",
    • "totalAmount": 0,
    • "mediatorFee": 0,
    • "currency": "str",
    • "scheduleDate": "2019-08-24T14:15:22Z",
    • "externalIdentifier": "string",
    • "recipient": {
      },
    • "typeOrigin": "CHANNEL",
    • "receiverReconciliationIdentifier": "string",
    • "additionalInformation": "string",
    • "qrCodeType": "STATIC",
    • "historyCode": "string",
    • "initiationProcedure": "MANUAL",
    • "initiatingInstitution": "string",
    • "initiationForm": "MANU",
    • "transactionIdentification": "string",
    • "scheduleId": "string",
    • "accountHolderId": "string",
    • "reprocessing": {
      },
    • "history": [
      ],
    • "createdAt": "2019-08-24T14:15:22Z",
    • "updatedAt": "2019-08-24T14:15:22Z",
    • "scheduleStatus": "SCHEDULED",
    • "paymentError": {
      },
    • "transactionId": "string"
    }

    Create a schedule.

    Authorizations:
    None
    Request Body schema: application/json
    required
    accountId
    required
    string

    Account Identifier

    totalAmount
    required
    number
    mediatorFee
    number
    currency
    required
    string = 3 characters

    ISO 4217 de 3 letras

    scheduleDate
    required
    string <date-time>
    externalIdentifier
    required
    string

    This field is used as idempotency and represents each item in the batch, not the entire batch

    required
    object

    Receiver information. When specifying the receiver account, one and only one of addressingKey and accountIdentification must be provided

    typeOrigin
    required
    string
    Enum: "CHANNEL" "OPEN_FINANCE"
    receiverReconciliationIdentifier
    string <= 35 characters

    Receivable identifier used by receiver to identify the payment/collection

    additionalInformation
    string <= 140 characters

    Additional information in free form.

    qrCodeType
    string
    Enum: "STATIC" "DYNAMIC"

    Field to indicate which type of qrcode

    historyCode
    string

    This field indicates how a transaction was completed, pre-stored or manual information. If not informed, the default value will be MANUAL

    initiationProcedure
    string
    Enum: "MANUAL" "PRE_STORED"

    This field indicates how a transaction was completed, pre-stored or manual information. If not informed, the default value will be MANUAL

    initiatingInstitution
    string

    CNPJ of the institution that actually initiated this payment through Open Finance channels. - Required if its for Open Finance

    initiationForm
    string
    Enum: "MANU" "DICT" "QRES" "QRDN" "INIC"

    Form of initiation of payment. Indicates whether the payment was initiated with manual data (MANU), by addressing key (DICT), static QR Code (QRES) , dynamic QR Code (QRDN) or payment transaction initiation service (INIC) - Required if the initiatingInstitution field is filled in

    transactionIdentification
    string

    Responses

    Request samples

    Content type
    application/json
    {
    • "accountId": "string",
    • "totalAmount": 0,
    • "mediatorFee": 0,
    • "currency": "str",
    • "scheduleDate": "2019-08-24T14:15:22Z",
    • "externalIdentifier": "string",
    • "recipient": {
      },
    • "typeOrigin": "CHANNEL",
    • "receiverReconciliationIdentifier": "string",
    • "additionalInformation": "string",
    • "qrCodeType": "STATIC",
    • "historyCode": "string",
    • "initiationProcedure": "MANUAL",
    • "initiatingInstitution": "string",
    • "initiationForm": "MANU",
    • "transactionIdentification": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "accountId": "string",
    • "totalAmount": 0,
    • "mediatorFee": 0,
    • "currency": "str",
    • "scheduleDate": "2019-08-24T14:15:22Z",
    • "externalIdentifier": "string",
    • "recipient": {
      },
    • "typeOrigin": "CHANNEL",
    • "receiverReconciliationIdentifier": "string",
    • "additionalInformation": "string",
    • "qrCodeType": "STATIC",
    • "historyCode": "string",
    • "initiationProcedure": "MANUAL",
    • "initiatingInstitution": "string",
    • "initiationForm": "MANU",
    • "transactionIdentification": "string",
    • "scheduleId": "string",
    • "accountHolderId": "string",
    • "reprocessing": {
      },
    • "history": [
      ],
    • "createdAt": "2019-08-24T14:15:22Z",
    • "updatedAt": "2019-08-24T14:15:22Z",
    • "scheduleStatus": "SCHEDULED",
    • "paymentError": {
      },
    • "transactionId": "string"
    }

    Filter and list schedules by account.

    Authorizations:
    None
    path Parameters
    accountId
    required
    string

    account identification.

    query Parameters
    endDate
    string

    filter by date range(yyyy-MM-dd)

    startDate
    string

    filter by date range(yyyy-MM-dd)

    status
    string
    Enum: "SCHEDULED" "RECEIVED" "ACCEPTED" "REJECTED" "CANCELLED"

    filter by status

    pageSize
    number

    Page max size.

    cursor
    string

    Get next page.

    Responses

    Response samples

    Content type
    application/json
    {
    • "payments": [
      ],
    • "cursor": "string"
    }

    Get schedule by id.

    Authorizations:
    None
    path Parameters
    id
    required
    any

    payment identification.

    Responses

    Response samples

    Content type
    application/json
    {
    • "accountId": "string",
    • "totalAmount": 0,
    • "mediatorFee": 0,
    • "currency": "str",
    • "scheduleDate": "2019-08-24T14:15:22Z",
    • "externalIdentifier": "string",
    • "recipient": {
      },
    • "typeOrigin": "CHANNEL",
    • "receiverReconciliationIdentifier": "string",
    • "additionalInformation": "string",
    • "qrCodeType": "STATIC",
    • "historyCode": "string",
    • "initiationProcedure": "MANUAL",
    • "initiatingInstitution": "string",
    • "initiationForm": "MANU",
    • "transactionIdentification": "string",
    • "scheduleId": "string",
    • "accountHolderId": "string",
    • "reprocessing": {
      },
    • "history": [
      ],
    • "createdAt": "2019-08-24T14:15:22Z",
    • "updatedAt": "2019-08-24T14:15:22Z",
    • "scheduleStatus": "SCHEDULED",
    • "paymentError": {
      },
    • "transactionId": "string"
    }

    Delete webhook configuration.

    Authorizations:
    None

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "string"
    }

    Add or update webhook.

    Authorizations:
    None
    Request Body schema: application/json
    required
    object (CreateWebHookConfigDto)

    Responses

    Request samples

    Content type
    application/json
    { }

    Response samples

    Content type
    application/json
    {
    • "accountHolderId": "string",
    • "createdAt": "2019-08-24T14:15:22Z",
    • "updatedAt": "2019-08-24T14:15:22Z"
    }

    Get webhook configuration.

    Authorizations:
    None

    Responses

    Response samples

    Content type
    application/json
    {
    • "accountHolderId": "string",
    • "createdAt": "2019-08-24T14:15:22Z",
    • "updatedAt": "2019-08-24T14:15:22Z"
    }

    AutoPix > Payer > Recurrence

    Get Recurrence

    • Responsible for getting the detail of recurrence authorizations on Flagship AutoPix Payer.
    • Compatible with the follow versions:
    • 1.0.0 or superior
    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    recId
    required
    string
    header Parameters
    Authorization
    required
    stringBearer .*

    A valid OAuth2 access token.

    Cpf-Cnpj-Pagador
    required
    string [ 11 .. 14 ]

    payer tax document

    Responses

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Configure Authorized Recurrence Limits

    • Responsible for configure limits of the authorized recurrence on Flagship AutoPix Payer.
    • Compatible with the follow versions:
    • 1.0.0 or superior
    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    recId
    required
    string
    header Parameters
    Idempotency-Id
    required
    string <= 300 characters

    Unique ID to prevent duplicate transactions. An API request with the same idempotency ID as a previous successful transaction will return the same response, but will not create a new transaction.

    Authorization
    required
    stringBearer .*

    A valid OAuth2 access token.

    Cpf-Cnpj-Pagador
    required
    string [ 11 .. 14 ]

    payer tax document

    Request Body schema: application/json
    required
    useAccountLimit
    boolean
    Default: true
    maximumValue
    number <double>

    Responses

    Request samples

    Content type
    application/json
    {
    • "useAccountLimit": true,
    • "maximumValue": 200.21
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    List Recurrence Histories

    • Responsible for list history of recurrences on Flagship AutoPix Payer.
    • Compatible with the follow versions:
    • 1.0.0 or superior
    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    recId
    required
    string
    query Parameters
    recId
    string
    status
    string
    Enum: "APPROVED" "REJECTED" "EXPIRED" "CANCELED"
    integrationStatus
    string
    Enum: "SENDING_APPROVAL" "WAITING_APPROVAL_CONFIRMATION" "APPROVED" "SENDING_REJECTION" "REJECTED" "SENDING_CANCELLATION" "WAITING_CANCELLATION_CONFIRMATION" "SENDING_CANCELLATION_CONFIRMATION" "CANCELED" "EXPIRED"
    payerBranch
    string
    payerAccount
    string
    initialDate
    string <date>
    finalDate
    string <date>
    sort
    string^\w+(,\w+)*,(asc|desc)$
    Examples:
    • sort=createdAt,asc or createdAt,desc - Sort by createdAt ascending or sort by createdAt descending.
    • sort=status,asc or status,desc - Sort by status ascending or sort by status descending.

    Can be sorted ascending and descending by createdAt, status.

    page
    integer
    size
    integer >= 1
    Default: 10
    header Parameters
    Authorization
    required
    stringBearer .*

    A valid OAuth2 access token.

    Cpf-Cnpj-Pagador
    required
    string [ 11 .. 14 ]

    payer tax document

    Responses

    Response samples

    Content type
    application/json
    {
    • "data": [
      ]
    }

    Cancel Recurrence Authorization

    • Responsible for cancel authorized recurrence on Flagship AutoPix Payer.
    • Compatible with the follow versions:
    • 1.0.0 or superior
    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    recId
    required
    string
    header Parameters
    Idempotency-Id
    required
    string <= 300 characters

    Unique ID to prevent duplicate transactions. An API request with the same idempotency ID as a previous successful transaction will return the same response, but will not create a new transaction.

    Authorization
    required
    stringBearer .*

    A valid OAuth2 access token.

    Cpf-Cnpj-Pagador
    required
    string [ 11 .. 14 ]

    payer tax document

    Request Body schema: application/json
    required
    reasonCode
    required
    string (CancellationReasonCode)
    Enum: "ACCL" "DCSD" "FRUD" "SLDB"

    Cancellation reason code of recurrence:

    • ACCL - Cancellation motivated to closure of the paying user's or receiving user's account
    • DCSD - Cancellation motivated to death of the paying user
    • FRUD - Cancellation motivated to suspicion of fraud
    • SLDB - Cancellation requested by the paying user
    requesterTaxId
    required
    string (TaxId)

    Document(CPF,CNPJ), mandatory for BACEN

    Responses

    Request samples

    Content type
    application/json
    {
    • "reasonCode": "ACCL",
    • "requesterTaxId": "99999999000999"
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Activate/Authorize Recurrence (Journeys 2,3,4)

    • Responsible for creating a Recurrence.
    • Compatible with the following versions:
      • 1.0.0 or superior
    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    header Parameters
    Idempotency-Id
    required
    string <= 300 characters

    Unique ID to prevent duplicate transactions. An API request with the same idempotency ID as a previous successful transaction will return the same response, but will not create a new transaction.

    Authorization
    required
    stringBearer .*

    A valid OAuth2 access token.

    Cpf-Cnpj-Pagador
    required
    string [ 11 .. 14 ]

    payer tax document

    Request Body schema: application/json
    required
    recId
    required
    string (RecurrenceId) = 29 characters [a-zA-Z0-9]{29}

    Formation rule:

    • RAxxxxxxxxyyyyMMddkkkkkkkkkkk (29 characters; "case sensitive", that is, it differentiates between upper and lower case letters), being:
    • "R": fixed (1 character). "R" for the recurrence created within Pix;
    • "A": identification of the possibility of new attempts, with the values"R" or "N" (1 character) possible. "R" if the recurrence allows new payment attempts after due date, or "N" if it does not allow new attempts.
    • "xxxxxxxx": identification of the agent that provides services to the receiving user who generated the , which can be: the ISPB of the direct participant, the ISPB of the indirect participant or the first 8 digits of the CNPJ of the initiation service provider (8 numeric characters [0-9]);
    • "yyyyMMdd": date (8 characters) of creation of the recurrence;
    • "kkkkkkkkkkk": sequential created by the agent that generated the (11 alphanumeric characters [a-z|A-Z|0-9]). It must be unique within each "yyyyMMdd".

    Therefore, the recurrence ID must be formed according to one of the following types:

    • "RRxxxxxxxxyyyyMMddkkkkkkkkkkk"; for recurrence created within Pix and which allows new payment attempts after maturity; or
    • "RNxxxxxxxxyyyyMMddkkkkkkkkkkk"; for recurrence created within Pix and which does not allow new payment attempts after due date.
    creationDateTime
    required
    string <date-time> (Timestamp)

    date and time

    required
    object (ContractLink)

    Contract link object identifier

    required
    object (Calendar)

    Recurrence calendar information

    object (RecValue)
    retryPolicy
    required
    string (RetryPolicy)
    Enum: "NOT_ALLOWED" "ALLOWED_3R_7D"

    Retry policy after recurrence expiration

    required
    object (RecActivationJourney234)

    Data related to confirmation of recurrence activation.

    required
    object (Receiver)

    Receiver

    required
    object (Payer)

    Payer object

    object (AuthorizedLimits)

    Responses

    Request samples

    Content type
    application/json
    {
    • "recId": "RR1234567820240115abcdefghijk",
    • "creationDateTime": "2017-07-21T17:32:28Z",
    • "contractLink": {
      },
    • "calendar": {
      },
    • "value": {
      },
    • "retryPolicy": "NOT_ALLOWED",
    • "activation": {
      },
    • "receiver": {
      },
    • "payer": {
      },
    • "limits": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    List Recurrences

    • Responsible for list recurrence on Flagship AutoPix Payer.
    • Compatible with the follow versions:
    • 1.0.0 or superior
    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    query Parameters
    initialDate
    required
    string <date>
    endDate
    required
    string <date>
    recId
    string
    debtorTaxDocument
    string^(\d{11}|\d{14})$

    Filters the debtor tax document.

    payerBranch
    string
    payerAccount
    string
    status
    string
    Enum: "APPROVED" "REJECTED" "EXPIRED" "CANCELED"
    integrationStatus
    string
    Enum: "SENDING_APPROVAL" "WAITING_APPROVAL_CONFIRMATION" "APPROVED" "SENDING_REJECTION" "REJECTED" "SENDING_CANCELLATION" "WAITING_CANCELLATION_CONFIRMATION" "SENDING_CANCELLATION_CONFIRMATION" "CANCELED" "EXPIRED"
    sort
    string^\w+(,\w+)*,(asc|desc)$
    Examples:
    • sort=id,asc or id,desc - Sort by id ascending or sort by id descending.
    • sort=status,asc or status,desc - Sort by status ascending or sort by status descending.
    • sort=date,asc or date,desc - Sort by date ascending or sort by date descending.
    • sort=createdAt,asc or createdAt,desc - Sort by createdAt ascending or sort by createdAt descending.

    Can be sorted ascending and descending by id, status, date, createdAt.

    page
    integer
    size
    integer >= 1
    Default: 10
    header Parameters
    Authorization
    required
    stringBearer .*

    A valid OAuth2 access token.

    Cpf-Cnpj-Pagador
    required
    string [ 11 .. 14 ]

    payer tax document

    Responses

    Response samples

    Content type
    application/json
    {
    • "data": [
      ]
    }

    AutoPix > Payer > Recurrence Request

    Recurrence Requests List

    • Responsible for recurrences requests on Flagship AutoPix Payer.
    • Compatible with the follow versions:
    • 1.0.0 or superior
    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    query Parameters
    initialDate
    required
    string <date-time>
    endDate
    required
    string <date-time>
    recipientBranch
    string
    recipientAccount
    string
    requestRecId
    string
    recId
    string
    status
    string
    Enum: "RECEIVED" "REJECTED" "ACCEPTED" "EXPIRED" "CANCELED"

    Recurrence request status

    integrationStatus
    string
    Enum: "RECEIVED" "SENDING_RECEIVING_CONFIRMATION" "ACCEPTANCE_PENDING" "ACCEPTED" "REJECTED" "SENDING_CANCELLATION_CONFIRMATION" "CANCELED" "EXPIRED"

    Recurrence request status

    sort
    string^\w+(,\w+)*,(asc|desc)$
    Examples:
    • sort=id,asc or id,desc - Sort by requestRecId ascending or sort by requestRecId descending.
    • sort=status,asc or status,desc - Sort by status ascending or sort by status descending.
    • sort=expirationDate,asc or expirationDate,desc - Sort by expirationDate ascending or sort by expirationDate descending.
    • sort=createdAt,asc or createdAt,desc - Sort by createdAt ascending or sort by createdAt descending.

    Can be sorted ascending and descending by id, status, expirationDate, createdAt.

    page
    integer
    size
    integer >= 1
    Default: 10
    header Parameters
    Authorization
    required
    stringBearer .*

    A valid OAuth2 access token.

    Cpf-Cnpj-Pagador
    required
    string [ 11 .. 14 ]

    payer tax document

    Responses

    Response samples

    Content type
    application/json
    {
    • "data": [
      ]
    }

    Find Recurrence Request

    • Responsible for get an recurrence request on Flagship AutoPix Payer.
    • Compatible with the follow versions:
    • 1.0.0 or superior
    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    requestRecId
    required
    string
    header Parameters
    Authorization
    required
    stringBearer .*

    A valid OAuth2 access token.

    Cpf-Cnpj-Pagador
    required
    string [ 11 .. 14 ]

    payer tax document

    Responses

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Recurrence Request Authorization (Journey 1)

    • Responsible for authorize recurrence for journey 1 (Push) on Flagship AutoPix Payer.
    • Compatible with the follow versions:
    • 1.0.0 or superior
    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    requestRecId
    required
    string
    header Parameters
    Idempotency-Id
    required
    string <= 300 characters

    Unique ID to prevent duplicate transactions. An API request with the same idempotency ID as a previous successful transaction will return the same response, but will not create a new transaction.

    Authorization
    required
    stringBearer .*

    A valid OAuth2 access token.

    Cpf-Cnpj-Pagador
    required
    string [ 11 .. 14 ]

    payer tax document

    Request Body schema: application/json
    required
    useAccountLimit
    boolean
    Default: true
    acceptance
    required
    boolean
    Default: true
    rejectionCode
    string
    maximumValue
    number <double>
    municipalityCode
    string (MunicipalityCode) = 7 characters
    Default: "0000000"

    IBGE's city code.

    payerName
    required
    string (PayerName)

    Payer Name.

    Responses

    Request samples

    Content type
    application/json
    {
    • "useAccountLimit": true,
    • "acceptance": true,
    • "rejectionCode": "Code of the Rejection",
    • "maximumValue": 200.21,
    • "municipalityCode": "0000000",
    • "payerName": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    AutoPix > Payer > Billing

    Cancel Billing

    • Responsible for cancelling billing Flagship AutoPix.
    • Compatible with the follow versions:
    • 1.0.0 or superior
    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    txId
    required
    string[a-zA-Z0-9]{26,35}
    Example: 33beb661beda44a8928fef47dbeb2dc5

    Transaction ID

    The txId field determines the transaction identifier. The purpose of this field is to be an element that allows the recipient's PSP to present the payment reconciliation functionality to the recipient user.

    In pacs.008, it is referenced as TransactionIdentification or idConciliacaoRecebedor.

    In terms of operational flow, the txId is read by the payer's PSP application and, after payment is confirmed, is sent to the SPI via pacs.008. A pacs.008 is also sent to the recipient's PSP, containing, in addition to all the usual payment information, the txId. Upon noticing a receipt with a txId, the recipient's PSP is able to communicate with the recipient user, informing them that a specific payment has been settled.

    The txId is created exclusively by the recipient user and is under their responsibility. The txId, in the context of representing a billing, is unique per CPF/CNPJ of the receiving user. It is up to the receiving PSP to validate this rule in the Pix API.

    header Parameters
    Idempotency-Id
    required
    string <= 300 characters

    Unique ID to prevent duplicate transactions. An API request with the same idempotency ID as a previous successful transaction will return the same response, but will not create a new transaction.

    Authorization
    required
    stringBearer .*

    A valid OAuth2 access token.

    Cpf-Cnpj-Pagador
    required
    string [ 11 .. 14 ]

    payer tax document

    Request Body schema: application/json
    code
    string (BillingCancellationReasonCode)
    Enum: "ACCT" "BLCK" "CCLD" "FAIL" "OTHR" "SLBD"

    Cancellation reason code of billing:

    • ACCT - Billing cancelation motivated to closure of the paying or receiving transactional account
    • BLCK - Billing cancelation motivated to blocking of the paying or receiving transactional account
    • CCLD - Billing cancelation motivated to cancellation of the authorization for periodic payments
    • FAIL - Billing cancelation motivated to failure or error in the settlement flow
    • OTHR - Billing cancelation requested by the paying user participant or the receiving user participant for other reasons
    • SLBD - Billing cancelation requested by paying user
    description
    string

    Detailed description of the cancellation reason

    Responses

    Request samples

    Content type
    application/json
    {
    • "code": "ACCT",
    • "description": "Cancellation requested by the PAYER_USER"
    }

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    List Billings

    • Responsible for list billing Flagship AutoPix.
    • Compatible with the follow versions:
    • 1.0.0 or superior
    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    query Parameters
    initialDate
    required
    string <date-time>
    endDate
    required
    string <date-time>
    dueDate
    string <date>
    txId
    string[a-zA-Z0-9]{26,35}
    Example: txId=33beb661beda44a8928fef47dbeb2dc5
    e2eId
    string[a-zA-Z0-9]{32}
    Example: e2eId=AB12CD34EF56GH78IJ90KL12MN34OP56
    recId
    string
    status
    string
    Enum: "ACTIVATED" "CONCLUDED" "REJECTED" "CANCELED" "EXPIRED"
    integrationStatus
    string
    Enum: "SENDING_SCHEDULING_CONFIRMATION" "ACTIVATED" "SETTLING_PAYMENT" "CONCLUDED" "SENDING_REJECTION" "REJECTED" "SENDING_CANCELLATION" "WAITING_CANCELLATION_CONFIRMATION" "SENDING_CANCELLATION_CONFIRMATION" "CANCELED" "EXPIRED"
    payerBranch
    string
    payerAccount
    string
    receiverDocument
    string
    sort
    string^\w+(,\w+)*,(asc|desc)$
    Examples:
    • sort=txId,asc or txId,desc - Sort by txId ascending or sort by txId descending.
    • sort=status,asc or status,desc - Sort by status ascending or sort by status descending.
    • sort=dueDate,asc or dueDate,desc - Sort by dueDate ascending or sort by dueDate descending.
    • sort=initialDate,asc or initialDate,desc - Sort by initialDate ascending or sort by initialDate descending.

    Can be sorted ascending and descending by txId, status, dueDate, initialDate.

    page
    integer
    size
    integer >= 1
    Default: 10
    header Parameters
    Authorization
    required
    stringBearer .*

    A valid OAuth2 access token.

    Cpf-Cnpj-Pagador
    required
    string [ 11 .. 14 ]

    payer tax document

    Responses

    Response samples

    Content type
    application/json
    {
    • "data": [
      ]
    }

    Get Billing

    • Responsible for initiating the billing process for Cash Management AutoPix.
    • Compatible with the follow versions:
    • 1.6.0 or superior
    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    txId
    required
    string[a-zA-Z0-9]{26,35}
    Example: 33beb661beda44a8928fef47dbeb2dc5

    Transaction ID

    The txId field determines the transaction identifier. The purpose of this field is to be an element that allows the recipient's PSP to present the payment reconciliation functionality to the recipient user.

    In pacs.008, it is referenced as TransactionIdentification or idConciliacaoRecebedor.

    In terms of operational flow, the txId is read by the payer's PSP application and, after payment is confirmed, is sent to the SPI via pacs.008. A pacs.008 is also sent to the recipient's PSP, containing, in addition to all the usual payment information, the txId. Upon noticing a receipt with a txId, the recipient's PSP is able to communicate with the recipient user, informing them that a specific payment has been settled.

    The txId is created exclusively by the recipient user and is under their responsibility. The txId, in the context of representing a billing, is unique per CPF/CNPJ of the receiving user. It is up to the receiving PSP to validate this rule in the Pix API.

    header Parameters
    Authorization
    required
    stringBearer .*

    A valid OAuth2 access token.

    Cpf-Cnpj-Pagador
    required
    string [ 11 .. 14 ]

    payer tax document

    Responses

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Get Billing EndToEndId

    • Responsible for initiating the billing process for AutoPix using the EndToEndIdentification.
    • Compatible with the follow versions:
    • 1.6.0 or superior
    Authorizations:
    oAuth2ClientCredentials
    path Parameters
    accountId
    required
    string
    e2eId
    required
    string[a-zA-Z0-9]{32}
    Example: AB12CD34EF56GH78IJ90KL12MN34OP56

    EndToEndIdentification Unique ID for tracking the transaction EndToEnd Identification that transits in PACS 002, PACS 004 and PACS 008

    header Parameters
    Authorization
    required
    stringBearer .*

    A valid OAuth2 access token.

    Cpf-Cnpj-Pagador
    required
    string [ 11 .. 14 ]

    payer tax document

    Responses

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    AutoPix > Payer > Webhook

    Put Webhook

    • Responsible for put webhook Flagship AutoPix.
    • Compatible with the follow versions:
    • 1.0.0 or superior
    Authorizations:
    oAuth2ClientCredentials
    header Parameters
    Authorization
    required
    stringBearer .*

    A valid OAuth2 access token.

    Request Body schema: application/json
    required
    url
    required
    string
    headers
    object

    Responses

    Request samples

    Content type
    application/json
    {}

    Response samples

    Content type
    application/json
    {
    • "url": "https://webhook.site/139b06d4-21df-4b76-88b5-30100298cab2",
    • "headers": {
      },
    • "mediatorId": "8ED16712-36C6-4440-9B68-437EF68C59A7",
    • "createdAt": "2024-12-10T07:10:05.115Z",
    • "updatedAt": "2024-12-10T07:10:05.115Z",
    • "deletedAt": null
    }

    Get Webhook

    • Responsible for get webhook Flagship AutoPix.
    • Compatible with the follow versions:
    • 1.0.0 or superior
    Authorizations:
    oAuth2ClientCredentials
    header Parameters
    Authorization
    required
    stringBearer .*

    A valid OAuth2 access token.

    Responses

    Response samples

    Content type
    application/json
    {
    • "url": "https://webhook.site/139b06d4-21df-4b76-88b5-30100298cab2",
    • "headers": {
      },
    • "mediatorId": "8ED16712-36C6-4440-9B68-437EF68C59A7",
    • "createdAt": "2024-12-10T07:10:05.115Z",
    • "updatedAt": "2024-12-10T07:10:05.115Z",
    • "deletedAt": null
    }

    Delete Webhook

    • Responsible for delete webhook Flagship AutoPix.
    • Compatible with the follow versions:
    • 1.0.0 or superior
    Authorizations:
    oAuth2ClientCredentials
    header Parameters
    Authorization
    required
    stringBearer .*

    A valid OAuth2 access token.

    Responses

    Response samples

    Content type
    application/problem+json
    {}

    AutoPix > Receiver > Receiver Management

    Gathers endpoints intended to handle receiver account management.

    Register receiver

    Create receiver

    Authorizations:
    None
    path Parameters
    accountId
    required
    string (Receiver account ID)
    Request Body schema: application/json

    Data to register receiver.

    document
    required
    string (Receiver CNPJ) [ 14 .. 18 ] characters
    name
    required
    string (Receiver Name) [ 1 .. 140 ] characters
    email
    string (Receiver Email) [ 1 .. 150 ] characters

    Responses

    Request samples

    Content type
    application/json
    {
    • "id": "cc5ebf6f-8949-4dbd-85b0-46ea5b7a1598",
    • "document": "11111111111111",
    • "name": "Nome Recebedor"
    }

    Response samples

    Content type
    application/json
    {
    • "id": "cc5ebf6f-8949-4dbd-85b0-46ea5b7a1598",
    • "document": "11111111111111",
    • "name": "Nome Recebedor"
    }

    AutoPix > Receiver > Recurrence Management

    Gathers endpoints intended to handle recurrence management.

    Consult recurrence.

    Consult recurrence.

    Authorizations:
    None
    path Parameters
    idRec
    required
    string (Recurrence ID)
    accountId
    required
    string (Receiver account ID)
    query Parameters
    txId
    string (TxId of the charge associated with the recurrence.)

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "idRec": "RN1234567820240115abcdefghijk",
    • "status": "APROVADA",
    • "valor": {
      },
    • "vinculo": {
      },
    • "calendario": {
      },
    • "politicaRetentativa": "NAO_PERMITE",
    • "loc": {
      },
    • "pagador": {
      },
    • "recebedor": {
      },
    • "atualizacao": [
      ],
    • "dadosQR": {
      }
    }

    Revise recurrence.

    Revise recurrence.

    Authorizations:
    None
    path Parameters
    idRec
    required
    string (Recurrence ID)
    accountId
    required
    string (Receiver account ID)
    Request Body schema: application/json

    Data for revising the recurrence.

    status
    string (Recurrence record status)
    Value: "CANCELADA"
    object
    loc
    integer <int64> (Location ID)

    Identifier of the location to be informed in the creation of a recurrence.

    object (Recurrence Calendar Information)

    Recurrence Calendar Information

    object (Data related to the recurrence activation confirmation.)

    Data related to the recurrence activation confirmation.

    Responses

    Request samples

    Content type
    application/json
    {
    • "loc": 108,
    • "vinculo": {
      },
    • "calendario": {
      },
    • "ativacao": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "idRec": "RN1234567820240115abcdefghijk",
    • "vinculo": {
      },
    • "calendario": {
      },
    • "politicaRetentativa": "NAO_PERMITE",
    • "recebedor": {
      },
    • "valor": {
      },
    • "status": "CRIADA",
    • "loc": {
      },
    • "ativacao": {
      },
    • "atualizacao": [
      ]
    }

    Consult recurrence list.

    Consult recurrence list.

    Authorizations:
    None
    path Parameters
    accountId
    required
    string (Receiver account ID)
    query Parameters
    inicio
    required
    string <date-time> (Start date)

    Filters records whose creation date is greater than or equal to the start date. Respects RFC 3339.

    fim
    required
    string <date-time> (End date)

    Filters records whose creation date is less than or equal to the end date. Respects RFC 3339.

    cpf
    string (CPF) /^\d{11}$/

    Filter by Debtor CPF. Cannot be used at the same time as CNPJ.

    cnpj
    string (CNPJ) /^\d{14}$/

    Filter by Debtor CNPJ. Cannot be used at the same time as CPF.

    locationPresente
    boolean
    status
    string (Recurrence record status)

    Filter by recurrence status.

    convenio
    string (Agreement) <= 60 characters

    Filter by associated agreement.

    paginacao.paginaAtual
    integer <int32> (Current page) >= 0
    Default: 0

    Page to be returned by the query. If not informed, the PSP will assume it to be 0.

    paginacao.itensPorPagina
    integer <int32> (Items per Page) [ 1 .. 1000 ]
    Default: 100

    Maximum number of records returned on each page. Only the last page may contain a smaller number of records.

    Responses

    Response samples

    Content type
    application/json
    {
    • "parametros": {
      },
    • "recs": [
      ]
    }

    Create recurrence.

    Create recurrence

    Authorizations:
    None
    path Parameters
    accountId
    required
    string (Receiver account ID)
    Request Body schema: application/json

    Data for generating the recurrence.

    required
    object (Description of Recurrence Object)

    Information about the recurrence object.

    required
    object (Recurrence Calendar Information)

    Recurrence Calendar Information

    object
    object
    politicaRetentativa
    required
    string (Retry policy after recurrence due date)
    Enum: "NAO_PERMITE" "PERMITE_3R_7D"
    loc
    integer <int64> (Location ID)

    Identifier of the location to be informed in the creation of a recurrence.

    object (Data related to the recurrence activation confirmation.)

    Data related to the recurrence activation confirmation.

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "vinculo": {
      },
    • "calendario": {
      },
    • "valor": {
      },
    • "politicaRetentativa": "NAO_PERMITE",
    • "loc": 108,
    • "ativacao": {
      }
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "idRec": "RN1234567820240115abcdefghijk",
    • "vinculo": {
      },
    • "calendario": {
      },
    • "politicaRetentativa": "NAO_PERMITE",
    • "recebedor": {
      },
    • "valor": {
      },
    • "status": "CRIADA",
    • "loc": {
      },
    • "ativacao": {
      },
    • "atualizacao": [
      ]
    }

    Consult recurrence and QR Code data.

    Authorizations:
    None
    path Parameters
    idRec
    required
    string (Recurrence ID)
    query Parameters
    txId
    string (TxId) [a-zA-Z0-9]{26,35}

    Filter by txId.

    Responses

    Response samples

    Content type
    application/json
    {
    • "recId": "RAxxxxxxxxyyyyMMddkkkkkkkkkkk",
    • "contractLink": {
      },
    • "calendar": {
      },
    • "retryPolicy": "NOT_ALLOWED",
    • "payer": {
      },
    • "receiver": {
      },
    • "value": {
      },
    • "status": "CREATED",
    • "integrationStatus": "CREATED",
    • "loc": {},
    • "activation": {
      },
    • "updates": [
      ],
    • "cancellation": {
      },
    • "qrcodeData": {
      }
    }

    AutoPix > Receiver > Recurrence Request Management

    Gathers endpoints intended to handle recurrence request management.

    Create recurrence confirmation request.

    Create recurrence confirmation request.

    Authorizations:
    None
    path Parameters
    accountId
    required
    string (Receiver account ID)
    Request Body schema: application/json

    Data for generating the recurrence request.

    idRec
    required
    string (Recurrence ID) = 29 characters [a-zA-Z0-9]{29}

    Recurrence Identifier

    Formation Rule:

    • RAxxxxxxxxyyyyMMddkkkkkkkkkkk (29 characters; "case sensitive"), where:

      • "R": fixed (1 character). "R" for the recurrence created inside Pix;
      • "A": identification of the possibility of new attempts, being possible values "R" or "N" (1 character). "R" if the recurrence allows new payment attempts after due date, or "N" if it does not allow new attempts.
      • "xxxxxxxx": identification of the agent providing service for the receiving user who generated the , can be: the ISPB of the direct participant, the ISPB of the indirect participant or the first 8 digits of the CNPJ of the initiation service provider (8 numeric characters [0-9]);
      • "yyyyMMdd": date (8 characters) of recurrence creation;
      • "kkkkkkkkkkk": sequential created by the agent who generated the (11 alphanumeric characters [a-z|A-Z|0-9]). Must be unique within each "yyyyMMdd".

    Thus, the Recurrence ID must be formed according to one of the following types:

    • "RRxxxxxxxxyyyyMMddkkkkkkkkkkk"; for recurrence created inside Pix and that allows new payment attempts after due date; or
    • "RNxxxxxxxxyyyyMMddkkkkkkkkkkk"; for recurrence created inside Pix and that does not allow new payment attempts after due date.”
    required
    object (Recurrence Request Calendar Information)
    required
    Natural Person (object) or Legal Person (object)

    Responses

    Request samples

    Content type
    application/json
    {
    • "idRec": "RN123456782024011577825445612",
    • "calendario": {
      },
    • "destinatario": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "idSolicRec": "SC876456782024021577825445312",
    • "idRec": "RN123456782024011577825445612",
    • "calendario": {
      },
    • "status": "CRIADA",
    • "destinatario": {
      },
    • "atualizacao": [
      ],
    • "recPayload": {
      }
    }

    Consult recurrence confirmation request.

    Consult request.

    Authorizations:
    None
    path Parameters
    idSolicRec
    required
    string (Recurrence request ID)
    accountId
    required
    string (Receiver account ID)

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "idSolicRec": "SC876456782024021577825445312",
    • "idRec": "RN123456782024011577825445612",
    • "calendario": {
      },
    • "status": "CRIADA",
    • "destinatario": {
      },
    • "atualizacao": [
      ],
    • "recPayload": {
      }
    }

    Revise recurrence confirmation request.

    Revise recurrence confirmation request.

    Authorizations:
    None
    path Parameters
    idSolicRec
    required
    string (Recurrence request ID)
    accountId
    required
    string (Receiver account ID)
    Request Body schema: application/json

    Data for revising the recurrence request.

    status
    required
    string (Recurrence request record status)
    Value: "CANCELADA"

    Responses

    Request samples

    Content type
    application/json
    {
    • "status": "CANCELADA"
    }

    Response samples

    Content type
    application/json
    {
    • "idSolicRec": "SC876456782024021577825445312",
    • "idRec": "RN123456782024011577825445612",
    • "calendario": {
      },
    • "status": "CANCELADA",
    • "destinatario": {
      },
    • "atualizacao": [
      ],
    • "recPayload": {
      }
    }

    AutoPix > Receiver > Management of charges associated with a recurrence

    Gathers endpoints intended to handle the management of charges associated with a recurrence.

    Revise recurring charge.

    Authorizations:
    None
    path Parameters
    txid
    required
    string (Transaction ID) [a-zA-Z0-9]{26,35}

    Transaction Identifier

    The txid field determines the transaction identifier. The purpose of this field is to be an element that enables the receiver's PSP to present the payment reconciliation functionality to the receiving user.

    In pacs.008, it is referenced as TransactionIdentification <txId> or idConciliacaoRecebedor.

    In terms of operation flow, the txid is read by the payer's PSP application and, after payment confirmation, sent to the SPI via pacs.008. A pacs.008 is also sent to the receiver's PSP, containing, in addition to all the usual payment information, the txid. Upon noticing a receipt with a txid, the receiver's PSP is able to communicate with the receiving user, informing that a specific payment has been settled.

    The txid is created exclusively by the receiving user and is under their responsibility. The txid, in the context of representing a charge, is unique per CPF/CNPJ of the receiving user. It is up to the receiving PSP to validate this rule in the Pix API.

    accountId
    required
    string (Receiver account ID)
    Request Body schema: application/json
    required

    Data for generating the charge.

    status
    string (Charge record status)
    Value: "CANCELADA"

    Responses

    Request samples

    Content type
    application/json
    {
    • "status": "CANCELADA"
    }

    Response samples

    Content type
    application/json
    {
    • "idRec": "RN985156112024071999000566354",
    • "txid": "517bd858b59d458a841280b0f0a60bfa",
    • "calendario": {
      },
    • "valor": {
      },
    • "status": "CANCELADA",
    • "politicaRetentativa": "NAO_PERMITE",
    • "ajusteDiaUtil": true,
    • "devedor": {
      },
    • "recebedor": {
      },
    • "tentativas": [
      ],
    • "encerramento": {
      },
    • "atualizacao": [
      ]
    }

    Consult recurring charge.

    Endpoint to consult a recurring charge via a specific txid.

    Authorizations:
    None
    path Parameters
    txid
    required
    string (Transaction ID) [a-zA-Z0-9]{26,35}

    Transaction Identifier

    The txid field determines the transaction identifier. The purpose of this field is to be an element that enables the receiver's PSP to present the payment reconciliation functionality to the receiving user.

    In pacs.008, it is referenced as TransactionIdentification <txId> or idConciliacaoRecebedor.

    In terms of operation flow, the txid is read by the payer's PSP application and, after payment confirmation, sent to the SPI via pacs.008. A pacs.008 is also sent to the receiver's PSP, containing, in addition to all the usual payment information, the txid. Upon noticing a receipt with a txid, the receiver's PSP is able to communicate with the receiving user, informing that a specific payment has been settled.

    The txid is created exclusively by the receiving user and is under their responsibility. The txid, in the context of representing a charge, is unique per CPF/CNPJ of the receiving user. It is up to the receiving PSP to validate this rule in the Pix API.

    accountId
    required
    string (Receiver account ID)

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "idRec": "RR1234567820240115abcdefghijk",
    • "txid": "3136957d93134f2184b369e8f1c0729d",
    • "infoAdicional": "Serviços de Streamming de Música e Filmes.",
    • "calendario": {
      },
    • "valor": {
      },
    • "status": "CRIADA",
    • "politicaRetentativa": "PERMITE_3R_7D",
    • "ajusteDiaUtil": true,
    • "devedor": {
      },
    • "recebedor": {
      },
    • "atualizacao": [
      ]
    }

    Create recurring charge.

    Endpoint to create a recurring charge, in this case, the txid must be defined by the PSP.

    Authorizations:
    None
    path Parameters
    accountId
    required
    string (Receiver account ID)
    Request Body schema: application/json
    required

    Data for generating the recurring charge.

    idRec
    required
    string (Recurrence ID) = 29 characters [a-zA-Z0-9]{29}

    Recurrence Identifier

    Formation Rule:

    • RAxxxxxxxxyyyyMMddkkkkkkkkkkk (29 characters; "case sensitive"), where:

      • "R": fixed (1 character). "R" for the recurrence created inside Pix;
      • "A": identification of the possibility of new attempts, being possible values "R" or "N" (1 character). "R" if the recurrence allows new payment attempts after due date, or "N" if it does not allow new attempts.
      • "xxxxxxxx": identification of the agent providing service for the receiving user who generated the , can be: the ISPB of the direct participant, the ISPB of the indirect participant or the first 8 digits of the CNPJ of the initiation service provider (8 numeric characters [0-9]);
      • "yyyyMMdd": date (8 characters) of recurrence creation;
      • "kkkkkkkkkkk": sequential created by the agent who generated the (11 alphanumeric characters [a-z|A-Z|0-9]). Must be unique within each "yyyyMMdd".

    Thus, the Recurrence ID must be formed according to one of the following types:

    • "RRxxxxxxxxyyyyMMddkkkkkkkkkkk"; for recurrence created inside Pix and that allows new payment attempts after due date; or
    • "RNxxxxxxxxyyyyMMddkkkkkkkkkkk"; for recurrence created inside Pix and that does not allow new payment attempts after due date.”
    infoAdicional
    string (Additional invoice information.) <= 140 characters

    Additional invoice information.

    required
    object (Charge Calendar Information)
    required
    object (Recurring charge value)

    Recurring charge value

    ajusteDiaUtil
    required
    boolean (Adjust expected settlement date to next business day)
    Default: true

    Activation field for adjusting the expected settlement date to the next business day if the current due date is a non-business day. The Receiver PSP must consider local holidays based on the paying user's municipality code.

    required
    object

    The receiver object organizes information about the receiver of the charge.

    object

    The debtor object organizes information about the debtor of the recurrence.

    Responses

    Request samples

    Content type
    application/json
    {
    • "idRec": "RR1234567820240115abcdefghijk",
    • "infoAdicional": "Serviços de Streamming de Música e Filmes.",
    • "calendario": {
      },
    • "valor": {
      },
    • "ajusteDiaUtil": true,
    • "devedor": {
      },
    • "recebedor": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "idRec": "RR1234567820240115abcdefghijk",
    • "txid": "3136957d93134f2184b369e8f1c0729d",
    • "infoAdicional": "Serviços de Streamming de Música e Filmes.",
    • "calendario": {
      },
    • "status": "CRIADA",
    • "valor": {
      },
    • "politicaRetentativa": "PERMITE_3R_7D",
    • "ajusteDiaUtil": true,
    • "devedor": {
      },
    • "recebedor": {
      },
    • "atualizacao": [
      ]
    }

    Consult list of recurring charges.

    Endpoint to consult recurring charges via parameters such as start, end, idRec, cpf, cnpj, status, and agreement.

    Authorizations:
    None
    path Parameters
    accountId
    required
    string (Receiver account ID)
    query Parameters
    inicio
    required
    string <date-time> (Start date)

    Filters records whose creation date is greater than or equal to the start date. Respects RFC 3339.

    fim
    required
    string <date-time> (End date)

    Filters records whose creation date is less than or equal to the end date. Respects RFC 3339.

    idRec
    string (Recurrence ID) = 29 characters [a-zA-Z0-9]{29}

    Filter by Recurrence Identifier.

    cpf
    string (CPF) /^\d{11}$/

    Filter by Debtor CPF. Cannot be used at the same time as CNPJ.

    cnpj
    string (CNPJ) /^\d{14}$/

    Filter by Debtor CNPJ. Cannot be used at the same time as CPF.

    status
    string (Recurring charge record status.)

    Filter by recurring charge status.

    convenio
    string (Agreement) <= 60 characters

    Filter by associated agreement.

    paginacao.paginaAtual
    integer <int32> (Current page) >= 0
    Default: 0

    Page to be returned by the query. If not informed, the PSP will assume it to be 0.

    paginacao.itensPorPagina
    integer <int32> (Items per Page) [ 1 .. 1000 ]
    Default: 100

    Maximum number of records returned on each page. Only the last page may contain a smaller number of records.

    Responses

    Response samples

    Content type
    application/json
    {
    • "parametros": {
      },
    • "cobsr": [
      ]
    }

    Request charge retry.

    Endpoint to request retry of a recurring charge.

    Authorizations:
    None
    path Parameters
    accountId
    required
    string (Receiver account ID)
    txid
    required
    string (Transaction ID) [a-zA-Z0-9]{26,35}

    Transaction Identifier

    The txid field determines the transaction identifier. The purpose of this field is to be an element that enables the receiver's PSP to present the payment reconciliation functionality to the receiving user.

    In pacs.008, it is referenced as TransactionIdentification <txId> or idConciliacaoRecebedor.

    In terms of operation flow, the txid is read by the payer's PSP application and, after payment confirmation, sent to the SPI via pacs.008. A pacs.008 is also sent to the receiver's PSP, containing, in addition to all the usual payment information, the txid. Upon noticing a receipt with a txid, the receiver's PSP is able to communicate with the receiving user, informing that a specific payment has been settled.

    The txid is created exclusively by the receiving user and is under their responsibility. The txid, in the context of representing a charge, is unique per CPF/CNPJ of the receiving user. It is up to the receiving PSP to validate this rule in the Pix API.

    data
    required
    string <date>
    Example: 2023-04-01

    Expected settlement date for the corresponding payment order. This is a date in YYYY-MM-DD format, according to ISO 8601.

    Responses

    Response samples

    Content type
    application/json
    {
    • "idRec": "RR123456782024061999000566354",
    • "txid": "7f733863543b4a16b516d839bd4bc34e",
    • "calendario": {
      },
    • "valor": {
      },
    • "status": "ATIVA",
    • "politicaRetentativa": "PERMITE_3R_7D",
    • "ajusteDiaUtil": true,
    • "devedor": {
      },
    • "recebedor": {
      },
    • "tentativas": [
      ],
    • "atualizacao": [
      ]
    }

    AutoPix > Receiver > Location configuration for recurrence payloads

    Gathers endpoints intended to handle the configuration and removal of locations for recurrence payload use.

    Create payload location.

    Create payload location

    Authorizations:
    None
    path Parameters
    accountId
    required
    string (Receiver account ID)

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": 12069,
    • "location": "pix.example.com/qr/v2/rec/2353c790eefb11eaadc10242ac120002",
    • "criacao": "2023-12-20T12:38:28.774Z"
    }

    Consult registered locations.

    Endpoint to consult registered locations

    Authorizations:
    None
    path Parameters
    accountId
    required
    string (Receiver account ID)
    query Parameters
    inicio
    required
    string <date-time> (Start date)

    Filters records whose creation date is greater than or equal to the start date. Respects RFC 3339.

    fim
    required
    string <date-time> (End date)

    Filters records whose creation date is less than or equal to the end date. Respects RFC 3339.

    idRecPresente
    boolean
    convenio
    string (Agreement) <= 60 characters

    Filter by associated agreement.

    paginacao.paginaAtual
    integer <int32> (Current page) >= 0
    Default: 0

    Page to be returned by the query. If not informed, the PSP will assume it to be 0.

    paginacao.itensPorPagina
    integer <int32> (Items per Page) [ 1 .. 1000 ]
    Default: 100

    Maximum number of records returned on each page. Only the last page may contain a smaller number of records.

    Responses

    Response samples

    Content type
    application/json
    {
    • "parametros": {
      },
    • "loc": [
      ]
    }

    Retrieve payload location.

    Retrieves the payload location

    Authorizations:
    None
    path Parameters
    id
    required
    string (Id of the location registered to serve a payload)
    accountId
    required
    string (Receiver account ID)

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": 12069,
    • "location": "pix.example.com/qr/v2/rec/2353c790eefb11eaadc10242ac120002",
    • "criacao": "2023-12-20T12:38:28.774Z",
    • "idRec": "RR123456782024011510056892226"
    }

    Unlink a recurrence from a location.

    Endpoint used to unlink a recurrence from a location.

    If executed successfully, the loc entity will no longer present a recurrence, if it presented one prior to the call. Additionally, the entity associated with the unlinked resource will also no longer present a location. This operation does not alter the status of the resource in question.

    Authorizations:
    None
    path Parameters
    id
    required
    string (Id of the location registered to serve a payload)
    accountId
    required
    string (Receiver account ID)

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": 12069,
    • "location": "pix.example.com/qr/v2/rec/2353c790eefb11eaadc10242ac120002",
    • "criacao": "2023-12-20T12:38:28.774Z"
    }

    AutoPix > Receiver > Recurrence and charge notification management

    Gathers endpoints for recurrence/charge notification management from the receiving PSP to the receiving user.

    Configure Webhook.

    Endpoint for configuring the notification service regarding recurrences and charges. Only messages associated with the receiver's mediator will be notified.

    Authorizations:
    None
    Request Body schema: application/json
    required
    webhookUrl
    required
    string <uri> (Webhook URL)

    Responses

    Callbacks

    Request samples

    Content type
    application/json
    {}

    Response samples

    Content type
    application/problem+json
    {}

    Callback payload samples

    Callback
    POST: Operation response
    Content type
    application/json
    {
    • "recs": [
      ]
    }

    Display Webhook information.

    Endpoint for retrieving Webhook information.

    Authorizations:
    None

    Responses

    Response samples

    Content type
    application/json
    {}

    Cancel the Webhook.

    Endpoint for canceling the webhook.

    Authorizations:
    None

    Responses

    Response samples

    Content type
    application/problem+json
    {}