Resgate de um valor da conta pocket

Utilize este endpoint para resgatar o valor depositado na conta pocket e devolvê-lo para a conta de pagamento.

📘
Nota
Recordamos que somente é possível enviar dinheiro da conta pocket para a conta de pagamento à qual ela está atrelada.

Requisição (Request)

Requisição HTTP

POST https://api-mtls.sandbox.bankly.com.br/pockets/{pocketNumber}/transactions/redeems

--request POST \
--url 'https://api-mtls.sandbox.bankly.com.br/pockets/1516482BRL/transactions/redeems' \
--header 'accept: application/json' \
--header 'api-version: 2' \
--header 'authorization: Bearer' \
--header 'content-type: application/json' \
--header 'idempotency-key: f5ff2ba3-76c0-4aa0-8015-a93b62a6c100' \
--data '
{
     "data": {
          "amount": {
               "currency": "BRL",
               "value": 500
          },
          "description": "Valor para livros didáticos"
     },
     "metadata": {}
}
'

Autorização

Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.

Esta requisição requer o scope descrito a seguir:

Scope	Descrição
`pocket.transaction.create`	Concede acesso para realizar transações internas com uma conta pocket.

Cabeçalhos (Headers)

Nome	Descrição
`api-version`	Obrigatório. A versão desta API é a 2.0.
`Authorization`	Obrigatório. Token de autorização do tipo Bearer.
`idempotency-key`	Obrigatório. Informe um GUID v4, sendo um novo a cada requisição.

🚧
Importante
O tempo para a expiração do Idempotency-Key é de 6 minutos.

Parâmetros da rota (Path)

No path desta requisição, envie o seguinte campo:

Nome	Tipo	Descrição
`pocketNumber`	`path`	Obrigatório. Número da conta pocket da qual o valor será resgatado.

Corpo da requisição (Body)

No body, envie os seguintes campos em formato JSON:

Nome	Tipo	Descrição
`data`	`object`	Obrigatório. Objeto que deverá conter informações sobre o resgate.
`data.amount`	`object`	Obrigatório. Objeto que deverá conter informações sobre o valor do resgate.
`data.amount.currency`	`string`	Obrigatório. Código da moeda com base na ISO-4217. Exemplo: “BRL”.
`data.amount.value`	`number`	Obrigatório. Valor a ser resgatado.
`data.description`	`string`	Texto que descreve o propósito da transação.

{
     "data": {
          "amount": {
               "currency": "BRL",
               "value": 500
          },
          "description": "Valor para livros didáticos"
     },
     "metadata": {}
}

📘
Nota
O objeto metadata exibido no exemplo é um dicionário de metadados e permite o envio de dados adicionais na requisição. O envio desse campo é opcional.

Resposta (Response)

O status code 202 indicará sucesso no processo de resgate de valor.

Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:

Nome	Tipo	Descrição
`data`	`object`	Objeto que contém informações sobre o depósito realizado.
`data.authenticationCode`	`string`	Código identificador da transação em formato GUID.
`data.amount`	`object`	Objeto que contém informações sobre o valor da transação.
`data.amount.value`	`number`	Valor transacionado.
`data.amount.currency`	`string`	Código da moeda com base na ISO-4217. Exemplo: “BRL”.
`data.pocket`	`object`	Objeto que contém informações sobre a conta pocket.
`data.pocket.number`	`number`	Número da conta pocket.
`data.pocket.status`	`string`	Status da conta pocket, o qual pode ser “ACTIVE”, “DORMANT”, “LOCKED” e “CLOSED”.
`data.pocket.account`	`object`	Objeto que contém informações sobre a conta de pagamento à qual a pocket está atrelada.
`data.pocket.account.branch`	`string`	Número da agência.
`data.pocket.account.number`	`string`	Número da conta.
`data.pocket.account.status`	`string`	Situação da conta de pagamento à qual a pocket está atrelada, que pode ser “ACTIVE” ou “CLOSED”.
`data.pocket.account.bank`	`object`	Objeto que contém informações sobre o banco ao qual a conta pertence.
`data.pocket.account.bank.code`	`string`	Código do banco.
`data.pocket.account.bank.ispb`	`string`	ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
`data.pocket.account.bank.name`	`string`	Nome do banco.
`data.pocket.account.holder`	`object`	Objeto que contém informações sobre o titular da conta de pagamento.
`data.pocket.account.holder.document`	`object`	Objeto que contém informações sobre o documento do titular da conta de pagamento.
`data.pocket.account.holder.document.value`	`string`	Número do documento.
`data.pocket.account.holder.document.type`	`string`	Tipo de documento (CPF ou CNPJ).
`data.pocket.account.holder.type`	`string`	Tipo do cadastro do titular da conta de pagamento, que pode ser “CUSTOMER” ou “BUSINESS”.
`data.pocket.account.holder.name`	`string`	Nome do titular da conta de pagamento.
`data.type`	`string`	Tipo de transação da pocket. Em caso de resgate, o valor desse campo será "REDEEM".
`data.status`	`string`	Situação da transação, a qual pode ser “CREATED”, “IN_PROCESS”, “DONE”, “UNDONE” e “ERROR”.
`data.createdAt`	`string`	Data de criação da transação, no formato ISO 8601 - UTC.
`data.updatedAt`	`string`	Data de atualização da transação, no formato ISO 8601 - UTC.
`data.description`	`string`	Texto que descreve o propósito da transação.
`links[]`	`array of objects`	Links de próximos estados válidos da entidade/recurso.
`links[].url`	`string`	URLs que podem ser utilizadas em um próximo estado da entidade.
`links[].rel`	`string`	Descrição de como a URL se relaciona com o recurso atual.
`links[].method`	`string`	Tipo de verbo que deve ser utilizado para acessar a URL.
`metadata`	`dictionary<string, object>`	Metadados da requisição.

{
    "data": {
        "authenticationCode": "2837eb11-e203-4c36-a80d-f8b131b2d8fd",
        "amount": {
            "value": 1.0,
            "currency": "BRL"
        },
        "pocket": {
            "number": "1516482BRL",
            "status": "ACTIVE",
            "account": {
                "number": "15164",
                "branch": "0001",
                "status": "ACTIVE",
                "bank": {
                    "ispb": "13140088",
                    "code": "332",
                    "name": "Acesso Soluções De Pagamento S.A."
                },
                "holder": {
                    "document": {
                        "value": "47742663023",
                        "type": "CPF"
                    },
                    "type": "CUSTOMER",
                    "name": "Nísia Floresta"
                }
            }
        },
        "type": "REDEEM",
        "status": "CREATED",
        "createdAt": "2022-12-01T03:09:09.4269668Z",
        "updatedAt": "0001-01-01T00:00:00Z",
        "description": "Valor destinado a livros"
    },
    "links": [
        {
            "url": "/pockets/24937871BRL/transactions/2837eb11-e203-4c36-a80d-f8b131b2d8fd",
            "rel": "get_pocket_transaction",
            "method": "GET"
        }
    ],
    "metadata": {}
}

🚧
Importante
Se a conta de pagamento for bloqueada ou cancelada, não será possível realizar movimentações na pocket.

👍
Dica
Para simular uma requisição nesse endpoint, acesse o API Reference.

Erros

Este endpoint pode retornar alguns erros específicos, conforme a tabela a seguir:

Status Code	Código	Mensagem	Descrição
422	PAYMENT_ACCOUNT_NOT_FOUND	Payment account not found.	Conta de pagamento não encontrada.
422	INSUFFICIENT_BALANCE	Pocket account does not have sufficient balance.	Saldo insuficiente na conta de pagamento.
422	POCKET_ACCOUNT_INVALID_STATUS	Pocket status {status} is invalid to handle this operation.	O status da conta pocket não permite a transação. Somente é possível transacionar se a conta apresentar status “ACTIVE” e “DORMANT”.

Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints. Portanto, recomendamos a consulta da documentação de erros, onde é possível encontrar as mensagens comuns em inglês que acompanham os erros 400 (se houver).

Eventos

Caso o parceiro deseje receber mensagens referentes aos eventos relacionados a esse endpoint, é preciso configurar o webhook. Os eventos são:

Nome do evento	Descrição
`POCKET_ACCOUNT_REDEEM_WAS_COMPLETED`	Comunica o resgate de valores da conta pocket.
`POCKET_ACCOUNT_REDEEM_ERROR_OCCURRED`	Comunica que ocorreu um erro na transação de resgate.

Resgate de um valor da conta pocket

📘
Nota

Requisição (Request)

Requisição HTTP

Autorização

Cabeçalhos (Headers)

🚧
Importante

Parâmetros da rota (Path)

Corpo da requisição (Body)

📘
Nota

Resposta (Response)

🚧
Importante

👍
Dica

Erros

Eventos

📘Nota

Requisição (Request)

Requisição HTTP

Autorização

Cabeçalhos (Headers)

🚧Importante

Parâmetros da rota (Path)

Corpo da requisição (Body)

📘Nota

Resposta (Response)

🚧Importante

👍Dica

Erros

Eventos

📘
Nota

🚧
Importante

📘
Nota

🚧
Importante

👍
Dica