Como realizar o saque de uma Subconta via API?

info

Para a utilização desta funcionalidade é necessário possuir a funcionalidade Subconta

Para realizar o saque integral de uma subconta, você utiliza o endpoint /api/v1/subaccount/{ID}/withdraw da API.

Você pode acessar aqui a documentação referente a esse endpoint.

A chave pix registrada na subconta deve ser passada na url da requisição como parâmetro.

Após efetuar a requisição, se tudo ocorreu bem, o status code da requisição será 2xx e no body da resposta, um objeto com os detalhes da transação efetuada para a chave pix registrada na subconta.

Exemplos em código

Shell + cURL

  curl 'https://api.woovi.com/api/v1/subaccount/chave-pix-subconta/withdraw -X POST \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "user-agent: node-fetch" \
      -H "Authorization": "app_id"

JavaScript + Fetch

fetch(
  'https://api.woovi.com/v1/subaccount/chave-pix-subconta/withdraw',
  {
    method: 'POST',
    headers: {
      Authorization: 'AUTHORIZATION',
      'Content-Type': 'application/json',
    },
  },
).then((res) => res.json());

Exemplos de resposta

{
  "transaction": {
    "status": "CREATED",
    "value": 100,
    "correlationID": "TESTING1323",
    "destinationAlias": "[email protected]",
    "comment": "testing-transaction"
  }
}

Tratamento de erros

Quando um saque de subconta falha, o webhook OPENPIX:MOVEMENT_FAILED é disparado com o código e a descrição específica do erro no campo error:

{
  "event": "OPENPIX:MOVEMENT_FAILED",
  "payment": {
    "value": 100,
    "status": "FAILED",
    "destinationAlias": "[email protected]",
    "correlationID": "TESTING1323"
  },
  "error": {
    "code": "PIX_KEY_INFO_NOT_FOUND",
    "description": "A chave pix não está registrada em uma instituição bancária"
  }
}

Os principais códigos de erro para saques de subconta são:

Código do Erro	Descrição
NOT_ENOUGH_BALANCE	A subconta não possui saldo suficiente para realizar o saque
PIX_KEY_INFO_NOT_FOUND	A chave pix não está registrada em nenhuma instituição bancária
INVALID_PIX_KEY	A chave pix informada é inválida
ENTRY_ASSOCIATED_WITH_RESTRICTED_ACCOUNT_OR_USER	A conta associada à chave pix está restrita por fraude pelo Banco Central

info

Para a lista completa de códigos de erro, consulte a documentação de erros de pagamento.

Para erros retornados pelo SPI (Sistema de Pagamentos Instantâneos do Banco Central), consulte os códigos de erro PIX.

cuidado

Quando a chave pix da subconta é inválida ou está associada a uma conta restrita, o campo withdrawBlocked da subconta é marcado como true e saques futuros serão bloqueados. Veja mais detalhes em Por que o saque da subconta foi bloqueado?.