PSP FISERV - API Pix

This documentation details the Fiserv PSP APIs, designed for integration with integrators, enabling the management of operations related to customers, accounts, collections and payments via Pix. The main functionalities include:

Authentication: Obtain tokens for all transactions authentication
Customer Management: Add, update, view and delete (CRUD) for customers
Account Management: Add, update, view and delete (CRUD) accounts
Pix Charges Generation: Create Pix charges efficiently and securely, allowing your customers to make payments via Pix
Pix Payment Query: View the status and details of payments via Pix for greater control and transparency
Refunds: Make payment refunds via Pix efficiently, ensuring customer satisfaction
Settlement: Automatically or manual cash-out
Webhook Management: Register webhooks to receive automatic notifications about important events such as payment confirmations or refund requests
Reports: Generate detailed reports of Pix transactions, facilitating the monitoring of operations and reporting of settlements related to accounts

¹ KYC - "Know your Customer" client validation process

Environments#

Production

https://connect.latam.fiservapis.com/gateway

Tests

https://connect-cert.latam.fiservapis.com/gateway

Table of contents#

📍Auth #

📍Webhooks #

🔻Callbacks #

📍Customer #

📍Accounts #

📍Transactions #

📍Cash-out #

📍Reports #

📍Additional Information #

🔻Default error object #

🔻Default Header #

🔻HMAC Calculation #

🔻For testing purposes #

#

Authentication#

🔒 /token#

POST#

Authentication Token generation endpoint, which is required for all calls. Obtain the authentication token using a client_secret and client_id, send it via application/x-www-form-urlencoded, and use the Bearer token in subsequent requests.

Parameters#

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

Request example#

application/x-www-form-urlencoded

Field	Value
client_id	user1234
client_secret	userPassword@123

Responses#

Code	Description
200	Returns the access token and expiration information

Response example#

{
  "access_token": "your-access-token",
  "expires_in": 300
}

#

Webhook#

/v1/webhook#

Configures (creates) the integrator's webhook to receive notifications for customer registration, payment, and chargeback. Here, the URL of the endpoint on the integrator's side must be provided; this endpoint will receive notifications when any asynchronous stage is completed. Examples of Callback are described below.

ATTENTION: To update the webhook URL, it is necessary to request it from the Fiserv team, as it is required to whitelist the URL on the proxy.

PUT#

Set up the Integrator Webhook, which is the URL of the endpoint that will receive the notification.

Parameters#

Name	Located in	Description	Mandatory	Type
webhookUrl	body	URL that will be called in the callback	yes	string
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)

Request example#

{
  "webhookUrl": "https://pix.example.com/api/webhook/"
}

Responses#

Code	Description
204	Webhook for notifications to the integrator.
400	Request with invalid format.
503	Service Unavailable

GET#

Displays the Integrator Webhook URL, noting that it will only receive callbacks if it is authorized by the Fiserv team.

Parameters#

Name	Located in	Description	Mandatory	Type
Authorization	header	Bearer token used for authentication	yes	string (bearerToken)
webhookUrl	body	URL that will be called in the callback	yes	string
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

Responses#

Code	Description
200	Webhook data
503	Service Unavailable

DELETE#

Deletes the Integrator Webhook URL, which will no longer receive notifications for asynchronous processes after deletion. It will only be possible to receive notifications again by registering a new URL and requesting authorization from the Fiserv team.

Parameters#

Name	Located in	Description	Mandatory	Type
webhookUrl	body	URL that will be called in the callback	yes	string
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)

Responses#

Code	Description
204	Webhook for Pix notifications canceled.
503	Service Unavailable

#

CALLBACKS#

Customer#

POST /client#

After the customer registration and the KYC(1) process is completed, the URL registered for the webhook receives the following notification:

{
     "protocolId":"347acdf2-7b01-4191-acff-36bd23639e43",
     "externalProtocolId":"8dd562ee4a7a",
     "omniClientId":"f932d207-573c-439c-b444-6ca26afff066",
     "document":{
        "type":"CNPJ",
        "number":"60664745000187"
         },
    "status":"DONE",
    "errors ":[ {
        "code":"FEP_123",
        "message":"string"
     }
         ]
 }

⚠️ Since this is a testing environment, KYC has different approval/rejection rules compared to the production environment; therefore, it is necessary to send the approved CNPJ(s) to the Fiserv team to facilitate development.

⚠️ When Status = DONE, indicates that processing has been completed in the final KYC(1) status and the customer information can be requested.

Transactions#

POST /v1/apm/pix/charges#

After the transaction charge is completed, the URL registered in the webhook receives the following notification:

{
    "Pix": {
        "endToEndId":"D13207930202410252046wrzeq7wrQZ8",
        "txid":"D13207930202410252034KgylGnIt2T3",
        "chave":"ac2ce947-fa51-4dd1-a4f9-52181bcc971f",
        "Status":1,
        "OperationType":2
    }
}

Field	Type	Description
Pix.endToEndId	string	End to End of payment confirmation
Pix.txid	string	Transaction id
Pix.chave	string	Account Pix Key
Pix.Status	string	Transaciton Status : 0 - Pending 1 - Confirmed 2 - Canceled
Pix.OperationType	string	Operation Type: 0 - Charge 1 - Refund 2 - Reverse

ction Type (0 – Charge, 1- Refund, 2 – Reverse |

PUT /v1/apm/pix/{endToEndId}/reverse/{txid} .#

After the transaction reverse is completed, the URL registered in the webhook receives the following notification:

{
    "Pix": {
        "endToEndId":"D13207930202410252046wrzeq7wrQZ8",
        "txid":"D13207930202410252034KgylGnIt2T3",
        "chave":"ac2ce947-fa51-4dd1-a4f9-52181bcc971f",
        "Status":1,
        "OperationType":2
    }
}

Field	Type	Description
Pix.endToEndId	string	End to End of payment confirmation
Pix.txid	string	Transaction id
Pix.chave	string	Account Pix Key
Pix.Status	string	Transaction Status : 0 - Pending 1 - Confirmed 2 - Canceled
Pix.OperationType	string	Operation Type: 0 - Charge 1 - Refund 2 - Reverse

Cash-out#

POST /v2/apm/pix/cashout#

After the cashout request is made, the URL registered in the webhook receives the notification below:

{
  "pix": [
    {
      "txid": "bec7e05d-484e-4814-a432-dde637f84408",
      "endToEndId": null,
      "createdAt": "2025-01-16 09:33:01.573Z",
      "confirmedAt": "2025-01-16 09:33:01.573Z",
      "pixKey": "883f75da-1f69-48c4-9444-c32b4bcb3553",
      "receiverDocument": "3626416467",
      "receiverPixKey": "pix-key-receiver@mail.com",
      "amount": 99.99,
      "confirmationKey": "4826e6ec-9bd2-4045-b030-f10e519d584a",
      "status": 2,
      "operationType": 7
    }
  ]
}

Field	Type	Description
Pix.txid	string	Id transaction
Pix.endToEndId	string	End to End of payment confirmation; it will always be null until the withdrawal confirmation.
Pix.createdAt	DateTime (ISO 8601)
Pix.confirmedAt	DateTime (ISO 8601)	Date and time of the request.
Pix.pixKey	string	Pix Key of Fiserv Account (source)
Pix.receiverDocument	string	Destination account document.
Pix.receiverPixKey	string	Pix key of the destination account.
Pix.amount	decimal	Cash-out Value
Pix.confirmationKey	string	Random key for the withdrawal confirmation.
Pix.Status	string	Transaction Status: 0 - Pending 1 - Requested 2 - Authorized (Payment processing) 3 - Confirmed 4 - Failed 5 - Expired
Pix.OperationType	string	Operation Type: 7 - Manual Withdrawal

Cashout callback occurs in two stages as described below:

⚠️ After requesting a withdrawal operation, some validations will be performed asynchronously, and the request may still be denied. The result of this validation, along with the confirmation key needed for the confirmation request, will be sent to the webhook..

⚠️ Once the confirmation key is received from the notification, the confirmation request (/cashout/confirm) must be called to confirm the withdrawal. After the confirmation, the withdrawal may still fail in some scenarios, thus a new notification will be sent to the configured webhook to indicate whether the withdrawal was completed successfully (status 1) or if it failed (status 2). The confirmation payload has the same structure as the withdrawal request payload, with the only main difference being in the "status."

#

Client#

/v1/client#

#

POST#

Add a client.

Parameters#

Name	Located in	Type	Description	Mandatory
apikey	header	string	API Key	yes
x-timestamp	header	string	Date/time of the request (used to prevent replay attacks)	yes
x-request-id	header	string	Random ID used to identify the request	yes
x-hmac-signature	header	string	HMAC signature generated by combining the request parameters: Example: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL)`	yes
Authorization	header	string (bearerToken)	Bearer token used for authentication	yes
address.city	body	string	Client's city (ISO 3166)	yes
address.country	body	string	Client's country (ISO 3166)	yes
address.locality	body	string	Client's district (ISO 3166)	yes
address.number	body	string	Client's address number	no
address.postalCode	body	string	Client's ZIP Code address	yes
address.province	body	string	Client's adress State	yes
address.street	body	string	Client's adress Street	yes
address.subNumber	body	string	Client's adress Complement	no
document.number	body	string	Document Number	yes
document.type	body	enum	CNPJ	yes
contact.email	body	string	Client's E-mail	yes
contact.phone	body	string	Client's Phone number	yes
legalName	body	string	Client's legal name	yes
tradeName	body	string	Client's trade name	yes
averageTicket	body	decimal	Average ticket	yes

Request example#

{
  "address": {
    "city": "string",
    "country": "str",
    "locality": "string",
    "number": "153",
    "postalCode": "string",
    "province": "string",
    "street": "string",
    "subNumber": "string"
  },
  "document": {
    "number": "60.664.745/0001-87",
    "type": "CNPJ"
  },
  "contact": {
    "email": "user@example.com",
    "phone": "string"
  },
  "legalName": "Fiserv Inc",
  "tradeName": "Fiserv",
  "averageTicket": 100.00
}

⚠️ Since this is a testing environment, the KYC(1) has different approval/rejection rules compared to the production environment. Therefore, it is necessary to send the approved CNPJ(s) to the Fiserv team to facilitate development.

Responses#

Name	Description	Type
clientId	Customer's unique ID	string
protocolId	Request protocol	string

Response example#

{
  "clientId": "bb41c1e6-654f-4263-83f4-36e37678f548",
  "protocolId": "Request protocol"
}

After the client registration a KYC validation will happen asynchronously, and the result will be notified to the configured webhook.

Code	Description
200	OK
400	Bad Request
403	Forbidden
404	Not Found
500	Internal Server Error
503	Service Unavailable
504	Gateway Timeout

/v1/client/{clientId}#

#

GET#

Search for information about the customer's "Know Your Customer" status.

Parameters#

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 id	yes	string
webhookUrl	body	URL that will be called in the callback	yes	string

Responses#

{
  "kycStatus": "Approved"
}

The KycSytatus can be one of the following:
🔸 APPROVED
🔸 PENDING
🔸 PROCESSING
🔸 REFUSED
🔸 ERROR

⚠️ Only the APPROVED status can allow the continuation of the accreditation process and the creation of a Pix Account

Code	Description
200	OK
400	Bad Request
403	Forbidden
404	Not Found
500	Internal Server Error
503	Service Unavailable
504	Gateway Timeout

#

Pix Account#

General Information about Account Management#

pixFee#

Pix fee is the fee charged for each transaction made. When the business model is commission-based, fee can be a fixed amount (amount) or MDR - Merchant Discount Rate (percentage) . Alternatively, when the business model is billing, it must not have any value.

Example of a commission-based business model with a fixed fee#

Registered fee for the account: R$ 0,85

Charged value: R$ 30,00

Fee value: R$ 0,85

Net amount: R$ 29,15

Example of a commission-based business model with MDR#

Registered fee for the account: 1%

Charged value: R$ 22,00

Fee value: R$ 0,22

Net amount: R$ 21,78

To use a zero rate, set fee.amount = 0

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

#

POST#

Add a pix account.

Parameters#

Field	Located in	Type	Mandatory	Description
name	body	string	no	Account name, if not provided, defaults to value
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	string	header	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
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”
Settlement.holdSettlement	body	bool	no	Identifies if charges are created with settlement hold (default false)
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
userTermsAccept.number.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.
hasAutomaticSettlement	body	boolean	yes	Indicates if settlement occurs automatically

Request example#

{
  "name" : "account name",
  "settlement": {
    "pixKey": "26770318000145",
    "bankAccount": {
      "accountNumber": "12345-1",
      "agency": "1234",
      "bankCompeCode": "341",
      "document": {
        "number": "60.664.745/0001-87",
        "type": "CNPJ"
      },
      "type": 1
    },
    "holdSettlement": true
  },
  "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"
  },
  "hasAutomaticSettlement": true
}

Response example#

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

Responses#

Code	Description
200	OK
400	Bad Request
401	Unauthorized
422	Client Error
500	Server Error

Possible errors:#

ErrorCode	Error
154	The fee must have a single value
158	Account not found
161	The account is not activated
162	The PixKey must be different from the AddressPixKey
169	The settlememt account provided is invalid.
170	A settlememt account is mandatory
171	It is not possible to inform two settlememt accounts
174	The liquidation account of the 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
187	Maximum tax rate must be greater than minimum tax rate
188	Minimum rate must be reported because maximum 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	Invalid settlement account for the split payment not found.
267	The destination account for split settlement cannot have split configured.

/v1/client/{clientId}/apm/pix/account/{pixKey}'#

GET#

Return an account based on the PIX key.

Parameters#

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#

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
settlement.bankAccount.holdSettlement	boolean	Indicates if charges are created as blocked and should not be settled.
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

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
    },
    "holdSettlement": true
  },
  "pixFee": {
    "amount": 0,
    "percentage": 2,
    "max": 0,
    "min": 0
  },
  "splitPixKey": "30001d73-4917-4a41-bb8f-9624b4910ff3",
  "hasAutomaticSettlement": true,
  "pspClientId": "7a2a1ed1-aa51-4a71-9b18-0ba6f6bcfee1",
  "pspClientSecret": "2ccd83fc-34ba-4a21-97ca-bef027cc2c70"
}

Responses#

Code	Description
200	Success
400	Bad Request
401	Unauthorized
422	Client Error
500	Server Error

⚠️ Every night during the early morning hours, automatic settlement of amounts is performed for accounts that have HasAutomaticSettlemnt = true. For cases where the value is "false", the withdrawal of funds from the account is carried out manually via the Cash-out endpoints

/v1/client/{clientId}/apm/pix/account/{pixkey} .#

PUT#

Change a pix account.

Description:#

Endpoint that changes a pix account.

Parameters#

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.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”
Settlement.holdSettlement	body	bool	no	Identifies if charges are created with liquidation hold (default false)
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.
hasAutomaticSettlement	body	boolean	yes	Indicates if settlement occurs automatically

Request example#

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

Responses#

Code	Description
204	No Content
400	Bad Request
401	Unauthorized
422	Client Error
500	Server Error

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 settlememt account provided is invalid
170	A settlememt account is mandatory
171	It is not possible to inform two settlememt 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
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	Invalid settlement account for the split payment not found.
267	The destination account for split settlement cannot have split configured.

/v1/client/{clientId}/apm/pix/account/{pixKey} .#

DELETE#

Delete a pix account.

Description:#

Endpoint to delete a pix account.

Parameters#

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

Responses#

Code	Description
204	No Content
400	Bad Request
401	Unauthorized
422	Client Error
500	Server Error

/v2/client/{clientId}/apm/pix/account/balance/{pixKey} ´#

GET#

Consult the account balance by pix key.

Parameters#

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

Responses#

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
}

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

GET#

View a customer's accounts.

Parameters#

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

Responses#

Code	Description
200	OK
400	Bad Request
401	Unauthorized
422	Client Error
500	Server Error

Response example#

{
  "content": [
    {
      "name": "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
}

/v1/apm/pix/accounts#

GET#

Query an integrator's accounts.

Parameters#

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

Responses#

Code	Description
200	OK
400	Bad Request
401	Unauthorized
422	Client Error
500	Server Error

Response example#

{
  "content": [
    {
      "name": "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
}

#

## Pix Transaction

/v1/apm/pix/charge#

#

POST#

Create pix charge.

Description:#

Endpoint to create an pix charge.

Parameters#

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)
amount	body	Charge amount	yes	decimal
pixKey	body	Account's Pix Key	yes	string
returnQrCodeImage	body	Indicator that returns the qrCode image (false default)	yes	bool
expiration	body	QRcode expiration time in seconds	yes	int

Request example#

{
  "expiration": 3600,
  "amount": "18.92",
  "returnQrCodeImage": false,
  "additionalInfo": [
    {
      "name": "Title of information",
      "value": "Content of information"
    }
  ],
  "pixKey": "b57c7b3c-976b-41f6-a5f6-7cccd86549bd",
  "payerDocument": "36264164615"
}

Responses#

Field	Type	Additional Information
txid	string	Transaction ID generated
location	string	Located in of the generated QRCode
qrCodeImage	bool	Base64 image of the QRcode (Only when returnQrCodeImage= true is specified)
status	string	Transaction status. Possible values: ATIVA(PENDING);CONCLUIDA(CONFIRMED); REMOVIDA_PELO_USUARIO_RECEBEDOR (CANCELLED)
amount	decimal	Transaction value
pixCopyPaste	string	Copy and paste code from Pix
pixKey	string	Pix key used for the transaction

Code	Description
200	Pix charge created
400	Request with invalid format
404	The requested content was not found
503	This service is currently unavailable

Response example#

{
  "txid": "ALzljVvS6DWp9ubnflS3nnCdeVBg7AxVt2p",
  "location": "pix.example.com/qr/v2/2353c790eefb11eaadc10242ac120002",
  "qrCodeImage": null,
  "status": "ATIVA",
  "amount": "18.92",
  "additionalInfo": [
    {
      "name": "Title of information",
      "value": "Content of information"
    }
  ],
  "pixCopyPaste": "00020101021226830014BR.GOV.BCB.PIX2561api-h.rendimento.com.br/q/v2/aeafe31da3ef48c295e6353d703415da5204000053039865802BR5915Teste-automacao6009SAO PAULO61081125553262070503***6304BE8A",
  "pixKey": "b57c7b3c-976b-41f6-a5f6-7cccd86549bd"
}

Error	Description
157	This charge does not have a fee amount
96	The settlement schedule date is less than the current date
153	The account for this pix key is not active
157	This charge does not have a fee amount
158	Account not found
167	Account suspended for billing processing
193	The charge cannot be null or negative
259	The split value cannot be negative.

/v1/apm/pix/charge/{txid} .#

GET#

Check immediate billing through a specific txid.

Parameters#

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)
txid	path	Transaction Id	yes	string
returnQrCodeImage	query	Indicator whether QrCode should be generated in base64 or not	no	boolean

Responses#

{
    "txid": "string",
    "amount": 99.99,
    "status": "status",
    "location": "string",
    "pixCopyAndPaste": "string",
    "qrCodeImage": "string"
}

Code	Description
200	Data from a immediate pix charge
404	The requested content was not found
503	This service is currently unavailable

Response example#

{
  "expiration": 3600,
  "amount": "18.92",
  "returnQrCodeImage": false,
  "additionalInfo": [
    {
      "name": "Title of information",
      "value": "Content of information"
    }
  ],
  "pixKey": "b57c7b3c-976b-41f6-a5f6-7cccd86549bd",
  "txid": "ALzljVvS6DWp9ubnflS3nnCdeVBg7AxVt2p",
  "location": "pix.example.com/qr/v2/2353c790eefb11eaadc10242ac120002",
  "qrCodeImage": null,
  "status": "1",
  "pixCopyPaste": "00020101021226830014BR.GOV.BCB.PIX2561api-h.rendimento.com.br/q/v2/aeafe31da3ef48c295e6353d703415da5204000053039865802BR5915Teste-automacao6009SAO PAULO61081125553262070503***6304BE8A",
  "createdAt": "2025-06-06T04:32:06.055Z",
  "pix": [
    {
      "endToEndId": "EDARFlxoxT0zBhFBqEIC6c2QQCo2d54U",
      "amount": "231.39",
      "pixKey": "b57c7b3c-976b-41f6-a5f6-7cccd86549bd",
      "confirmedAt": "2025-06-06T04:32:06.055Z",
      "inconsistencyReproval": null,
      "reverses": [
        {
          "txid": "DLzljVvS6DWp9ubnflS3nnCdeVBg7AxVt2h",
          "endToEndId": "D12345678202009091000abcde123456",
          "amount": "231.39",
          "confirmedAt": "2025-06-06T04:32:06.055Z",
          "status": "1"
        }
      ]
    }
  ]
}

/v1/apm/pix/charge/cancel/{txid} '#

PATCH#

Cancel immediate charge.

Parameters#

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)
txid	path		yes	string

Responses#

Code	Description
204	No Content
400	Request with invalid format
404	The requested content was not found
503	This service is currently unavailable

/v1/apm/pix/charges#

GET#

Check the list of immediate charges using parameters such as start, end, CPF, CNPJ and status.

Parameters#

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)
startDate	query	Start date to filter the query	yes	timezone (ISO 8601)
endDate	query	End date to filter the query	yes	timezone (ISO 8601)
pixKey	query	Account Pix Key	no	string
documentNumber	query	CNPJ number	no	string
status	query	Status of the transactionPossible values: 1 - CONFIRMED; 2 - CANCELLED
no	string
pagination.currentPage	query		no	int
pagination.pageSize	query		no	int

Responses#

Code	Description
200	List of pix charges
503	This service is currently unavailable

Response#

Property	Type	Description
results.txid	string	Pix charge unique identifier
results.location	string	Payloads location
results.qrCodeImage	bool	Base64 of the QrCode image
results.status	string (enum)	Status of the pix charge. Possible values: ATIVA(PENDING);CONCLUIDA(CONFIRMED); REMOVIDA_PELO_USUARIO_RECEBEDOR (CANCELLED)
results.amount	decimal	Amount of the pix charge (BRL)
results.pixCopyPaste	string	Copy and paste code
results.pixKey	string	Internal pix key of the account
results.expiration	int	Lifetime of the pix charge before expiration, specified in seconds
results.createdAt	DateTime (ISO 8601)	Date and time of creation
results.pix.confirmedAt	DateTime (ISO 8601)	Date and time of confirmation
results.pix.endToEndId	string	Unique end to end id for the pix charge
results.pix.amount	decimal	Amount of the payment (BRL)
results.pix.pixKey	string	Pix key of the receiver
pix.inconsistencyReproval	enum	In case of reproval by the inconsistency prevention engine, this field will be populated with the following value: 1 - Inconsistency
results.pix.reverses.txid	string	Refunds unique identifier
results.pix.reverses.endToEndId	string	Unique end to end id for the refund
results.pix.reverses.amount	decimal	Refunded amount (BRL)
results.pix.reverses.confirmedAt	DateTime (ISO 8601)	Date and time of refund
results.pix.reverses.status	int (enum)	Status of the refund. Possible values: 1 - CONFIRMED 2 - CANCELLED
pagination.currentPage	int	Current page retrieved
pagination.pageSize	int	Current page size
pagination.totalPages	int	Total pages to be retrieved
pagination.totalItems	int	Total items to be retrieved
criteria.startDate	DateTime (ISO 8601)	Filter transactions after this date and time
criteria.endDate	DateTime (ISO 8601)	Filter transactions before this date and time
criteria.pixKey	string	Pix key of the account
criteria.documentNumber	string	Document number of the account
criteria.status	string	Status of the transaction values: 0 - PENDING; 1 - CONFIRMED; 2 - CANCELLED

Response examples#

{
  "criteria": {
    "startDate": "2020-04-01T00:00:00Z",
    "endDate": "2020-04-01T17:00:00Z",
    "pixKey": "b57c7b3c-976b-41f6-a5f6-7cccd86549bd",
    "documentNumber": "27574383000168",
    "status": 1
  },
  "results": [
    {
      "expiration": 3600,
      "amount": "18.92",
      "returnQrCodeImage": false,
      "additionalInfo": [
        {
          "name": "Title of information",
          "value": "Content of information"
        }
      ],
      "pixKey": "b57c7b3c-976b-41f6-a5f6-7cccd86549bd",
      "txid": "ALzljVvS6DWp9ubnflS3nnCdeVBg7AxVt2p",
      "location": "pix.example.com/qr/v2/2353c790eefb11eaadc10242ac120002",
      "qrCodeImage": null,
      "status": "CONCLUIDA",
      "pixCopyPaste": "00020101021226830014BR.GOV.BCB.PIX2561api-h.rendimento.com.br/q/v2/aeafe31da3ef48c295e6353d703415da5204000053039865802BR5915Teste-automacao6009SAO PAULO61081125553262070503***6304BE8A",
      "createdAt": "2025-06-06T04:35:23.707Z",
      "pix": [
        {
          "endToEndId": "EDARFlxoxT0zBhFBqEIC6c2QQCo2d54U",
          "amount": "231.39",
          "pixKey": "b57c7b3c-976b-41f6-a5f6-7cccd86549bd",
          "confirmedAt": "2025-06-06T04:35:23.707Z",
          "inconsistencyReproval": null,
          "reverses": [
            {
              "txid": "DLzljVvS6DWp9ubnflS3nnCdeVBg7AxVt2h",
              "endToEndId": "D12345678202009091000abcde123456",
              "amount": "231.39",
              "confirmedAt": "2025-06-06T04:35:23.707Z",
              "status": "ATIVA"
            }
          ]
        }
      ]
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 1,
    "totalPages": 1,
    "totalItems": 1
  }
}

/v1/apm/pix/{endToEndId}/reverse/{txid} '#

#

PUT#

Request a refund.

Parameters#

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)
endToEndId	path	End to end transaction code	yes	string
txid	path	Transaction Id	yes	string
amount	body	Transaction amount	yes	string

Request example#

{
  "amount": "231.39"
}

Responses#

Code	Description
200	Return data
400	Request with invalid format
404	The requested content was not found
503	This service is currently unavailable

Response example#

{
  "txid": "DLzljVvS6DWp9ubnflS3nnCdeVBg7AxVt2h",
  "endToEndId": "D12345678202009091000abcde123456",
  "amount": "231.39",
  "confirmedAt": "2025-06-06T04:37:07.173Z",
  "status": "ATIVA"
}

GET#

Check return using a Pix End To End ID and return ID.

Parameters#

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)
endToEndId	path	Payment End To End Code	yes	string
txid	path	Transaction Id	yes	string

Responses#

Code	Description
200	Refunds data
404	The requested content was not found
503	This service is currently unavailable

Response example#

{
  "txid": "DLzljVvS6DWp9ubnflS3nnCdeVBg7AxVt2h",
  "endToEndId": "D12345678202009091000abcde123456",
  "amount": "231.39",
  "confirmedAt": "2025-06-06T04:40:25.725Z",
  "status": "0"
}

/v1/apm/pix/charge/settlement/hold/{txid} '#

PATCH#

Block the pix charge settlement until it's unblocked.

/v1/apm/pix/charge/settlement/release/{txid}'#

Parameters#

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
txid	path	Charge unique identifier	yes	string

Responses#

Code	Description
204	No Content
400	Request with invalid format
404	Request content not found
503	Service unavailable

/v1/apm/pix/charge/settlement/release/{txid}'#

PATCH#

Allows the pix charge to be settled in the next settlement window.

Parameters#

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
txid	path	Charge unique identifier	yes	string

Responses#

Code	Description
204	No Content
400	Request with invalid format
404	Request content not found
503	Service unavailable

#

Cash-out#

/v2/apm/pix/cashout#

POST#

Create pix cashout.

Parameters#

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)
amount	body	Amount to cashout (BRL)	yes	decimal
pixKey	query	Internal pix key of the account	yes	string
receiverPixKey	body	Pix key of the receiver, must belong to the receiverDocument	yes	bool
receiverDocument	body	Document of the receiver, will be validated together with the pix key	yes	string

Request example#

{
  "pixKey": "tec7e05d-484e-4814-a432-dde637f84402",
  "receiverDocument": "36264164615",
  "receiverPixKey": "pix-key-receiver@mail.com",
  "amount": 99.99
}

Responses#

Field	Type	Additional Information
txid	string	Cashouts unique identifier

Response example#

{
  "txid": "2a2cc743-3913-48ea-91fe-13256ab3c3d2"
}

After successfully requesting the cashout operation some validations will be made asynchronously, and the cashout might still be denied. The result from this validation, together with the confirmation key necessary for the confirmation request (next endpoint), will be sent to the webhook .

GET#

Search and retrieve cash-outs. Allows for batch reconciliation.

Parameters#

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	query	Pix key of the account	yes	string
startDate	query	Filter cashouts after the startDate	yes	DateTime (ISO 8601)
endDate	query	Filter cashouts before the endDate	yes	DateTime (ISO 8601)
status	query	Status of the cashout.	yes	Possible values: Pending Requested Authorized Confirmed Failed Expired
pagination.currentPage	int	Actual page	yes
pagination.pageSize	int	Page size	yes

Responses#

Field	Type	Additional Information
result.txid	string	Unique identifier of the cashout operation
result.endToEndId	string	Unique end to end id for the pix transaction, will always be null until the confirmation of the cashout (item X+1)
result.createdAt	DateTime (ISO 8601)	Date and time of the cashout creation
result.confirmedAt	DateTime (ISO 8601)	Date and time of the cashout confirmation
result.pixKey	string	Internal accounts pix key
result.receiverDocument	string	Document of the cashouts receiver
result.receiverPixKey	string	Pix key of the cashouts receiver
result.amount	decimal	Amount of the cashout (BRL)
result.status	int (enum)	Cashout Status: Pending Requested Authorized Confirmed Failed Expired
result.failReason	Int(enum)	Fail Reason (Only when status is Failed) 1 - Without limit 2 - Without balance 3 - Expired 4 - Concurrency 5 - Processing Fail 6 - Inconsistency
criteria.pixKey	string	Account Pix Key Chave Pix used in filter
criteria.startDate	DateTime (ISO 8601)	Initial Date used in filter
criteria.endDate	DateTime (ISO 8601)	End Date used in filter
criteria.status	int (enum)	Withdrawal Status Possible Values: Transaction Status: 0 - Pending (Waiting for confirmation) 1 - Requested 2 - Processing (Processing payment) 3 - Confirmed (paid) 4 - Failed (Payment failed) 5 - Expired
pagination.currentPage	int	Current page retrieved
pagination.pageSize	int	Page size retrieved
pagination.totalPages	int	Total pages to retrieve
pagination.totalItems	int	Total items to retrieve

Response example#

{
  "criteria": {
    "startDate": "2025-01-16 09:33:01.573Z",
    "endDate": "2025-01-16 09:33:01.573Z",
    "pixKey": "b57c7b3c-976b-41f6-a5f6-7cccd86549bd",
    "status": 2
  },
  "result": [
    {
      "txid": "bec7e05d-484e-4814-a432-dde637f84408",
      "endToEndId": "E144654798498498465123",
      "createdAt": "2025-01-16 09:33:01.573Z",
      "confirmedAt": "2025-01-16 09:33:01.573Z",
      "pixKey": "883f75da-1f69-48c4-9444-c32b4bcb3553",
      "receiverDocument": "36264164615",
      "receiverPixKey": "pix-key-receiver@mail.com",
      "amount": 999.99,
      "status": "Confirmed",
      "failReason": null
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 10,
    "totalPages": 1,
    "totalItems": 1
  }
}

/v2/apm/pix/cashout/confirm#

POST#

Confirm a pix cashout request with the confirmation key.

Parameters#

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)
txid	body	Cashouts unique identifier	yes	string
confirmationKey	body	Confirmation key provided in the webhook notification payload	yes	string

Request example#

{
  "txid": "bec7e05d-484e-4814-a432-dde637f84408",
  "confirmationKey": "4826e6ec-9bd2-4045-b030-f10e519d584a"
}

After the confirmation the cashout can still fail in some scenarios, so another notification will be sent to the configured webhook to inform if the cashout was completed successfully.

Response#

Code	Description
204	No Content

/v2/apm/pix/cashout/{txid}'#

GET#

Retrieve cashout data with the txid. In case of delay or failure of the webhook notification, this endpoint can be used to check the cashout status.

Parameters#

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)
txid	path	Cashouts unique identifier	yes	string

Responses#

Field	Type	Additional Information
txid	string	Unique identifier of the cashout operation
endToEndId	string	Unique end to end id for the pix transaction, will always be null until the confirmation of the cashout
createdAt	DateTime (ISO 8601)	Date and time of the cashout creation
confirmedAt	DateTime (ISO 8601)	Date and time of the cashout confirmation
pixKey	string	Internal accounts pix key
receiverDocument	string	Document of the cashouts receiver
receiverPixKey	string	Pix key of the cashouts receiver
amount	decimal	Amount of the cashout (BRL)
status	int (enum)	Status of cashout: Pending Requested Authorized Confirmed Failed Expired
result.failReason	int (enum)	Fail Reason (Only when status is Failed). 1 - Withou limit 2 - Without balance 3 - Expired 4 - Concurrency 5 - Processing fail 6 - Inconsistency

Response example#

{
  "txid": "bec7e05d-484e-4814-a432-dde637f84408",
  "endToEndId": "E144654798498498465123",
  "createdAt": "2025-01-16 09:33:01.573Z",
  "confirmedAt": "2025-01-16 09:33:01.573Z",
  "pixKey": "883f75da-1f69-48c4-9444-c32b4bcb3553",
  "receiverDocument": "36264164615",
  "receiverPixKey": "pix-key-receiver@mail.com",
  "amount": 999.99,
  "status": 2,
  "failReason": 1
}

#

Reports#

/v1/apm/pix/report/transactions#

GET#

Consult list of charges.

Parameters#

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	query	Pix Key	no	string
documentNumber	query	Client id	no	string
startDate	query	Billing start date and time	no	timezone (ISO 8601)
endDate	query	Billing end date and time	no	timezone (ISO 8601)
settlementStartDate	query	Settlement start date and time	no	timezone (ISO 8601)
settlementEndDate	query	Settlement end date and time	no	timezone (ISO 8601)
txid	query	Transaction Id	no	string
endToEnd	query	End to End Confirmation Code	no	string
pagination.currentPage	query	Current page	yes	integer
pagination.pageSize	query	Number of items per page	yes	integer

Responses#

Code	Description
200	Success
400	Bad Request
401	Unauthorized
422	Client Error
500	Server Error

Response example#

{
  "criteria": {
    "startDate": "2020-04-01T00:00:00Z",
    "endDate": "2020-04-01T17:00:00Z",
    "pixKey": "string",
    "documentNumber": "string",
    "status": "string"
  },
  "results": [
    {
      "expiration": 3600,
      "amount": "2221.39",
      "returnQrCodeImage": true,
      "pixKey": "string",
      "additionalInfo": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "txid": "69xWbpREB9fvZ5oUr7HPNSlm5r6cclBy3Gk0",
      "location": "pix.example.com/qr/v2/2353c790eefb11eaadc10242ac120002",
      "qrCodeImage": "string",
      "status": "ATIVA",
      "pixCopyPaste": "string",
      "createdAt": "2024-12-17T19:42:50.414Z",
      "pix": [
        {
          "endToEndId": "jt86OxM1YwTvUuMsZpjGIhZlcodBS8GD",
          "amount": "52.34",
          "pixKey": "string",
          "confirmedAt": "2024-12-17T19:42:50.414Z",
          "reverses": [
            {
              "txid": "kXrK2W2mFxOQ8NEXH",
              "endToEndId": "D12345678202009091000abcde123456",
              "amount": "7163749810.26",
              "confirmedAt": "2024-12-17T19:42:50.414Z",
              "status": "1"
            }
          ]
        }
      ]
    }
  ],
  "pagination": {
    "currentPage": 0,
    "pageSize": 1,
    "totalPages": 1,
    "totalItems": 0
  }
}

/v2/apm/pix/report/transactions#

GET#

Search transactions statement

Parameters#

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	query	Pix key of the account	no	string
documentNumber	query	Document number of the account	no	string
startDate	query	Filter transactions after this date and time	yes	DateTime (ISO 8601)
endDate	query	Filter transactions before this date and time	yes	DateTime (ISO 8601)
txid	query	Transactions unique identifier	no	string
endToEndId	query	Pix transaction unique end to end identifier	no	string
pagination.currentPage	query	Page number to be retrieved	yes	integer
pagination.pageSize	query	Page size to be retrieved	yes	integer

Responses#

Field	Type	Additional Information
result.txid	string	Transactions unique identifier
result.amount	decimal	Amount of the transaction (BRL)
result.movementType	int (enum)	Type of movement Possible values: 0 - Debit 1 - Credit
result.transactionType	int	Transaction Type Possible values: 0 - Charge; 1 – Reverse; 2 - PixChargeLock(special refund) 3 – PixChargeUnlock (special refund) 4 – PixSpecialRefund 5 - Refund 6 – Bacen Jud transfer 7 - Bacen Jud Lock 8 – Bacen Jud Unlock 9 – Automatic Settlement 10 – Manual Settlement 11 - Fee 12 - Fee Reverse 13 - Special Refund Reverse 14 - Management Adjustment
result.accountCnpj	string	Account CNPJ
result.createdAt	DateTime (ISO 8601)	Date and time of creation
result.endToEndId	string	Unique end to end id for the transaction
result.inconsistencyReproval	enum	In case of reproval by the inconsistency prevention engine, this field will be populated with the following values: 1 - Inconsistency
result.thirdPartyName	string	Name of the third party (external) involved in the transaction
pagination.currentPage	int	Current page retrieved
pagination.pageSize	int	Current page size
pagination.totalPages	int	Total pages to be retrieved
pagination.totalItems	int	Total items to be retrieved
criteria.startDate	DateTime (ISO 8601)	Filter transactions after this date and time
criteria.endDate	DateTime (ISO 8601)	Filter transactions before this date and time
criteria.pixKey	string	Pix key of the account
criteria.documentNumber	string	Document number of the account
criteria.txid	string	Transactions unique identifier
criteria.endToEndId	string	Unique end to end id for the transaction
summary.sumAmountCredits	decimal	Sum of all credits for the searched filters
summary.sumAmountDebits	decimal	Sum of all debits for the searched filters

Responses#

Code	Description
200	Success
400	Bad Request
401	Unauthorized
422	Client Error
500	Server Error

Response example#

{
  "criteria": {
    "pixKey": "4d2dd55d-d1ab-492b-868e-6b1a2791dc0b",
    "documentNumber": "14821268000107",
    "startDate": "2025-01-01",
    "endDate": "2029-12-31",
    "txid": "2a2cc743-3913-48ea-91fe-13256ab3c3d2",
    "endToEndId": "E144654798498498465123"
  },
  "result": [
    {
      "createdAt": "2025-06-06T04:57:20.882Z",
      "movementType": 1,
      "transactionType": 1,
      "amount": 99.99,
      "endToEndId": "EDARFlxoxT0zBhFBqEIC6c2QQCo2d54U",
      "txid": "42474ba2-fd99-43b9-b688-52fb7a74106d",
      "accountCnpj": "14821268000107",
      "thirdPartyName": "John Mary",
      "inconsistencyReproval": 1
    }
  ],
  "summary": {
    "sumAmountCredits": 99.99,
    "sumAmountDebits": 0
  },
  "pagination": {
    "currentPage": 1,
    "pageSize": 1,
    "totalPages": 1,
    "totalItems": 1
  }
}

/v1/apm/pix/report/settlements#

GET#

Consult the list of liquidations.

Parameters#

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	query	Account's Pix Key	no	string
documentNumber	query	CNPJ number	no	string
startDate	query	Start date for consultation	no	timezone (ISO 8601)
endDate	query	End date for consultation	no	timezone (ISO 8601)
status	query		no	GetLiquidationsInStatus
pagination.currentPage	query	Current Page	yes	integer
pagination.pageSize	query	Itens per page	no	integer

#

Get Liquidations Status#

Code	Status
0	Pending
1	Confirmed
2	Fail

Responses#

Code	Description
200	Success
400	Bad Request
401	Unauthorized
422	Client Error
500	Server Error

Response example#

{
  "criteria": {
    "pixKey": "string",
    "documentNumber": "string",
    "startDate": "string",
    "endDate": "string",
    "status": "string"
  },
  "results": [
    {
      "totalAmount": 0,
      "totalGrossAmount": 0,
      "totalFeeAmount": 0,
      "status": 0,
      "errorMessage": "string",
      "createdAt": "2024-12-17T20:17:24.421Z",
      "endToEnd": "string",
      "settlement": {
        "pixKey": "string",
        "bankAccount": {
          "accountNumber": "12345-1",
          "agency": "1234",
          "bankCompeCode": "341",
          "document": {
            "number": "60.664.745/0001-87",
            "type": "CNPJ"
          },
          "type": 1
        }
      }
    }
  ],
  "pagination": {
    "currentPage": 0,
    "pageSize": 1,
    "totalPages": 1,
    "totalItems": 0
  }
}

#

Additional Information#

Default Header#

Some information is required in all requests, they are:

Header	Detalhes
Authorization	Authentication token. For more information, check Token from this document
apikey	Provided by Fiserv after onboarding
x-timestamp	Timestamp of the request. Also used to generate the HMAC signature. For more information, check HMAC Calculation item from this document
x-hmac-signature	Generated HMAC. For more information, check HMAC Calculation item from this document
x-request-id	Random request ID

#

HMAC Calculation#

The HMAC must be calculated using the SHA256 algorithm and the private key that will be provided by Fiserv, containing the following concatenated fields:

APIKEY + TIMESTAMP + REQUEST_BODY + URL_PATH

Below is an example of a postman script that generates the indicated headers according to the specification:

var CryptoJS = require("crypto-js");

function setHMACAuth(request) {
const currentDate = new Date();
var API_KEY = pm.collectionVariables.get('apikey');
var SECRET = pm.collectionVariables.get('secret');
var requestId = generateUUID();
const timestamp = currentDate.getTime().toString();

rawData=API_KEY+timestamp+request.body.toString()+'/'+pm.request.url.path.toString().replaceAll(',','/');;
 
var signedValue = CryptoJS.algo.HMAC.create(CryptoJS.algo.SHA256, SECRET).update(rawData).finalize();
hashedStringRequest = CryptoJS.enc.Base64.stringify(signedValue);

pm.request.headers.add({key:"x-timestamp",value:timestamp});
pm.request.headers.add({key:"x-hmac-signature",value:hashedStringRequest});
pm.request.headers.add({key:"x-request-id",value:requestId});
}

function generateUUID() {
return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
var r = Math.random() * 16 | 0, v = c == 'x' ? r : (r & 0x3 | 0x8);
return v.toString(16);
});
}
 
setHMACAuth(pm.request);

#

Default error object#

All errors handled are returned in a standard format, which is as follows:

{
  "message": "Error Message",
  "details": [
    {
      "errorCode": 0,
      "error": "Error Description"
    }
  ]
}

#

Tests#

PUT /utils/ ordem-pagar#

Simulates the payment of a pix charge in the sandbox environment.

Parâmetros da requisição#

Nome	Localizado em	Descrição	Obrigatório	Tipo
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)
qrCode	body	Pix charge copy and paste code (QRCode)	yes	string

Request example#

{
    "qrCode": "00020101021226830014BR.GOV.BCB.PIX2561api-h.rendimento.com.br/q/v2/28d1eeb09673415ea5ad1c3c2793fbc45204000053039865802BR5914QRCOeAccount6009SAO PAULO61081125553262070503***6304AE83",
}

Home

Environments#

Table of contents#

📍Auth#

📍Webhooks#

🔻Callbacks#

📍Customer#

📍Accounts#

📍Transactions#

📍Cash-out#

📍Reports#

📍Additional Information#

🔻Default error object#

🔻Default Header#

🔻HMAC Calculation#

🔻For testing purposes#

Authentication#

🔒 /token#

POST#

Parameters#

Request example#

Responses#

Response example#

Webhook#

/v1/webhook#

PUT#

Parameters#

Request example#

Responses#

GET#

Parameters#

Responses#

DELETE#

Parameters#

Responses#

CALLBACKS#

Customer#

POST /client#

Transactions#

POST /v1/apm/pix/charges#

PUT /v1/apm/pix/{endToEndId}/reverse/{txid} .#

Cash-out#

POST /v2/apm/pix/cashout#

Client#

/v1/client#

POST#

Parameters#

Request example#

Responses#

Response example#

/v1/client/{clientId}#

GET#

Parameters#

Responses#

Pix Account#

General Information about Account Management#

pixFee#

Example of a commission-based business model with a fixed fee#

Example of a commission-based business model with MDR#

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

POST#

Parameters#

Request example#

Response example#

Responses#

Possible errors:#

/v1/client/{clientId}/apm/pix/account/{pixKey}'#

GET#

Parameters#

Response#

Response example#

Responses#

/v1/client/{clientId}/apm/pix/account/{pixkey} .#

PUT#

Description:#

Parameters#

Request example#

Responses#

/v1/client/{clientId}/apm/pix/account/{pixKey} .#

DELETE#

📍Auth #

📍Webhooks #

🔻Callbacks #

📍Customer #

📍Accounts #

📍Transactions #

📍Cash-out #

📍Reports #

📍Additional Information #

🔻Default error object #

🔻Default Header #

🔻HMAC Calculation #

🔻For testing purposes #