GET

Consultar Saque por Lookup

Consulta um saque por múltiplos identificadores (ID, EndToEnd, TID, ProviderPaymentId, IdempotencyKey). Em modo API Key, o escopo é automaticamente limitado à empresa da credencial.

Endpoint

GET/api/Withdraw/lookup?q={identificador}

Busca um saque por qualquer identificador

Base URL: https://rayopay.com.br

Autenticação

O endpoint exige autenticação. Você pode usar API Key ou JWT.

Método	Header	Observação
API Key	X-Client-Id + X-API-Key	Escopo sempre limitado à empresa da credencial
JWT	Authorization: Bearer <jwt>	Admin/Manager: pode consultar geral. Usuário comum: somente própria empresa

Boas práticas

Não registre (log) o valor de X-API-Key. Use variáveis de ambiente e rotação de segredo quando necessário.

Query Parameters

Parametro	Tipo	Descricao
`q`obrigatorio	`string`	Chave de busca. Pode ser: Id numérico, ProviderEndToEndId (EndToEnd), ProviderTid (TID), ProviderPaymentId, IdempotencyKey.
`companyId`	`integer`	Filtro opcional (apenas útil para Admin/Manager via JWT). Em modo API Key, deve ser omitido.

Campos avaliados na busca:

• Id (apenas quando q for numérico)
• ProviderEndToEndId (EndToEnd)
• ProviderTid (TID)
• ProviderPaymentId
• IdempotencyKey

Resposta de Sucesso - Match Único (200 OK)

Quando 1 saque é encontrado:

response-unico.json

json

{
  "ok": true,
  "withdraw": {
    "id": 1390,
    "companyId": 1,
    "value": 1112.00,
    "currency": "BRL",
    "pixKey": "12505368473",
    "pixKeyType": "CPF",
    "creditorDocument": "44444444444444",
    "enTransaction": "Successful",
    "provider": "Provider",
    "providerPaymentId": "175b4f3a-2d71-401c-9dd2-1f33cb32fc7a",
    "providerTid": "wld-00001390",
    "providerEndToEndId": "E48756121202602031458MHoTfthbxEq",
    "providerStatus": "successful",
    "providerPayload": "{... string JSON do provedor ...}"
  },
  "keys": {
    "id": 1390,
    "companyId": 1,
    "providerTid": "wld-00001390",
    "providerPaymentId": "175b4f3a-2d71-401c-9dd2-1f33cb32fc7a",
    "end2end": "E48756121202602031458MHoTfthbxEq",
    "idempotencyKey": "2ce66db9-7d2f-4761-a5d4-46799ab8709f"
  }
}

providerPayload

providerPayload é retornado como string JSON (auditoria/debug). Se precisar ler campos internos, faça parse do JSON no cliente.

Resposta Ambígua - Múltiplos Matches (200 OK)

Quando mais de 1 saque é encontrado:

response-ambiguo.json

json

{
  "ok": true,
  "ambiguous": true,
  "count": 2,
  "items": [
    {
      "id": 1001,
      "companyId": 1,
      "value": 10.00,
      "status": "Successful",
      "providerTid": "wld-00001001"
    },
    {
      "id": 1002,
      "companyId": 1,
      "value": 10.00,
      "status": "Successful",
      "providerTid": "wld-00001002"
    }
  ],
  "hint": "Use o Id retornado e consulte /api/Withdraw/{id}."
}

Códigos de Erro

Código	Descrição	Exemplo
`400`	q ausente ou inválido	Query q é obrigatória
`403`	Credenciais inválidas ou sem permissão	Credenciais inválidas de API KEY
`404`	Nenhum saque encontrado	Saque não encontrado para o parâmetro informado
`500`	Erro interno inesperado	Erro interno

Exemplos

Buscar por ID

cURL - Buscar por ID

bash

curl -sS "https://rayopay.com.br/api/Withdraw/lookup?q=1390" \
  -H "X-Client-Id: <client_id>" \
  -H "X-API-Key: <secret>"

Buscar por EndToEnd

cURL - Buscar por EndToEnd

bash

curl -sS "https://rayopay.com.br/api/Withdraw/lookup?q=E123...XYZ" \
  -H "X-Client-Id: <client_id>" \
  -H "X-API-Key: <secret>"

Buscar por TID

cURL - Buscar por TID

bash

curl -sS "https://rayopay.com.br/api/Withdraw/lookup?q=wld-00001390" \
  -H "X-Client-Id: <client_id>" \
  -H "X-API-Key: <secret>"

JavaScript / Node.js

javascript

const q = '1390'; // ID, EndToEnd, TID, ProviderPaymentId ou IdempotencyKey
 
const response = await fetch(
  `https://rayopay.com.br/api/Withdraw/lookup?q=${encodeURIComponent(q)}`,
  {
    method: 'GET',
    headers: {
      'X-Client-Id': '<client_id>',
      'X-API-Key': '<secret>'
    }
  }
);
 
const data = await response.json();
 
if (data.ok && !data.ambiguous) {
  console.log('Saque encontrado:', data.withdraw);
  console.log('Identificadores:', data.keys);
} else if (data.ambiguous) {
  console.log(`${data.count} saques encontrados. Use ID específico.`);
  console.log(data.items);
}