Documentation
IntroCreateBalanceHooksErrors

Get Withdrawal by Lookup

Looks up a withdrawal by any of several identifiers (ID, EndToEnd, TID, ProviderPaymentId, IdempotencyKey).

Version 1.0 - This endpoint finds a withdrawal from a single parameter (q) that can hold any of the withdrawal's identifiers. With API Key authentication, the scope is automatically limited to the credential's company.

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

Authentication

This endpoint requires authentication. You can use an API Key or a JWT.

API Key

X-Client-Id: <client_id> | X-API-Key: <secret>

Scope is always limited to the credential's company. Sending a different companyId returns 403.

JWT

Authorization: Bearer <jwt>

Admin/Manager: can search everything and filter by companyId. Regular user: own company only.

WARNING: Never log the X-API-Key value. Use environment variables and rotate the secret when needed.

Query Parameters

q
Obrigatoriostring

Search key: Id (numeric), ProviderEndToEndId (EndToEnd), ProviderTid (TID), ProviderPaymentId, IdempotencyKey

companyId
integer

Optional filter (only useful for Admin/Manager with JWT). With API Key authentication, omit it or send the credential's own company.

Fields checked by the search:

  • Id (only when q is numeric)
  • ProviderEndToEndId (EndToEnd)
  • ProviderTid (TID)
  • ProviderPaymentId
  • IdempotencyKey

Success Response - Single Match (200 OK)

When exactly 1 withdrawal is found, the endpoint returns ok=true, the withdraw object and the keys block.

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

INFO: providerPayload is returned as a JSON string (for auditing/debugging). To read its fields, parse the JSON on your side.

Ambiguous Response - Multiple Matches (200 OK)

When more than 1 withdrawal is found:

Response (Ambiguous)
{
  "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}."
}

Error Codes

400q missing or invalid
{ "message": "Query q e obrigatoria." }
403Invalid credentials or no permission
{ "message": "Credenciais invalidas de API KEY." }
404No withdrawal found in scope
{ "message": "Saque nao encontrado para o parametro informado." }
500Unexpected internal error
{ "message": "Erro interno.", "detail": "..." }

cURL Examples

Search by ID:

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

Search by EndToEnd:

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

Search by TID:

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

JavaScript / Node.js Example

JavaScript
const q = '1390'; // ID, EndToEnd, TID, ProviderPaymentId or IdempotencyKey
const response = await fetch(
  `https://baanko.app/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('Withdrawal found:', data.withdraw);
  console.log('Identifiers:', data.keys);
} else if (data.ambiguous) {
  console.log(`${data.count} withdrawals found. Use a specific ID.`);
  console.log(data.items);
}

Performance Recommendations

For frequent lookups, we recommend indexes (PostgreSQL) on these fields:

  • (CompanyId, ProviderEndToEndId)
  • (CompanyId, ProviderTid)
  • (CompanyId, ProviderPaymentId)
  • (CompanyId, IdempotencyKey)

With API Key authentication, the CompanyId filter narrows the data set and significantly improves latency.