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
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
Content-Type: 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
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 /v1/webhook
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)
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
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 Callback
POST /client
After the customer registration and the KYC(1) process is completed, the URL registered for the webhook receives the following notification:
Response Fields
Field
Type
Description
protocolId
string
Internal protocol identifier for the KYC process
externalProtocolId
string
External protocol identifier
omniClientId
string
Unique identifier for the client in the Omni system
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 Callback
POST /v1/apm/pix/charges
After the transaction charge is completed, the URL registered in the webhook receives the following notification:
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."
Customer
POST /v1/client
Add a client.
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)
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.
After the client registration a KYC validation will happen asynchronously, and the result will be notified to the configured webhook.
GET /v1/client/{clientId}
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
Response Fields
Name
Description
Type
kycStatus
Customer's KYC status
string
Response Example
{
"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
Accounts
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
POST /v1/client/{clientId}/apm/pix/account
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
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
Settlement.pixKey
body
string
yes
PixKey of settlement account. Only the pix key or account information should be provided, never both.
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.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.
holdSettlement
body
bool
no
Identifies if charges are created with settlement hold (default false)
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.
GET /v1/client/{clientId}/apm/pix/account/{pixKey}
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
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
Every night, during the early morning hours, automatic settlement is performed for accounts that have hasAutomaticSettlement = true. For accounts where the value is false, the withdrawal of funds must be carried out manually through the Cash-out endpoints
PUT /v1/client/{clientId}/apm/pix/account/{pixKey}
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.
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”
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)
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.
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
yes
bool
expiration
body
QRcode expiration time in seconds
yes
int
payerDocument
body
Only for Bets. And when provided, the payment must be made using an account owned by the same document holder; otherwise, the payment will not be accepted
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 /v2/apm/pix/cashout
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)
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.
GET /v2/apm/pix/cashout/{txid}
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
Reference table for transaction types used in report endpoints:
Value
Name
Description
0
Payment
Charge
1
Reverse
Reversal
2
Block
MED block
3
Unlock
MED unlock
4
SpecialReturn
Special Return Movement
5
Refund
Partial Refund
6
BacenJudTransfer
Bacen Jud Transfer
7
BacenJudBlock
Bacen Jud Block
8
BacenJudUnlock
Bacen Jud Unlock
9
ScheduledCashOut
Scheduled Cash Out
10
ImmediateCashOut
Immediate Cash Out
11
PixFee
Pix Fee
12
PixFeeReverse
Fee Reversal
13
SpecialReturnReverse
Special Return Reversal
14
ManagementAdjustment
Management Adjustments
Get Cash-out Status
Code
Status
0
Pending
1
Requested
2
Authorized
3
Confirmed
4
Failed
5
Expired
Get Liquidations Status
Code
Status
0
Pending
1
Confirmed
2
Fail
Default Header
Some information is required in all requests, they are:
Header
Details
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:
