Transactions by PIX Key

Overview

The transactions by PIX key endpoints allow you to query the transaction history associated with a specific PIX key (CPF, CNPJ, phone, email, or random EVP key). They are ideal for scenarios such as:

Reconciliation by key: verify all receipts for a specific CNPJ or CPF
Auditing: audit movements of a PIX key within a period
Receipt monitoring: track payments received via a specific key

Compared to the general /api/transactions endpoint, the main difference is the mandatory PIX key filter and the larger maximum size: up to 1000 records per page (vs. 100 on the general endpoint). The query returns at most 1000 results in total -- if the key has more transactions in the period, use type, status, or shorter period filters to narrow down.

Authentication

This endpoint requires a valid Bearer token in the Authorization header:

Authorization: Bearer <your_token>

The token must be obtained through the Generate Token endpoint.

Supported PIX Key Types

Type	Format	Example
CPF	Numbers only (11 digits)	`12345678900`
CNPJ	Numbers only (14 digits)	`12345678000190`
Phone	E.164 format with `+` encoded as `%2B`	`%2B5511999999999`
Email	Valid email address	`joao@example.com`
Random key (EVP)	UUID v4	`550e8400-e29b-41d4-a716-446655440000`

When using keys with special characters in the URL (such as + in phone numbers), always apply URL encoding. In the code examples, encodeURIComponent (JavaScript) and quote(..., safe="") (Python) handle this automatically.

Endpoint 1: List Transactions by PIX Key

GET /api/pix/transactions/pix-key/{pixKey}

Parameters

Parameter	Type	Required	Default	Description
`pixKey`	string	Yes (path)	--	PIX key (URL-encoded)
`page`	integer	--	`1`	Page number
`size`	integer	--	`20`	Records per page (max. 1000)
`status`	string	--	--	`PENDING`, `CONFIRMED`, or `ERROR`
`type`	string	--	--	`PAYMENT`, `WITHDRAW`, `REFUND_IN`, or `REFUND_OUT`
`startDate`	date	--	Last 30 days	Start date (ISO 8601)
`endDate`	date	--	Today	End date (ISO 8601)

The interval between startDate and endDate cannot exceed 31 days. The query returns at most 1000 results -- if there are more transactions in the period, use additional filters (type, status, or shorter periods) to narrow down.

Key with No Results

If the provided pixKey has no transactions in the queried period, the API returns HTTP 200 with empty data:

{
  "data": [],
  "metadata": { "page": 1, "size": 20, "total": 0, "totalPages": 0, "hasNext": false, "hasPrevious": false }
}

Examples

curl -X GET "https://api.gateway.goforge.com.br/api/pix/transactions/pix-key/joao%40example.com?status=CONFIRMED&page=1&size=50" \
  -H "Authorization: Bearer your_token_here"

const pixKey = 'joao@example.com';
const params = new URLSearchParams({
  status: 'CONFIRMED',
  page: '1',
  size: '50'
});

const response = await fetch(
  `https://api.gateway.goforge.com.br/api/pix/transactions/pix-key/${encodeURIComponent(pixKey)}?${params}`,
  {
    headers: {
      'Authorization': 'Bearer your_token_here'
    }
  }
);

const data = await response.json();
console.log(data);

import requests
from urllib.parse import quote

pix_key = 'joao@example.com'

response = requests.get(
    f'https://api.gateway.goforge.com.br/api/pix/transactions/pix-key/{quote(pix_key, safe="")}',
    params={
        'status': 'CONFIRMED',
        'page': 1,
        'size': 50
    },
    headers={
        'Authorization': 'Bearer your_token_here'
    }
)

data = response.json()
print(data)

Response Example

{
  "data": [
    {
      "transactionId": "12345",
      "externalId": "order-abc123",
      "status": "Confirmado",
      "operationType": "Pix in",
      "movementType": "CREDIT",
      "originalAmount": 100.00,
      "feeAmount": 1.00,
      "finalAmount": 99.00,
      "endToEndId": "E00416968202501151030VX5Sx8fIpkY",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "processedAt": "2025-01-15T10:30:05.000Z",
      "counterpart": {
        "name": "João Silva",
        "document": "***.456.789-**",
        "bank": {
          "bankISPB": "00000000",
          "bankName": "Banco do Brasil",
          "bankCode": "001",
          "accountBranch": "0001",
          "accountNumber": "123456-7"
        }
      }
    }
  ],
  "metadata": {
    "page": 1,
    "size": 50,
    "total": 320,
    "totalPages": 7,
    "hasNext": true,
    "hasPrevious": false
  }
}

Pagination

Field	Description
`page`	Current page
`size`	Number of records per page
`total`	Total records found (max. 1000)
`totalPages`	Total available pages
`hasNext`	Indicates if there is a next page
`hasPrevious`	Indicates if there is a previous page

To get all results at once, use size=1000. To process in batches, navigate through pages while hasNext is true:

async function getAllTransactions(pixKey, filters = {}) {
  const results = [];
  let page = 1;

  do {
    const params = new URLSearchParams({ ...filters, page, size: 100 });
    const response = await fetch(
      `https://api.gateway.goforge.com.br/api/pix/transactions/pix-key/${encodeURIComponent(pixKey)}?${params}`,
      { headers: { 'Authorization': 'Bearer your_token_here' } }
    );
    const { data, metadata } = await response.json();
    results.push(...data);
    if (!metadata.hasNext) break;
    page++;
  } while (true);

  return results;
}

Endpoint 2: Query Transaction by PIX Key and Identifier

GET /api/pix/transactions/pix-key/{pixKey}/{identifier}

Parameters

Parameter	Type	Required	Description
`pixKey`	string	Yes	PIX key (URL-encoded)
`identifier`	string	Yes	Transaction identifier (URL-encoded)

The identifier is compared simultaneously against three transaction fields:

endToEndId -- PIX End-to-End ID (e.g., E00416968202501151030VX5Sx8fIpkY)
externalId -- External identifier provided at transaction creation
id (numeric) -- Internal Avista transaction ID (only if the value is purely numeric)

In practice there is no ambiguity: each identifier type has a unique format (e2eId starts with E followed by 32 alphanumeric characters; id is purely numeric; externalId is any string).

Examples

curl -X GET "https://api.gateway.goforge.com.br/api/pix/transactions/pix-key/joao%40example.com/E00416968202501151030VX5Sx8fIpkY" \
  -H "Authorization: Bearer your_token_here"

curl -X GET "https://api.gateway.goforge.com.br/api/pix/transactions/pix-key/joao%40example.com/order-abc123" \
  -H "Authorization: Bearer your_token_here"

const pixKey = 'joao@example.com';
const identifier = 'E00416968202501151030VX5Sx8fIpkY';

const response = await fetch(
  `https://api.gateway.goforge.com.br/api/pix/transactions/pix-key/${encodeURIComponent(pixKey)}/${encodeURIComponent(identifier)}`,
  {
    headers: {
      'Authorization': 'Bearer your_token_here'
    }
  }
);

if (response.status === 404) {
  console.log('Transaction not found');
} else {
  const transaction = await response.json();
  console.log(transaction);
}

import requests
from urllib.parse import quote

pix_key = 'joao@example.com'
identifier = 'E00416968202501151030VX5Sx8fIpkY'

response = requests.get(
    f'https://api.gateway.goforge.com.br/api/pix/transactions/pix-key/{quote(pix_key, safe="")}/{quote(identifier, safe="")}',
    headers={
        'Authorization': 'Bearer your_token_here'
    }
)

if response.status_code == 404:
    print('Transaction not found')
else:
    transaction = response.json()
    print(transaction)

Response 200 -- Transaction Found

{
  "transactionId": "12345",
  "externalId": "order-abc123",
  "status": "Confirmado",
  "operationType": "Pix in",
  "movementType": "CREDIT",
  "originalAmount": 100.00,
  "feeAmount": 1.00,
  "finalAmount": 99.00,
  "endToEndId": "E00416968202501151030VX5Sx8fIpkY",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "processedAt": "2025-01-15T10:30:05.000Z",
  "counterpart": {
    "name": "João Silva",
    "document": "***.456.789-**",
    "bank": {
      "bankISPB": "00000000",
      "bankName": "Banco do Brasil",
      "bankCode": "001",
      "accountBranch": "0001",
      "accountNumber": "123456-7"
    }
  }
}

Response 404 -- Not Found

Returned when no transaction matches the provided identifier for the specified pixKey.

{
  "statusCode": 404,
  "message": "Transação não encontrada"
}

Field Mapping

Status

Internal Value	Returned Value
`PENDING`	`Pendente`
`CONFIRMED`	`Confirmado`
`ERROR`	`Error`

Operation Type

Internal Value	Returned Value	Description
`PAYMENT`	`Pix in`	PIX receipt
`WITHDRAW`	`Pix out`	PIX payment
`REFUND_IN`	`Refund in`	Refund requested (debit)
`REFUND_OUT`	`Refund out`	Reversal received (credit)

Movement Type

Operation Type	Movement
`Pix in`	`CREDIT`
`Pix out`	`DEBIT`
`Refund in`	`DEBIT`
`Refund out`	`CREDIT`

Differences from `/api/transactions`

Aspect	`/api/transactions`	`/api/pix/transactions/pix-key/\{pixKey\}`
Main filter	Entire account	By specific PIX key
Max. `size` per page	100	1000
Max. total results	No limit	1000
Default `startDate`	Last 31 days	Last 30 days
Non-existent key / no results	200 with empty list	200 with empty list
Search by `externalId`	Query param `?externalId=`	Path param `/\{identifier\}`
Search by `endToEndId`	Query param `?endToEndId=`	Path param `/\{identifier\}`

Use Cases

Error Codes

Code	Description
`400`	Invalid parameters, reversed dates, or interval exceeds 31 days
`401`	Token not provided or invalid
`404`	Transaction not found (only on the `/\{pixKey\}/\{identifier\}` endpoint)

Transactions by PIX Key

Overview

Authentication

Supported PIX Key Types

Endpoint 1: List Transactions by PIX Key

Parameters

Key with No Results

Examples

Response Example

Endpoint 2: Query Transaction by PIX Key and Identifier

Parameters

Examples

Response 200 -- Transaction Found

Response 404 -- Not Found

Field Mapping

Status

Operation Type

Movement Type

Differences from `/api/transactions`

Use Cases

Error Codes

Next Steps

Search Transactions

Check Status

Configure Webhooks

On this page

Transactions by PIX Key

Reconciliation by PIX key

Verify specific payment by endToEndId

Corporate audit by CNPJ

Receipt monitoring for a specific period

Search Transactions

Check Status

Configure Webhooks

On this page