Skip to main content

​
Overview

Create outbound PIX transfers from BRL accounts via POST /api/v1/br/transactions/outbound. Requires sufficient net balance. The transaction starts in processing when accepted, or cancelled if the payout cannot be created.

​
Required fields

  • accountId, amount
  • name — recipient display name
  • keyType — document, email, evp, phone, or cnpj
  • keyPix — destination PIX key matching keyType (required; cannot be omitted)

​
Optional fields

  • document — recipient CPF or CNPJ (11 or 14 digits). Forwarded to the PIX provider when provided. You may send formatted values (for example 123.456.789-01); HG.Cash normalizes to digits before calling the provider.

​
Inbound vs outbound

PIX cash-in requires payer document. Outbound payouts require keyType + keyPix because the provider withdraw-by-key API uses pixKey (required) and document (optional). The optional outbound document identifies the key holder when you send it — it does not replace keyPix. When keyType is document or cnpj, send keyPix as the destination key. HG.Cash strips punctuation before forwarding CPF/CNPJ keys to the provider.

​
Status updates

  • Poll: GET /api/v1/br/transactions/{id}/status
  • Optional webhookUrl on the request (see Receiving webhooks)
Status webhooks use the account-movement body (topic TRANSACTION, eventType status_change). A stored PIX end-to-end id is sent as endToEndId and omitted when empty. See PIX end-to-end id.

​
Example requests

Email key:
CPF key (keyType: document). You may send masked or unmasked CPF in keyPix; HG.Cash forwards digits only:

​
Payout lifecycle

An accepted payout starts in processing. It moves to done when the PIX transfer settles, or to cancelled when the provider rejects or fails it. Provider outcomes such as Zetta/Bankizi FAILED and REJECTED are normalized to cancelled. HG.Cash does not expose a separate failed status on Brazil payouts. Use polling (GET /api/v1/br/transactions/{id}/status) or your webhook handler to react to status changes.

​
Account status

The source account must be Operativa. Requests against Bloqueada or Cerrada accounts return 403 with code: ACCOUNT_NOT_OPERATIVE.