InstitucionalBlogService DeskStatus Page

Resgate de um valor da conta pocket

stable

Suggest Edits

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

🚧

Importante

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

Requisição

Requisição HTTP

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

curl --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:

ScopeDescrição
pocket.transaction.createConcede acesso para realizar transações internas com uma conta pocket.

Cabeçalhos (Headers)

NomeDescrição
api-versionObrigatório. A versão desta API é a 2.0.
AuthorizationObrigatório. Token de autorização do tipo Bearer.
idempotency-keyObrigató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:

NomeTipoDescrição
pocketNumberpathObrigató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:

NomeTipoDescrição
dataobjectObrigatório. Objeto contendo os dados do resgate.
data.amountobjectObrigatório. Objeto contendo os dados relativos ao valor do resgate.
data.amount.currencystringObrigatório. Sigla da moeda utilizada, de acordo com a ISO 4217. Atualmente, só é possível informar BRL.
data.amount.valuenumberObrigatório. Valor a ser resgatado.
data.descriptionstringTexto 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.

👍

Dica

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

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:

NomeTipoDescrição
dataobjectObjeto que contém os dados do depósito realizado.
data.authenticationCodestringCódigo identificador da transação em formato GUID.
data.amountobjectObjeto que contém dados referentes ao valor da transação.
data.amount.valuenumberValor transacionado.
data.amount.currencystringSigla da moeda utilizada, de acordo com a ISO 4217. Atualmente, só é possível informar BRL.
data.pocketobjectObjeto que contém os dados da conta pocket.
data.pocket.numbernumberNúmero da conta pocket.
data.pocket.statusstringEstado da conta pocket, o qual pode ser: “ACTIVE”, “DORMANT”, “LOCKED” e “CLOSED”.
data.pocket.accountobjectObjeto que contém informações sobre a conta de pagamento à qual a pocket está atrelada.
data.pocket.account.branchstringNúmero da agência.
data.pocket.account.numberstringNúmero da conta.
data.pocket.account.statusstringSituação da conta de pagamento à qual a pocket está atrelada, que pode ser “ACTIVE” ou “CLOSED”.
data.pocket.account.bankobjectObjeto que contém informações sobre o banco ao qual a conta pocket pertence.
data.pocket.account.bank.codestringCódigo do banco.
data.pocket.account.bank.ispbstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
data.pocket.account.bank.namestringNome do banco.
data.pocket.account.holderobjectObjeto que contém os dados do titular da conta de pagamento.
data.pocket.account.holder.documentobjectObjeto que contém os dados do documento do titular da conta de pagamento.
data.pocket.account.holder.document.valuestringNúmero do documento.
data.pocket.account.holder.document.typestringTipo de documento (CPF ou CNPJ).
data.pocket.account.holder.typestringTipo do cadastro do titular da conta de pagamento (“CUSTOMER” ou “BUSINESS”).
data.pocket.account.holder.namestringNome do titular da conta de pagamento.
data.typestringTipo de transação da pocket. Em caso de resgate, o valor desse campo será "REDEEM".
data.statusstringSituação da transação, o qual pode ser “CREATED”, “IN_PROCESS”, “DONE”, “UNDONE” e “ERROR”.
data.createdAtstringData de criação da transação, no formato ISO 8601 - UTC.
data.updatedAtstringData de atualização da transação, no formato ISO 8601 - UTC.
data.descriptionstringTexto que descreve o propósito da transação.
links[]array of objectsLinks de próximos estados válidos da entidade/recurso.
links[].urlstringURLs que podem ser utilizadas em um próximo estado da entidade.
links[].relstringDescrição de como a URL se relaciona com o recurso atual.
links[].methodstringTipo de verbo que deve ser utilizado para acessar a URL.
metadatadictionary<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.

Erros

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

Status CodeCódigoMensagemDescrição
422PAYMENT_ACCOUNT_NOT_FOUNDPayment account not found.Conta de pagamento não encontrada.
422INSUFFICIENT_BALANCEPocket account does not have sufficient balance.Saldo insuficiente na conta de pagamento.
422POCKET_ACCOUNT_INVALID_STATUSPocket 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 eventoDescrição
POCKET_ACCOUNT_REDEEM_WAS_COMPLETEDComunica o resgate de valores da conta pocket.
POCKET_ACCOUNT_REDEEM_ERROR_OCCURREDComunica que ocorreu um erro na transação de resgate.

Updated 12 days ago