Skip to main content

Locations

The following set of endpoints are intended to handle configuration and removal of locations for payload usage.


List locations​

Endpoint to list all available locations (payload sites) for the participant.

What are Locations:

Locations are unique URLs where charge data (payloads) is stored. Each PIX charge has an associated location that can be used to consult charge data via QR Code or Pix Copy and Paste.

Returned Information:
  • ID: Unique identifier of the location
  • Location: Full URL of the location
  • Type: Type of charge (cob, cobv)
  • Creation Date: When the location was created
  • Last Modification: Last update of the location
Tip!

Locations are automatically created when you create charges.


GET /v1/loc
Requires authorization for the scope: payload.location.read


Request

To obtain the result of the location query, it is necessary to provide the inicio and fim parameters, as shown in the code snippet below. These parameters restrict results to locations within this date range.

/v1/loc/?inicio=2020-10-22T16:01:35Z&fim=2020-10-23T16:01:35Z

Responses

The responses below represent Success(200) and failures/errors from the request.

{
  "parametros": {
    "inicio": "2023-10-01T00:00:00Z",
    "fim": "2023-10-31T23:59:59Z",
    "paginacao": {
      "paginaAtual": 0,
      "itensPorPagina": 100,
      "quantidadeDePaginas": 1,
      "quantidadeDeItens": 3
    }
  },
  "loc": [
    {
      "id": 789,
      "location": "pix.example.com/qr/v2/cob/fb2761260e054c7a94fb7b7b",
      "tipoCob": "cob",
      "criacao": "2023-10-15T14:30:00Z",
      "txid": "fb2761260e054c7a94fb7b7b"
    },
    {
      "id": 790,
      "location": "pix.example.com/qr/v2/cobv/ab1234567890123456789012",
      "tipoCob": "cobv",
      "criacao": "2023-10-16T09:15:00Z",
      "txid": "ab1234567890123456789012"
    },
    {
      "id": 791,
      "location": "pix.example.com/qr/v2/cobv/xyz789",
      "tipoCob": "cobv",
      "criacao": "2023-10-17T16:45:00Z",
      "txid": "xyz789"
    }
  ]
}

Get specific location​

Endpoint to retrieve details of a specific location by its ID.

What you get:
  • Location Data: ID, URL, type of charge
  • Charge Information: Full data of the associated charge
  • Status: Current status of the linked charge
  • Metadata: Creation and modification dates
Use Cases:
  • QR Code Validation: Check if a location is still valid
  • Auditing: Track charges via their locations
  • Integration: Retrieve data for external systems
  • Debug: Investigate issues in specific charges
TypeDescriptionURL Pattern
cobImmediate charge/qr/v2/cob/:txid
cobvCharge with due date/qr/v2/cobv/:txid
Important!

The location returns the current charge data, which may have been modified after creation.


GET /v1/loc/:id
Requires authorization for the scope: payload.location.read


Responses

The responses below represent Success(200) and failures/errors from the request.

// Immediate charge Location
{
  "responseTime": 300,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "id": 789,
  "location": "pix.example.com/qr/v2/cob/fb2761260e054c7a94fb7b7b",
  "tipoCob": "cob",
  "criacao": "2023-10-15T14:30:00Z",
  "txid": "fb2761260e054c7a94fb7b7b"
}

OU

// Due Charge Location
{
  "responseTime": 300,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "id": 790,
  "location": "pix.example.com/qr/v2/cobv/ab1234567890123456789012",
  "tipoCob": "cobv",
  "criacao": "2023-10-16T09:15:00Z",
  "txid": "ab1234567890123456789012"
}


Endpoint used to remove the binding of a location, making it unavailable for queries via QR Code.

Irreversible Operation!

This operation CANNOT BE UNDONE.

Consult your technical team to understand the specific impacts of this operation on your system.


Restrictions:
  • Status: Only charges with status ATIVA can have their location unlinked
  • Permissions: Requires a specific scope for removal
DELETE /v1/loc/:id/txid
Requires authorization for the scope: payload.location.write


Responses

The responses below represent Success(200) and failures/errors from the request.

// Immediate charge Location
{
  "responseTime": 300,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "id": 789,
  "location": "pix.example.com/qr/v2/cob/fb2761260e054c7a94fb7b7b",
  "tipoCob": "cob",
  "criacao": "2023-10-15T14:30:00Z",
  "txid": "fb2761260e054c7a94fb7b7b"
}

OU

// Due charge Location
{
  "responseTime": 300,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "id": 790,
  "location": "pix.example.com/qr/v2/cobv/ab1234567890123456789012",
  "tipoCob": "cobv",
  "criacao": "2023-10-16T09:15:00Z",
  "txid": "ab1234567890123456789012"
}

Last updated on