Account

General Information

Pix Fees

Pix fees are charged per transaction. Commission-based models use either fixed amounts or MDR (Merchant Discount Rate as a percentage), while billing models require no fee.

Examples:

A fixed fee of R$ 0.85 on a R$ 30.00 transaction nets R$ 29.15.
With 1% MDR, a R$ 22.00 transaction incurs a R$ 0.22 fee, netting R$ 21.78.

Set fee.amount = 0 for zero-fee rates.

Settlement Configuration

Settlement configuration determines where and how PIX transaction funds are transferred.

Settlement Method

An account must have exactly one settlement method: either a PIX key or a bank account, never both.

PIX Key Settlement transfers funds directly to another PIX participant with nearly instant processing. The PIX key used for settlement must be different from the account’s main key.
Bank Account Settlement transfers funds to a specific bank account on the next business day. This option requires COMPE/ISPB codes, agency, account number, and a CNPJ whose root matches the account’s root.

Automatic Settlement

hasAutomaticSettlement controls the transfer frequency of available funds.

When true, the system automatically transfers available funds every night during early morning hours.
When false, withdrawals must be initiated manually using Cash-Out endpoints.

This field is mandatory during account creation.

Hold Settlement

holdSettlement prevents automatic fund transfers even when automatic settlement is enabled.

When true, charges are created in a blocked state and do not settle normally.
This is useful for scenarios that require transaction review or manual approval before settlement.

The default value is false.

Split Fee Settlement

splitPixKey enables multi-party fund distribution when configured with the account’s settlement partner.

This setting defines a destination account for fee split crediting, allowing integrators to automatically redirect part of the fees to a separate account.

Rules:

The receiving account’s CNPJ root must match the primary account’s root.
Both accounts cannot have split payments enabled at the same time.
This feature requires Fiserv activation (Only available if the integrator has been created)

POST /v1/client/{clientId}/apm/pix/account

Add a pix account.

Request Fields

Field	Located in	Type	Mandatory	Description
clientId	path	string	yes	Client Id
header	API Key	string	yes	apikey
x-timestamp	header	string	yes	Date/time of the request (used to prevent replay attacks)
x-request-id	header	string	yes	Random ID used to identify the request
x-hmac-signature	header	string	yes	HMAC signature generated by combining the request parameters: Example: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`
Authorization	header	string (bearerToken)	yes	Bearer token for authentication
name	body	string	no	Account name, if not provided, defaults to value
Settlement.pixKey	body	string	yes	PixKey of settlement account. Only the pix key or account information should be provided, never both.
Settlement.bankAccount.type	body	integer	yes	(enum) 0. Checking Account, 1. Deposit Account, 2. Payment Account, 3. Savings Account
Settlement.bankAccount.BankCompeCode	body	string	yes	COMPE Code (Clearing System)
Settlement.bankAccount.bankIspbCode	body	string	yes	ISPB Code (Bank Identifier)
Settlement.bankAccount.agency	body	string	yes	Agency number
Settlement.bankAccount.accountNumber	body	string	yes	Account Number
Settlement.bankAccount.document.number	body	string	yes	Account's CNPJ. Must have the same root as the registered CNPJ
Settlement.bankAccount.document.type	body	string	yes	Always inform “CNPJ”
pixFee.amount	body	decimal	no	If percentage is given, it cannot be greater than 0
pixFee.percentage	body	decimal	no	If this value is given, it cannot be greater than 0
pixFee.min	body	decimal	no	Can be zero, but cannot be negative
pixFee.max	body	decimal	no	It can only be sent if the min exists; cannot be zero, negative, or ≤ min
userTermsAccept.document.number	body	string	yes	CPF of the person making the acceptance
userTermsAccept.document.type	body	string	yes	Always “CPF”
userTermsAccept.ip	body	string	yes	IP Address of the machine that gave the acceptance term
splitPixKey	body	string	no	This specifies the destination account to which the fee split will be credited. The account will not have a split calculation if no value is entered. Note: the integrator must have split functionality activated with Fiserv; otherwise, the fee split will not occur, even if a destination settlement account for the split is specified.
holdSettlement	body	bool	no	Identifies if charges are created with settlement hold (default false)
hasAutomaticSettlement	body	boolean	yes	Indicates if settlement occurs automatically
tradeName	body	string	yes	Trade name of the account

Request Example

{
  "name": "account name",
  "settlement": {
    "pixKey": "26770318000145",
    "bankAccount": {
      "accountNumber": "12345-1",
      "agency": "1234",
      "bankCompeCode": "341",
      "bankIspbCode": "00000007",
      "document": {
        "number": "60.664.745/0001-87",
        "type": "CNPJ"
      },
      "type": 1
    }
  },
  "pixFee": {
    "amount": 0,
    "percentage": 2,
    "max": 0,
    "min": 0
  },
  "splitPixKey": "1c78a371-187f-4318-ab95-69b54788ecda",
  "userTermsAccept": {
    "document": {
      "number": "631.313.010-31",
      "type": "CPF"
    },
    "ip": "198.51.100.42"
  },
  "holdSettlement": true,
  "tradeName": "Fiserv",
  "hasAutomaticSettlement": true
}

Response Fields

Field	Type	Description
pixKey	string	Unique Pix key generated for the account
pspClientId	string	Client ID for API authentication (Disregard if you will integrate directly with PSP Fiserv)
pspClientSecret	string	Client Secret for API authentication (Disregard if you will integrate directly with PSP Fiserv)

Response Example

{
  "pixKey": "b57c7b3c-976b-41f6-a5f6-7cccd86549bd",
  "pspClientId": "7a2a1ed1-aa51-4a71-9b18-0ba6f6bcfee1",
  "pspClientSecret": "2ccd83fc-34ba-4a21-97ca-bef027cc2c70"
}

GET /v1/client/{clientId}/apm/pix/account/{pixKey}

Return an account based on the PIX key.

Request Fields

Name	Located in	Description	Mandatory	Type
apikey	header	API Key	yes	string
x-timestamp	header	Date/time of the request (used to prevent replay attacks)	yes	string
x-request-id	header	Random ID used to identify the request	yes	string
x-hmac-signature	header	HMAC signature generated by combining the request parameters: Example: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL)`	yes	string
Authorization	header	Bearer token for authentication	yes	string (bearerToken)
pixKey	path	Account's PIX Key	yes	string
clientId	path	Client id	yes	string

Response Fields

Field	Type	Notes
name	string	Account legal name
documentNumber	string	Account CNPJ
pixKey	string	Pix key of the account. Used for charge generation
status	int	Account status
settlement	object	Settlement data
settlement.pixKey	string	Pix key of the settlement account, i.e., the account that receives the amounts from charges
settlement.bankAccount	object	Bank details of the settlement account, i.e., the account that receives the amounts from charges
settlement.bankAccount.accountNumber	string	Account number
settlement.bankAccount.agency	string	Branch number
settlement.bankAccount.bankCompeCode	string	Three-digit code of the Bank Clearing System. COMPE
settlement.bankAccount.type	string	Account type
settlement.bankAccount.document	object	Document data
settlement.bankAccount.document.number	string	Document number
settlement.bankAccount.document.type	string	Document type
pixFee	object	Fee information
pixFee.amount	decimal	Fixed fee
pixFee.percentage	decimal	Percentage fee
pixFee.max	decimal	Maximum fee
pixFee.min	decimal	Minimum fee
hasAutomaticSettlement	boolean	Indicates if the account automatically transfers amounts once a day to the settlement account.
pspClientId	string	Account client ID in the PSP
pspClientSecret	string	Account client secret in the PSP
splitPixKey	string	Pix key of the destination account for split fee settlement
holdSettlement	boolean	Indicates if charges are created as blocked and should not be settled
tradeName	string	Account trade name (optional)

Response Example

{
  "name": "Store Nome",
  "documentNumber": "40486138000167",
  "pixKey": "d60e6246-4885-471f-bab7-a3482f48d68b",
  "status": 1,
  "settlement": {
    "pixKey": null,
    "bankAccount": {
      "accountNumber": "12345-1",
      "agency": "1234",
      "bankCompeCode": "341",
      "document": {
        "number": "40.486.138/0001-67",
        "type": "CNPJ"
      },
      "type": 1
    }
  },
  "pixFee": {
    "amount": 0,
    "percentage": 2,
    "max": 0,
    "min": 0
  },
  "splitPixKey": "30001d73-4917-4a41-bb8f-9624b4910ff3",
  "hasAutomaticSettlement": true,
  "holdSettlement": true,
  "pspClientId": "7a2a1ed1-aa51-4a71-9b18-0ba6f6bcfee1",
  "pspClientSecret": "2ccd83fc-34ba-4a21-97ca-bef027cc2c70",
  "tradeName": "Store Nome"
}

PUT /v1/client/{clientId}/apm/pix/account/{pixKey}

Endpoint that changes a pix account.

Request Fields

Name	Located in	Type	Mandatory	Description
apikey	header	string	yes	API Key
x-timestamp	header	string	yes	Date/time of the request (used to prevent replay attacks)
x-request-id	header	string	yes	Random ID used to identify the request
x-hmac-signature	header	string	yes	HMAC signature generated by combining the request parameters: Example: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL)`
Authorization	header	string (bearerToken)	yes	Bearer token used for authentication
pixKey	path	string	yes	Account's PIX Key
clientId	path	string	yes	client id
Settlement.pixKey	body	string	yes	PixKey of settlement account. Only the pix key or account information should be provided, never both.
Settlement.bankAccount.type	body	integer	yes	(enum) 0. Checking Account, 1. Deposit Account 2. Payment Account 3. Savings Account
Settlement.bankAccount.BankCompeCode	body	string	yes	COMPE Code (Check and Other Document Clearing System)
Settlement.bankAccount.agency	body	string	yes	Agency number
Settlement.bankAccount.accountNumber	body	string	yes	Account Number
Settlement.bankAccount.document.number	body	string	yes	Account's CNPJ. Must have the same root as the registered CNPJ
Settlement.bankAccount.document.type	body	string	yes	Always inform the “CNPJ”
pixFee.amount	body	decimal	no	If percentage is given, it cannot be greater than 0
pixFee.percentage	body	decimal	no	If this value is given, it cannot be greater than 0
pixFee.min	body	decimal	no	Can be zero, but cannot be negative
pixFee.max	body	decimal	no	It can only be sent if the min exists; It cannot be zero, but cannot be negative and it can never be less than or equal to the min
splitPixKey	body	string	no	This specifies which settlement account the fee split will be credited to. If you have a settlement account, and this information is not provided or a null value is sent, that link will be removed, as well as the fee split calculation. Note: the integrator must have split functionality active with Fiserv; otherwise, the fee split will not occur, even if a settlement account is specified for the split.
holdSettlement	body	bool	no	Identifies if charges are created with liquidation hold (default false)
hasAutomaticSettlement	body	boolean	yes	Indicates if settlement occurs automatically
name	body	boolean	yes	Corporate Name
tradeName	body	boolean	yes	Trade Name

Request Example

{
  "settlement": {
    "pixKey": "26770318000145",
    "bankAccount": {
      "accountNumber": "12345-1",
      "agency": "1234",
      "bankCompeCode": "341",
      "document": {
        "number": "60.664.745/0001-87",
        "type": "CNPJ"
      },
      "type": 1
    }
  },
  "pixFee": {
    "amount": 0,
    "percentage": 2,
    "max": 0,
    "min": 0
  },
  "splitPixKey": "1c78a371-187f-4318-ab95-69b54788ecda",
  "holdSettlement": false,
  "hasAutomaticSettlement": true,
  "name": "Account Corporate Name",
  "tradeName": "Account Trade Name"
}

DELETE /v1/client/{clientId}/apm/pix/account/{pixKey}

Endpoint to delete a pix account.

Request Fields

Name	Located in	Description	Mandatory	Type
apikey	header	API Key	yes	string
x-timestamp	header	Date/time of the request (used to prevent replay attacks)	yes	string
x-request-id	header	Random ID used to identify the request	yes	string
x-hmac-signature	header	HMAC signature generated by combining the request parameters: Example: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL)`	yes	string
Authorization	header	Bearer token used for authentication	yes	string (bearerToken)
pixKey	path	Account's PIX Key	yes	string
clientId	path	Client id	yes	string

GET /v2/client/{clientId}/apm/pix/account/balance/{pixKey}

Consult the account balance by pix key.

Request Fields

Name	Located in	Description	Mandatory	Type
apikey	header	API Key	yes	string
x-timestamp	header	Date/time of the request (used to prevent replay attacks)	yes	string
x-request-id	header	Random ID used to identify the request	yes	string
x-hmac-signature	header	HMAC signature generated by combining the request parameters: Example: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL)`	yes	string
Authorization	header	Bearer token for authentication	yes	string (bearerToken)
clientId	path	Client Identifier	yes	string
pixKey	path	Pix Key of the account	yes	string

Response Fields

Field	Type	Additional Information
availableBalance	decimal	Available balance in the account
blockedBalance	decimal	Blocked balance in the account
totalBalance	decimal	Total balance in the account

Response Example

{
  "availableBalance": 2500000.42,
  "blockedBalance": 500000.18,
  "totalBalance": 3000000.6
}

GET /v1/client/{clientId}/apm/pix/accounts

View a customer's accounts.

Request Fields

Name	Located in	Description	Mandatory	Type
apikey	header	API Key	yes	string
x-timestamp	header	Date/time of the request (used to prevent replay attacks)	yes	string
x-request-id	header	Random ID used to identify the request	yes	string
x-hmac-signature	header	HMAC signature generated by combining the request parameters: Example: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL)`	yes	string
Authorization	header	Bearer token used for authentication	yes	string (bearerToken)
clientId	path	Client id	yes	string
pagination.currentPage	query	Page to be consulted	no	int
pagination.pageSize	query	Number of items per page	no	int

Response Example

{
  "content": [
    {
      "name": "Store Name",
      "tradeName": "Trade Store Name",
      "documentNumber": "40486138000167",
      "pixKey": "d60e6246-4885-471f-bab7-a3482f48d68b",
      "pixFee": {
        "amount": 0,
        "percentage": 2,
        "max": 0,
        "min": 0
      },
      "settlement": {
        "bankAccount": {
          "accountNumber": "12345-1",
          "agency": "1234",
          "bankCompeCode": "123",
          "document": {
            "number": "60.664.745/0001-87",
            "type": "CNPJ"
          },
          "ispb": "00000000",
          "type": 1
        },
        "pixKey": null
      },
      "status": "string",
      "hasAutomaticSettlement": true,
      "pspClientId": "7a2a1ed1-aa51-4a71-9b18-0ba6f6bcfee1",
      "pspClientSecret": "2ccd83fc-34ba-4a21-97ca-bef027cc2c70"
    }
  ],
  "totalElements": 1
}

GET /v1/apm/pix/accounts

Query an integrator's accounts.

Request Fields

Name	Located in	Description	Mandatory	Type
apikey	header	API Key	yes	string
x-timestamp	header	Date/time of the request (used to prevent replay attacks)	yes	string
x-request-id	header	Random ID used to identify the request	yes	string
x-hmac-signature	header	HMAC signature generated by combining the request parameters: Example: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL)`	yes	string
Authorization	header	Bearer token used for authentication	yes	string (bearerToken)
pagination.currentPage	query	Page to be consulted	no	int
pagination.pageSize	query	Number of items per page	no	int

Response Example

{
  "content": [
    {
      "name": "Store Name",
      "tradeName": "Trade Store Name",
      "documentNumber": "40486138000167",
      "pixKey": "d60e6246-4885-471f-bab7-a3482f48d68b",
      "pixFee": {
        "amount": 0,
        "percentage": 2,
        "max": 0,
        "min": 0
      },
      "settlement": {
        "bankAccount": {
          "accountNumber": "12345-1",
          "agency": "1234",
          "bankCompeCode": "123",
          "document": {
            "number": "60.664.745/0001-87",
            "type": "CNPJ"
          },
          "ispb": "00000000",
          "type": 1
        },
        "pixKey": null
      },
      "status": "string",
      "hasAutomaticSettlement": true,
      "pspClientId": "7a2a1ed1-aa51-4a71-9b18-0ba6f6bcfee1",
      "pspClientSecret": "2ccd83fc-34ba-4a21-97ca-bef027cc2c70"
    }
  ],
  "totalElements": 1
}

Additional Information

Response Error Codes

ErrorCode	Error
154	The fee must have a single value
158	Account not found
161	Account is not active
162	The PixKey must be different from the AddressPixKey
169	The settlement account provided is invalid
170	A settlement account is mandatory
171	It is not possible to inform two settlement accounts
174	The settlement account CNPJ is invalid
176	It is not possible to change the settlement information for this account
177	It is not possible to change the tax rate for this account
178	The ISPB code or COMPE code must be filled in
182	ISPB is not valid for the informed COMPE code.
187	Maximum tax rate must be greater than minimum tax rate
188	Minimum tax rate must be reported because maximum tax rate has been reported
189	The minimum tax rate must be greater than or equal to zero
190	Maximum tax rate must be greater than zero
191	The minimum and maximum tax rate should only be reported in the case of an MDR rate
260	The minimum tax rate must be equal to or greater than {value}.
261	The tax rate must be equal to or greater than {value}.
262	It is not possible to specify an account as the settlement destination for a split payment if the specified destination account also has split payments enabled.
263	Split settlement destination account not found.
267	The destination account for split settlement cannot have split configured.

Updated 7 days ago