> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://en.docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://en.docs.api.corpx.com/_mcp/server.

# Lookup payment by identifier

GET https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/payments/lookup

Returns a PIX payment, sent or received, as the settlement bank
reports it now. Look it up by the `identifier` you sent on the
PIX out, or by `endToEnd`. Backed by a live call to the banking
partner. When the settlement bank does not find a payment that
already has a final status at CorpX (completed, refused before
reaching the settlement bank, or returned), the response is `200`
with that status.

Pass `waitForFinalStatus` to hold this call until the payment
reaches `COMPLETED`, `FAILED` or `REVERSED`, or until the wait
expires, instead of polling this endpoint yourself. The response
shape does not change. Only this endpoint accepts the parameter;
`GET .../pix/transactions` ignores it. The webhook remains the
authoritative outcome; the wait is for callers that need the
result in the same request.


Reference: https://en.docs.api.corpx.com/baas/referencia/pix/lookup-payment

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `accountId` (string, required) — Account ID.

### Query parameters

- `identifier` (string, optional) — Client-supplied identifier from the original PIX out request (1-38 chars `[A-Za-z0-9._-]`). For BigPix chunks, use the full chunk identifier `{base}#bigpix:{shortId}#chunk:{i}/{n}`. Send `identifier`, `endToEnd` or both; without either the response is `400 missing_identifier`. With both, `identifier` is tried first and `endToEnd` is the fallback.
- `endToEnd` (string, optional) — BACEN end-to-end ID of the PIX. Finds received payments too: it is the lookup the API itself uses to fill the payer of a paid QR code. `endToEndId` is accepted as an alias.
- `waitForFinalStatus` (integer, optional) — Seconds to hold the connection while the server polls the settlement bank until the payment reaches a final status (`COMPLETED`, `FAILED` or `REVERSED`). Use this instead of calling this endpoint in a loop. The first attempt goes out 1 s after the call, inside the wait: right after the `POST` the settlement bank usually does not have the payment yet. Omit it, leave it empty or pass `0` to receive the current status immediately, as before. The response shape does not change. A value above 10 is capped at 10; the applied wait comes back in the `X-Wait-Seconds` header. A non-integer or negative value is `400 invalid_payload`. When the wait expires before a final status: if the payment was read at least once, the last status read comes back with `200`. If it was never read, the response is the one of the last attempt — `404` when the settlement bank did not find it, or the settlement bank error when that attempt failed. A definitive refusal from the settlement bank (`4xx` other than `408` and `429`) comes back right away, without waiting. The response can arrive a few seconds after the wait: an attempt already in flight when the wait expires is allowed to finish (up to 5 s). Set your HTTP client timeout to at least `waitForFinalStatus` + 10 s — 20 s for `waitForFinalStatus=10`. The webhook is still the authoritative path. This parameter is for the caller that needs the outcome in the same request.

### Headers

- `X-Tenant-Id` (string, required) — Tenant context used for authorization and routing.

## Response

### 200

The payment. When `waitForFinalStatus` is greater than 0, this is the final status, or the last status read if the wait expired first.

- `partnerId` (string, required) — Operation reference at the settlement bank. The current settlement bank does not return it on PIX lookups, so it comes empty; use `endToEndId` or `identifier`.
- `endToEndId` (string, required) — BACEN end-to-end ID. Empty while the settlement bank has not assigned one.
- `identifier` (string, required) — Identifier echoed by the settlement bank. On a PIX out, the one you sent.
- `direction` (string, required) — `OUT` when the account in the path paid, `IN` when it received. Empty when the settlement bank payload does not tell the sides apart.
- `status` (enum, required) — Canonical status. `COMPLETED`, `FAILED` and `REVERSED` are final — the values `waitForFinalStatus` waits for. - `INITIATED` — created, not yet sent to BACEN - `PENDING_APPROVAL` — held inside the settlement bank (its authorisation queue or its risk review). It never means an approval is pending on your side or on ours; read `hold`. - `PROCESSING` — sent to BACEN, awaiting settlement - `COMPLETED` — confirmed by BACEN - `FAILED` — rejected; the settlement bank reason is in `errorMessage` - `REVERSED` — returned after settlement - `UNKNOWN` — settlement bank status we do not map yet; the raw value is in `partnerStatus`
  - Allowed values: `INITIATED`, `PENDING_APPROVAL`, `PROCESSING`, `COMPLETED`, `FAILED`, `REVERSED`, `UNKNOWN`
- `amount` (double, required) — Amount in BRL, always positive. `direction` gives the side.
- `currency` (enum, required)
  - Allowed values: `BRL`
- `description` (string, required) — Message attached to the PIX. May be empty.
- `initiation` (string, required) — How the PIX was started, as the settlement bank labels it: `pix-key`, `manual`, `static-qr-code` or `dynamic-qr-code`. May be empty.
- `errorMessage` (string, required) — Settlement bank reason when `status` is `FAILED`. Empty otherwise.
- `reversal` (boolean, required) — Refund marker. The current settlement bank does not report it on PIX lookups, so it comes `false`; refunds show up in the statement (`reversal`, `originalEndToEnd`) and in the webhooks.
- `originalEndToEnd` (string, required) — End-to-end of the refunded PIX. Empty for the same reason as `reversal`.
- `occurredAt` (datetime, required) — Transaction time in RFC 3339 with São Paulo offset (`-03:00`).
- `payer` (PixPaymentParty, required, nullable) — Who paid. `null` when the settlement bank sends nothing about this side.
- `beneficiary` (PixPaymentParty, required, nullable) — Who received. `null` when the settlement bank sends nothing about this side.
- `errorCode` (string, optional) — Public code of the refusal, the same one the `pix.out.failed` webhook carries (e.g. `insufficient_funds`, `limit_exceeded_transaction`, `limit_exceeded_daily`, `partner_rejected`). Present only when `status` is `FAILED`. Branch on this field, not on the `errorMessage` text.
- `partnerStatus` (string, optional) — Raw status at the settlement bank, echoed in a clearly named field (never in `status`). Present only when the settlement bank reports one. These are the settlement bank's own values and may change without notice — do not use them in status comparisons; they exist so you can attach evidence to a support ticket.
- `partnerStatusId` (integer, optional) — Numeric status code at the settlement bank. Present only when it is not zero.
- `hold` (PixPaymentDetailHold, optional) — Present only while the order is held by someone. Today the only possible owner is the settlement bank, which is exactly the information `PENDING_APPROVAL` fails to convey: when this object is present there is nothing to approve on your side or on ours.

## Errors

### 400 Bad Request Error

Invalid request sent by client.

- `errorCode` (string, required) — Stable machine-readable code. See `ErrorCode` for the known values.
- `message` (string, required) — Human-readable explanation (pt-BR). Presentation only; may change.
- `docs` (string, optional) — Link to this code in the public error catalogue.
- `requestId` (string, optional) — Gateway request id. Quote it when contacting support.
- `details` (map from string to any, optional) — Optional machine-readable context for the specific `errorCode` (for example `kind` on `identity_verification_monthly_limit_exceeded`, `maxBytes` on `payload_too_large`, `attemptsRemaining` on `facetec_attempts_exhausted`). Keys are documented per operation; absent when the code carries no extra context.
- `partner` (ErrorResponsePartner, optional) — Raw error from the settlement bank, when the failure came from it. Diagnostic only.

### 404 Not Found Error

Payment not found at the settlement bank. With `waitForFinalStatus`, it comes only when the payment never appeared during the wait; right after `POST .../pix/out/async` it usually means the settlement bank has not registered it yet.

- `errorCode` (string, required) — Stable machine-readable code. See `ErrorCode` for the known values.
- `message` (string, required) — Human-readable explanation (pt-BR). Presentation only; may change.
- `docs` (string, optional) — Link to this code in the public error catalogue.
- `requestId` (string, optional) — Gateway request id. Quote it when contacting support.
- `details` (map from string to any, optional) — Optional machine-readable context for the specific `errorCode` (for example `kind` on `identity_verification_monthly_limit_exceeded`, `maxBytes` on `payload_too_large`, `attemptsRemaining` on `facetec_attempts_exhausted`). Keys are documented per operation; absent when the code carries no extra context.
- `partner` (ErrorResponsePartner, optional) — Raw error from the settlement bank, when the failure came from it. Diagnostic only.

### 500 Internal Server Error

Unexpected server error.

- `errorCode` (string, required) — Stable machine-readable code. See `ErrorCode` for the known values.
- `message` (string, required) — Human-readable explanation (pt-BR). Presentation only; may change.
- `docs` (string, optional) — Link to this code in the public error catalogue.
- `requestId` (string, optional) — Gateway request id. Quote it when contacting support.
- `details` (map from string to any, optional) — Optional machine-readable context for the specific `errorCode` (for example `kind` on `identity_verification_monthly_limit_exceeded`, `maxBytes` on `payload_too_large`, `attemptsRemaining` on `facetec_attempts_exhausted`). Keys are documented per operation; absent when the code carries no extra context.
- `partner` (ErrorResponsePartner, optional) — Raw error from the settlement bank, when the failure came from it. Diagnostic only.

## Types

### PixPaymentParty

One side of a PIX payment as the settlement bank reports it. Each field appears only when the settlement bank sends it.

- `name` (string, optional) — Full name.
- `document` (string, optional) — CPF or CNPJ.
- `bankIspb` (string, optional) — 8-digit ISPB of the institution.
- `bankCode` (string, optional) — Bank code (COMPE).
- `bankName` (string, optional) — Institution name.
- `branch` (string, optional) — Branch.
- `account` (string, optional) — Account number.
- `accountType` (string, optional) — Account type, when the settlement bank reports it.
- `pixKey` (string, optional) — PIX key of the beneficiary, when the payment used one.

### PixPaymentDetailHold

Present only while the order is held by someone. Today the only possible owner is the settlement bank, which is exactly the information `PENDING_APPROVAL` fails to convey: when this object is present there is nothing to approve on your side or on ours.

- `owner` (enum, optional) — Who is holding the order.
  - Allowed values: `partner`
- `reason` (enum, optional) — - `partner_authorization` — the settlement bank's internal authorisation queue. It does not resolve by itself for API-initiated orders and the settlement bank sends no transition notification while it holds; release can take hours or days. - `partner_risk_analysis` — risk review, usually resolved in minutes with an approval or a rejection. - `partner_unspecified` — held, queue not disclosed.
  - Allowed values: `partner_authorization`, `partner_risk_analysis`, `partner_unspecified`

### ErrorResponsePartner

Raw error from the settlement bank, when the failure came from it. Diagnostic only.

- `code` (string, optional)
- `message` (string, optional)
- `field` (string, optional) — Field the partner pointed at, when any.

## Examples

### PIX out settled

**Response**

```json
{
  "partnerId": "",
  "endToEndId": "E50871921202602200833NdtppklLCj2",
  "identifier": "order-12345",
  "direction": "OUT",
  "status": "COMPLETED",
  "amount": 150,
  "currency": "BRL",
  "description": "Pedido 12345",
  "initiation": "pix-key",
  "errorMessage": "",
  "reversal": false,
  "originalEndToEnd": "",
  "occurredAt": "2026-02-20T08:33:39-03:00",
  "payer": {
    "name": "EMPRESA EXEMPLO LTDA",
    "document": "12345678000190",
    "bankIspb": "50871921",
    "branch": "0001",
    "account": "1234567"
  },
  "beneficiary": {
    "name": "MARIA DA SILVA",
    "document": "12345678900",
    "bankIspb": "00000000",
    "bankCode": "001",
    "branch": "1234",
    "account": "567890",
    "pixKey": "maria@example.com"
  },
  "partnerStatus": "confirmed",
  "partnerStatusId": 3
}
```

**SDK Code**

```python PIX out settled
import requests

url = "https://tenant.api.corpx.com/v1/accounts/accountId/pix/payments/lookup"

querystring = {"endToEnd":"E50871921202602200833NdtppklLCj2","identifier":"order-12345","waitForFinalStatus":"10"}

headers = {
    "X-Tenant-Id": "X-Tenant-Id",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript PIX out settled
const url = 'https://tenant.api.corpx.com/v1/accounts/accountId/pix/payments/lookup?endToEnd=E50871921202602200833NdtppklLCj2&identifier=order-12345&waitForFinalStatus=10';
const options = {
  method: 'GET',
  headers: {'X-Tenant-Id': 'X-Tenant-Id', Authorization: 'Bearer <token>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go PIX out settled
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://tenant.api.corpx.com/v1/accounts/accountId/pix/payments/lookup?endToEnd=E50871921202602200833NdtppklLCj2&identifier=order-12345&waitForFinalStatus=10"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Tenant-Id", "X-Tenant-Id")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby PIX out settled
require 'uri'
require 'net/http'

url = URI("https://tenant.api.corpx.com/v1/accounts/accountId/pix/payments/lookup?endToEnd=E50871921202602200833NdtppklLCj2&identifier=order-12345&waitForFinalStatus=10")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Tenant-Id"] = 'X-Tenant-Id'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java PIX out settled
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://tenant.api.corpx.com/v1/accounts/accountId/pix/payments/lookup?endToEnd=E50871921202602200833NdtppklLCj2&identifier=order-12345&waitForFinalStatus=10")
  .header("X-Tenant-Id", "X-Tenant-Id")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php PIX out settled
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://tenant.api.corpx.com/v1/accounts/accountId/pix/payments/lookup?endToEnd=E50871921202602200833NdtppklLCj2&identifier=order-12345&waitForFinalStatus=10', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'X-Tenant-Id' => 'X-Tenant-Id',
  ],
]);

echo $response->getBody();
```

```csharp PIX out settled
using RestSharp;

var client = new RestClient("https://tenant.api.corpx.com/v1/accounts/accountId/pix/payments/lookup?endToEnd=E50871921202602200833NdtppklLCj2&identifier=order-12345&waitForFinalStatus=10");
var request = new RestRequest(Method.GET);
request.AddHeader("X-Tenant-Id", "X-Tenant-Id");
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift PIX out settled
import Foundation

let headers = [
  "X-Tenant-Id": "X-Tenant-Id",
  "Authorization": "Bearer <token>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://tenant.api.corpx.com/v1/accounts/accountId/pix/payments/lookup?endToEnd=E50871921202602200833NdtppklLCj2&identifier=order-12345&waitForFinalStatus=10")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### PIX out held by the settlement bank

**Response**

```json
{
  "partnerId": "",
  "endToEndId": "E50871921202608200900Ab12Cd34Ef5",
  "identifier": "order-12346",
  "direction": "OUT",
  "status": "PENDING_APPROVAL",
  "amount": 16,
  "currency": "BRL",
  "description": "",
  "initiation": "pix-key",
  "errorMessage": "",
  "reversal": false,
  "originalEndToEnd": "",
  "occurredAt": "2026-08-20T09:00:00-03:00",
  "payer": {
    "name": "EMPRESA EXEMPLO LTDA",
    "document": "12345678000190",
    "bankIspb": "50871921",
    "branch": "0001",
    "account": "1234567"
  },
  "beneficiary": {
    "name": "MARIA DA SILVA",
    "document": "12345678900",
    "pixKey": "maria@example.com"
  },
  "partnerStatus": "awaiting-authorization",
  "partnerStatusId": 7,
  "hold": {
    "owner": "partner",
    "reason": "partner_authorization"
  }
}
```

**SDK Code**

```python PIX out held by the settlement bank
import requests

url = "https://tenant.api.corpx.com/v1/accounts/accountId/pix/payments/lookup"

querystring = {"endToEnd":"E50871921202602200833NdtppklLCj2","identifier":"order-12345","waitForFinalStatus":"10"}

headers = {
    "X-Tenant-Id": "X-Tenant-Id",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript PIX out held by the settlement bank
const url = 'https://tenant.api.corpx.com/v1/accounts/accountId/pix/payments/lookup?endToEnd=E50871921202602200833NdtppklLCj2&identifier=order-12345&waitForFinalStatus=10';
const options = {
  method: 'GET',
  headers: {'X-Tenant-Id': 'X-Tenant-Id', Authorization: 'Bearer <token>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go PIX out held by the settlement bank
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://tenant.api.corpx.com/v1/accounts/accountId/pix/payments/lookup?endToEnd=E50871921202602200833NdtppklLCj2&identifier=order-12345&waitForFinalStatus=10"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Tenant-Id", "X-Tenant-Id")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby PIX out held by the settlement bank
require 'uri'
require 'net/http'

url = URI("https://tenant.api.corpx.com/v1/accounts/accountId/pix/payments/lookup?endToEnd=E50871921202602200833NdtppklLCj2&identifier=order-12345&waitForFinalStatus=10")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Tenant-Id"] = 'X-Tenant-Id'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java PIX out held by the settlement bank
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://tenant.api.corpx.com/v1/accounts/accountId/pix/payments/lookup?endToEnd=E50871921202602200833NdtppklLCj2&identifier=order-12345&waitForFinalStatus=10")
  .header("X-Tenant-Id", "X-Tenant-Id")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php PIX out held by the settlement bank
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://tenant.api.corpx.com/v1/accounts/accountId/pix/payments/lookup?endToEnd=E50871921202602200833NdtppklLCj2&identifier=order-12345&waitForFinalStatus=10', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'X-Tenant-Id' => 'X-Tenant-Id',
  ],
]);

echo $response->getBody();
```

```csharp PIX out held by the settlement bank
using RestSharp;

var client = new RestClient("https://tenant.api.corpx.com/v1/accounts/accountId/pix/payments/lookup?endToEnd=E50871921202602200833NdtppklLCj2&identifier=order-12345&waitForFinalStatus=10");
var request = new RestRequest(Method.GET);
request.AddHeader("X-Tenant-Id", "X-Tenant-Id");
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift PIX out held by the settlement bank
import Foundation

let headers = [
  "X-Tenant-Id": "X-Tenant-Id",
  "Authorization": "Bearer <token>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://tenant.api.corpx.com/v1/accounts/accountId/pix/payments/lookup?endToEnd=E50871921202602200833NdtppklLCj2&identifier=order-12345&waitForFinalStatus=10")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```