Pular para o conteúdo
Vintém

Solicitar devolução

PUT
/pix/{e2eid}/devolucao/{id}
curl --request PUT \
  --url http://localhost:8080/pix/example/devolucao/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "valor": "10.50", "natureza": "ORIGINAL", "descricao": "example" }'

Devolve o Pix total ou parcialmente. O par e2eid + id é idempotente: repetir com o mesmo valor devolve a devolução existente, com outro valor responde 409. Saldo, prazo de 90 dias e natureza são conferidos antes de chamar o banco (RN-21).

Authorizations

Seção intitulada “Authorizations”

Parameters

Seção intitulada “Parameters”

Path Parameters

Seção intitulada “Path Parameters”
e2eid
required
string
/^[a-zA-Z0-9]{32}$/
id
required
string
/^[a-zA-Z0-9]{1,35}$/

Escolhido pelo cliente; identifica a devolução junto com o e2eid.

Request Bodyrequired

Seção intitulada “Request Bodyrequired”
Media typeapplication/json
object
valor
required
string
/^\d{1,10}\.\d{2}$/

Example 

10.50
natureza

RETIRADA (Pix Saque ou Troco) é recusada; o Vintém não recebe esse tipo de Pix.

string
default: ORIGINAL
Allowed values: ORIGINAL RETIRADA
descricao
string
<= 140 characters

Responses

Seção intitulada “Responses”

201

Seção intitulada “201”

Devolução solicitada.

Media typeapplication/json
object
id
required
string
rtrId

Identificador da devolução no SPI, gerado pelo banco.

string
valor
required
string
/^\d{1,10}\.\d{2}$/
natureza
required
string
Allowed values: ORIGINAL RETIRADA
descricao
string
horario
required
object
solicitacao
required
string format: date-time
liquidacao
string format: date-time
status
required
string
Allowed values: EM_PROCESSAMENTO DEVOLVIDO NAO_REALIZADO
motivo

Por que a devolução não foi realizada.

string

Example 

{
  "valor": "10.50",
  "natureza": "ORIGINAL",
  "status": "EM_PROCESSAMENTO"
}

400

Seção intitulada “400”

Requisição fora do formato ou violando uma regra de negócio.

Media typeapplication/problem+json

Erro no formato da spec do BCB (RFC 7807).

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
correlationId
string
violacoes
Array<object>
object
razao
string
propriedade
string
valor
string

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "correlationId": "example",
  "violacoes": [
    {
      "razao": "example",
      "propriedade": "example",
      "valor": "example"
    }
  ]
}

401

Seção intitulada “401”

API key ausente ou inválida.

Media typeapplication/problem+json

Erro no formato da spec do BCB (RFC 7807).

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
correlationId
string
violacoes
Array<object>
object
razao
string
propriedade
string
valor
string

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "correlationId": "example",
  "violacoes": [
    {
      "razao": "example",
      "propriedade": "example",
      "valor": "example"
    }
  ]
}

403

Seção intitulada “403”

A API key não tem o escopo necessário.

Media typeapplication/problem+json

Erro no formato da spec do BCB (RFC 7807).

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
correlationId
string
violacoes
Array<object>
object
razao
string
propriedade
string
valor
string

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "correlationId": "example",
  "violacoes": [
    {
      "razao": "example",
      "propriedade": "example",
      "valor": "example"
    }
  ]
}

404

Seção intitulada “404”

Recurso não encontrado.

Media typeapplication/problem+json

Erro no formato da spec do BCB (RFC 7807).

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
correlationId
string
violacoes
Array<object>
object
razao
string
propriedade
string
valor
string

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "correlationId": "example",
  "violacoes": [
    {
      "razao": "example",
      "propriedade": "example",
      "valor": "example"
    }
  ]
}

409

Seção intitulada “409”

Txid já existe, revisão desatualizada, ou Idempotency-Key reutilizada com outro payload.

Media typeapplication/problem+json

Erro no formato da spec do BCB (RFC 7807).

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
correlationId
string
violacoes
Array<object>
object
razao
string
propriedade
string
valor
string

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "correlationId": "example",
  "violacoes": [
    {
      "razao": "example",
      "propriedade": "example",
      "valor": "example"
    }
  ]
}

501

Seção intitulada “501”

O PSP da conta não oferece essa capacidade (RN-50).

Media typeapplication/problem+json

Erro no formato da spec do BCB (RFC 7807).

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
correlationId
string
violacoes
Array<object>
object
razao
string
propriedade
string
valor
string

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "correlationId": "example",
  "violacoes": [
    {
      "razao": "example",
      "propriedade": "example",
      "valor": "example"
    }
  ]
}

default

Seção intitulada “default”

Qualquer outro erro, sempre como Problema. Os mais comuns: 502 quando o banco recusa ou falha (PSPIndisponivel) e 500 para erro interno.

Media typeapplication/problem+json

Erro no formato da spec do BCB (RFC 7807).

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
correlationId
string
violacoes
Array<object>
object
razao
string
propriedade
string
valor
string

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "correlationId": "example",
  "violacoes": [
    {
      "razao": "example",
      "propriedade": "example",
      "valor": "example"
    }
  ]
}