Respawn PayDocs

Withdrawal Lookup

Looks up a withdrawal by multiple identifiers (ID, EndToEnd, TID, ProviderPaymentId, IdempotencyKey).

Version 1.0 - This endpoint lets you find a withdrawal using a single parameter (q) that can hold any withdrawal identifier. In API Key mode, the scope is automatically limited to the credential's company.

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

Authentication

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

API Key

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

Scope is always limited to the credential's company. If you send a different companyId: 403.

JWT

Authorization: Bearer <jwt>

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

Warning: Do not log the value of X-API-Key. Use environment variables and secret rotation when needed.

Query Parameters

q
Requiredstring

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

companyId
string

Company ID (UUID). Optional filter (only useful for Admin/Manager via JWT). In API Key mode, it must be omitted or equal to the credential's company.

Fields evaluated in the search:

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

The search compares the exact value (it does not look for fragments) and returns at most 5 withdrawals. The IdempotencyKey is the value you sent in the Idempotency-Key header when requesting the withdrawal.

Success Response - Single Match (200 OK)

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

Response
{
  "ok": true,
  "withdraw": {
    "id": 1390,
    "idempotencyKey": "2ce66db9-7d2f-4761-a5d4-46799ab8709f",
    "value": 1112.00,
    "pixKey": "12505368473",
    "pixKeyType": "CPF",
    "creditorDocument": "44444444444444",
    "priority": "normal",
    "description": "Test withdrawal",
    "method": "pix",
    "paymentFlow": "INSTANT",
    "expiration": null,
    "currency": "BRL",
    "withdrawAcquirer": null,
    "amount": 111200,
    "ispbDeny": null,
    "enPaymentSystem": "Pix",
    "enTransaction": "Successful",
    "updateDate": "2026-02-03T14:58:20Z",
    "createdAt": "2026-02-03T14:58:00Z",
    "metadata": null,
    "provider": "OnlyUp",
    "providerPaymentId": "175b4f3a-2d71-401c-9dd2-1f33cb32fc7a",
    "providerTid": "wld-00001390",
    "providerEndToEndId": "E48756121202602031458MHoTfthbxEq",
    "providerStatus": "successful",
    "providerPayload": "{... JSON string from the provider ...}",
    "providerPayerName": null,
    "providerPayerDocument": null,
    "providerPayerIspb": null,
    "providerPayerAgency": null,
    "providerPayerAccount": null,
    "providerReceiverName": "NAME OF THE BENEFICIARY",
    "providerReceiverDocument": "12505368473",
    "providerReceiverIspb": null,
    "providerReceiverAgency": null,
    "providerReceiverAccount": null,
    "providerAmount": 1112.00,
    "providerConfirmedAt": "2026-02-03T14:58:19Z",
    "providerDebitedAt": "2026-02-03T14:58:19Z",
    "providerErrorCode": null,
    "providerErrorDescription": null,
    "companyName": "Your Company",
    "companyDocument": "44444444444444",
    "companyEmail": null
  },
  "keys": {
    "id": 1390,
    "value": 1112.00,
    "currency": "BRL",
    "pixKey": "12505368473",
    "pixKeyType": "CPF",
    "status": "Successful",
    "createdAt": "2026-02-03T14:58:00Z",
    "updateDate": "2026-02-03T14:58:20Z",
    "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 (audit/debug). To read inner fields, parse the JSON on the client.

Notes on the withdraw object:

  • method is the withdrawal method (pix, bank_transfer) and paymentFlow is the provider flow (INSTANT or APPROVAL_REQUIRED). See Request Withdrawal.
  • priority is low, normal, high, urgent or null.
  • enPaymentSystem and enTransaction come as names (for example Pix and Successful), not numbers.
  • Dates are UTC (ISO 8601 ending in Z).
  • The company ID is never returned. companyEmail comes as null in this endpoint.
  • Rare case: if the withdrawal cannot be loaded in full right after the search, the response is { "ok": true, "item": { ...keys... } }, with only the fields of the keys block.

Ambiguous Response - Multiple Matches (200 OK)

When more than 1 withdrawal is found (up to 5, newest first). To get the full object, call the lookup again with the numeric id of the one you want:

Response (Ambiguous)
{
  "ok": true,
  "ambiguous": true,
  "count": 2,
  "items": [
    {
      "id": 1001,
      "value": 10.00,
      "currency": "BRL",
      "pixKey": "12505368473",
      "pixKeyType": "CPF",
      "status": "Successful",
      "createdAt": "2026-02-03T14:58:00Z",
      "updateDate": "2026-02-03T14:58:20Z",
      "providerTid": "wld-00001001",
      "providerPaymentId": "175b4f3a-2d71-401c-9dd2-1f33cb32fc7a",
      "end2end": "E48756121202602031458MHoTfthbxEq",
      "idempotencyKey": "2ce66db9-7d2f-4761-a5d4-46799ab8709f"
    },
    {
      "id": 1002,
      "value": 10.00,
      "currency": "BRL",
      "pixKey": "12505368473",
      "pixKeyType": "CPF",
      "status": "Successful",
      "createdAt": "2026-02-03T15:10:00Z",
      "updateDate": "2026-02-03T15:10:20Z",
      "providerTid": "wld-00001002",
      "providerPaymentId": "275b4f3a-2d71-401c-9dd2-1f33cb32fc7b",
      "end2end": "E48756121202602031510MHoTfthbxEq",
      "idempotencyKey": "3ce66db9-7d2f-4761-a5d4-46799ab8709f"
    }
  ],
  "hint": "Mais de um saque bateu no 'q'. Use o Id retornado e consulte /api/Withdraw/{id}."
}

Error Codes

400q missing
{ "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "q": ["The q field is required."] }, "traceId": "..." }
400q sent empty or with spaces only
{ "message": "Query 'q' é obrigatória." }
403Invalid API key credentials
{ "message": "Credenciais inválidas de API KEY." }
403Only one of X-Client-Id / X-API-Key sent
{ "message": "Headers X-Client-Id e X-API-Key devem ser enviados juntos." }
403companyId different from the API key company
{ "message": "companyId não corresponde às credenciais da API KEY." }
404No withdrawal found in scope
{ "message": "Saque não encontrado para o parâmetro informado." }
500Unexpected internal error
Generic server error (no fixed body)

cURL Examples

Search by ID:

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

Search by EndToEnd:

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

Search by TID:

cURL
curl -sS "https://api.respawnpay.com/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://api.respawnpay.com/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. Query by a specific ID.`);
  console.log(data.items);
}