Stream de Pagamentos

O conjunto de endpoints a seguir é responsável pela gestão de Stream de Pagamentos.

Long Polling de Pix disponibilizados para o PSP

Endpoint para retornar uma lista de mensagens Pix recebidas para o participante, tanto crédito quanto débito (Cash In e Cash Out).

Long Polling:

Este endpoint utiliza a técnica de long polling. Diferente do polling tradicional, a API não responde imediatamente caso não haja nenhuma mensagem disponível.

Comportamento:

A API aguarda por alguns segundos até que uma mensagem esteja disponível
Se nenhuma mensagem estiver disponível após o timeout, retorna código 204 (No Content)
Após receber a resposta, o PSP deve realizar a requisição novamente para buscar novas informações de pagamento
Contém apenas informações relacionadas a pagamentos (Cash In e Cash Out)

Importante!

Mensagens que são do tipo crédito e que estão com situação(status) "WAITING" carecem de resposta deste pagamento através da rota /v1/pix/confirm, para confirmar (aceitar ou rejeitar) os Pix em questão.

GET /payments/stream

Requer autorização para o escopo: pix.ind.read

Requisição

A requisição enviada para esse endpoint não precisa de um body, apenas os cabeçalhos de autorização OAuth, parâmetros e o certificado da conta.

Respostas

As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.

// Pix com sucesso
{
  "correlationId": "47a704c5-6b39-4619-98d2-cea4ab75f7ca",
  "responseTime": 963,
  "pix": [
    {
      "endToEndId": "E2E123456789545430",
      "messageId": "M111111119079b30094602833bd8d208",
      "txid": "TXID123456789",
      "endUserAccount": "0001234",
      "key": "[email protected]",
      "value": "110.11",
      "type": "credit",
      "status": "ACCC",
      "effectiveDatetime": "2025-04-07T12:23:18.000Z",
      "extras": {
        "favored": {
          "name": "Nome completo da Silva",
          "document": 12345678901,
          "account": {
            "participant": 12345678,
            "branch": 1,
            "accountNumber": 1234567890,
            "type": "CACC"
          }
        }
      }
    }
  ]
}

OU

// Pix com erro
{
  "correlationId": "47a704c5-6b39-4619-98d2-cea4ab75f7ca",
  "responseTime": 963,
  "pix": [
    {
      "endToEndId": "E2E123456789545431",
      "messageId": "M111111118099b90031236547ec9a809",
      "txid": "TXID123456790",
      "endUserAccount": "0001234",
      "key": "[email protected]",
      "value": "200.00",
      "type": "credit",
      "status": "RJCT",
      "extras": {
        "error": {
          "code": "AB03",
          "reason": "Informações complementares sobre o motivo do status"
        }
      }
    }
  ]
}

OU

// Sem pagamentos disponíveis
{
  "correlationId": "47a704c5-6b39-4619-98d2-cea4ab75f7ca",
  "responseTime": 150,
  "pix": []
}

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Could not parse request body",
    "status": 400,
    "title": "Bad Request",
    "type": "https://dict.pi.rsfn.net.br/api/v2/error/BadRequest"
  }
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Expired access token",
    "status": 401,
    "title": "invalid_token"
  },
  "responseTime": 0
}

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Participant is not allowed to access this resource",
    "status": 403,
    "title": "Forbidden"
  }
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Entry associated with given key does not exist",
    "status": 404,
    "title": "Not found",
    "type": "https://dict.pi.rsfn.net.br/api/v2/error/NotFound"
  },
  "responseTime": 0
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "status": 429,
    "title": "Rate limited",
    "type": "https://dict.pi.rsfn.net.br/api/v2/error/RateLimited"
  },
  "responseTime": 0
}

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Our service is currently experiencing an issue. We apologize for the inconvenience and are working to resolve it as soon as possible.",
    "status": 500,
    "title": "Internal Server Error"
  }
}

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Service is under scheduled maintenance",
    "status": 503,
    "title": "Service Unavailable",
    "type": "https://dict.pi.rsfn.net.br/api/v2/error/ServiceUnavailable"
  }
}

Consulta mensagens de um Stream por correlationId

Endpoint para retornar as mensagens Pix vinculadas ao correlationId informado.

Este endpoint consulta mensagens específicas de pagamentos (Cash In e Cash Out) associadas a um correlationId gerado previamente durante uma requisição de long polling.

GET /payments/stream/:correlationId

Requer autorização para o escopo: pix.ind.read

Requisição

Este endpoint utiliza path params em seu funcionamento, onde o correlationId deve ser informado na URL.

Respostas

As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.

// Pix com sucesso
{
  "correlationId": "47a704c5-6b39-4619-98d2-cea4ab75f7ca",
  "responseTime": 963,
  "pix": [
    {
      "endToEndId": "E2E123456789545430",
      "messageId": "M111111119079b30094602833bd8d208",
      "txid": "TXID123456789",
      "endUserAccount": "0001234",
      "key": "[email protected]",
      "value": "110.11",
      "type": "credit",
      "status": "ACCC",
      "effectiveDatetime": "2025-04-07T12:23:18.000Z",
      "extras": {
        "favored": {
          "name": "Nome completo da Silva",
          "document": 12345678901,
          "account": {
            "participant": 12345678,
            "branch": 1,
            "accountNumber": 1234567890,
            "type": "CACC"
          }
        }
      }
    }
  ]
}

OU

// Pix com erro
{
  "correlationId": "47a704c5-6b39-4619-98d2-cea4ab75f7ca",
  "responseTime": 963,
  "pix": [
    {
      "endToEndId": "E2E123456789545431",
      "messageId": "M111111118099b90031236547ec9a809",
      "txid": "TXID123456790",
      "endUserAccount": "0001234",
      "key": "[email protected]",
      "value": "200.00",
      "type": "credit",
      "status": "RJCT",
      "extras": {
        "error": {
          "code": "AB03",
          "reason": "Informações complementares sobre o motivo do status"
        }
      }
    }
  ]
}

OU

// Sem pagamentos disponíveis
{
  "correlationId": "47a704c5-6b39-4619-98d2-cea4ab75f7ca",
  "responseTime": 150,
  "pix": []
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Could not parse request body",
    "status": 400,
    "title": "Bad Request",
    "type": "https://dict.pi.rsfn.net.br/api/v2/error/BadRequest"
  },
  "responseTime": 0
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Expired access token",
    "status": 401,
    "title": "invalid_token"
  },
  "responseTime": 0
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Participant is not allowed to access this resource",
    "status": 403,
    "title": "Forbidden"
  },
  "responseTime": 0
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Entry associated with given key does not exist",
    "status": 404,
    "title": "Not found",
    "type": "https://dict.pi.rsfn.net.br/api/v2/error/NotFound"
  },
  "responseTime": 0
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "status": 429,
    "title": "Rate limited",
    "type": "https://dict.pi.rsfn.net.br/api/v2/error/RateLimited"
  },
  "responseTime": 0
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Our service is currently experiencing an issue. We apologize for the inconvenience and are working to resolve it as soon as possible.",
    "status": 500,
    "title": "Internal Server Error"
  },
  "responseTime": 0
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "Service is under scheduled maintenance",
    "status": 503,
    "title": "Service Unavailable",
    "type": "https://dict.pi.rsfn.net.br/api/v2/error/ServiceUnavailable"
  },
  "responseTime": 0
}

Stream de Pagamentos

Long Polling de Pix disponibilizados para o PSP​

Consulta mensagens de um Stream por correlationId​

Long Polling de Pix disponibilizados para o PSP

Consulta mensagens de um Stream por correlationId