Cashout

POST /v2/apm/pix/cashout

Create pix cashout.

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)
amount	body	Amount to cashout (BRL)	yes	decimal
pixKey	body	Internal pix key of the account	yes	string
receiverPixKey	body	Pix key of the receiver. Optional. See Receiver validation logic	no	string
receiverDocument	body	Document of the receiver. Optional. See Receiver validation logic	no	string
txId	body	External transaction ID provided by the integrator (optional). When not provided, Fiserv generates a random txId	no	string

Receiver validation logic

The receiverPixKey and receiverDocument fields are optional and their handling depends on the integrator's segment:

Merchant: the destination is resolved from the account's own settlement data, so receiverPixKey and receiverDocument may be omitted. When receiverPixKey is provided, it must match the account's settlement pix key; if it does not match, the cashout, after confirmation, will failed with fail reason 8 - Invalid destination data.
Bets: receiverPixKey and receiverDocument must be provided. They define the destination of the cashout and are validated together (the pix key must belong to the informed document). If they are missing or the ownership validation fails, the cashout, after confirmation, will failed with fail reason 8 - Invalid destination data.

Request Example

{
  "pixKey": "tec7e05d-484e-4814-a432-dde637f84402",
  "receiverDocument": "36264164615",
  "receiverPixKey": "[email protected]",
  "amount": 99.99,
  "txId": "2a2cc743-3913-48ea-91fe-13256ab3c3d2"
}

Response Fields

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 /v2/apm/pix/cashout

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

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	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	Cash-out Status
pagination.currentPage	query	Actual page	yes	int
pagination.pageSize	query	Page size	yes	int

Response Fields

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. See Cash-out Status
result.failReason	int (enum)	Cashout Fail Reason (Only when status is Failed). See Cash-out Fail Reason
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)	Cashout Status filter. See Cash-out Status
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-16T09:33:01.573000",
      "confirmedAt": "2025-01-16T09:33:01.573000",
      "pixKey": "883f75da-1f69-48c4-9444-c32b4bcb3553",
      "receiverDocument": "36264164615",
      "receiverPixKey": "[email protected]",
      "amount": 999.99,
      "status": "Confirmed",
      "failReason": null
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 10,
    "totalPages": 1,
    "totalItems": 1
  }
}

POST /v2/apm/pix/cashout/confirm

Confirm a pix cashout request with the confirmation 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)
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.

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.

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

Response Fields

Field	Type	Additional Information
txid	string	Unique identifier of the cashout operation
endToEnd	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)	Cashout Status. See Cash-out Status
failReason	int (enum)	Cashout Fail Reason (Only when status is Failed). See Cash-out Fail Reason

Response Example

{
  "txid": "bec7e05d-484e-4814-a432-dde637f84408",
  "endToEnd": "E144654798498498465123",
  "createdAt": "2025-01-16T09:33:01.573000",
  "confirmedAt": "2025-01-16T09:33:01.573000",
  "pixKey": "883f75da-1f69-48c4-9444-c32b4bcb3553",
  "receiverDocument": "36264164615",
  "receiverPixKey": "[email protected]",
  "amount": 999.99,
  "status": 2,
  "failReason": 1
}

Additional Information

Cash-out Status

Code	Status	Description
0	Pending	Initial state. Cashout request created and undergoing validation. Account balance is locked during this phase.
1	Requested	Awaiting authorization confirmation from customer. Confirmation key auto-generated and sent via webhook. Auto-expires after configured timeout.
2	Authorized	Authorization confirmed and PIX order sent to processor. Detects and marks concurrent requests from the same receiver as failed.
3	Confirmed	PIX transaction successfully completed. Status confirmed via webhook callback from PIX processor. Final state (unless the cashout is later reversed).
4	Failed	Cashout failed due to one of multiple possible reasons: security validation failure, insufficient balance, limit exceeded, expired, concurrent request, or processing error.
5	Expired	Timeout expired while waiting for authorization confirmation. Treated as a failed transaction.
6	Reversed	The cashout was previously confirmed and later reversed. Status confirmed via webhook callback from PIX processor.

Cash-out Fail Reason

Code	Reason	Description
0	Security flag	The transaction was flagged and could not be processed due to security validation policies.
1	Without limit	The cashout amount exceeds the configured transaction limit for the account.
2	Without balance	Insufficient balance in the account to complete the cashout operation.
3	Expired	The cashout request has expired and is no longer valid for processing.
4	Concurrency	Concurrent transaction detected. Another transaction is being processed simultaneously for the same account.
5	Processing failure	A system error occurred during the cashout processing. Please retry the operation.
6	Policy violation	The transaction could not be completed due to policy validation or compliance requirements.
7	Validation error	The transaction could not be processed due to internal validation or compliance check failures.
8	Invalid destination data	The informed receiver data (`receiverPixKey` / `receiverDocument`) is invalid or does not match the account settlement data. See Receiver validation logic.

Updated 30 days ago

Did this page help you?