Skip to main content
API docs by Redocly

OpenPix (1.0.0)

Download OpenAPI specification:Download

A OpenPix é uma Plataforma de Gestão de Pagamentos.

Para utilizar nossa API de Produção, utilize exclusivamente o seguinte endpoint:

👉 https://api.openpix.com.br/

Além disso, oferecemos também um ambiente de sandbox (ambiente de testes), ideal para desenvolvimento e validação de integrações sem impactar dados reais.

👉 https://api.woovi-sandbox.com/

Veja como configurar seu acesso a nossa API aqui.

account

Endpoint to manage Accounts

Close an Account

Closes an Account.

Notes:

  • Accounts with balance cannot be closed.
Authorizations:
AppID
path Parameters
accountId
required
string
Example: 6290ccfd42831958a405debc

ID of the Account

Responses

Request samples 

const http = require('https');

const options = {
  method: 'DELETE',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/account/6290ccfd42831958a405debc',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "status": "OK",
  • "accountId": "6290ccfd42831958a405debc"
}

Get an Account

Authorizations:
AppID
path Parameters
accountId
required
string
Example: 6290ccfd42831958a405debc

ID of the Account

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/account/6290ccfd42831958a405debc',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "account": {
    }
}

Get a list of Accounts

Authorizations:
AppID
query Parameters
email
string
Example: email=email0@example.com

You can use the email to filter accounts

skip
number

Number of items to skip for pagination

limit
number
Example: limit=10

Maximum number of items to return

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/account/?email=email0%40example.com&skip=0&limit=10',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "pageInfo": {
    },
  • "accounts": [
    ]
}

Duplicates the Account

Duplicates the account associated with the authorization appId. Requires the bank account feature to be enabled.

Authorizations:
AppID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'POST',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/account',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "account": {
    }
}

Withdraw from an Account

An additional fee may be charged depending on the minimum free withdrawal amount. See more about at https://developers.openpix.com.br/docs/FAQ/faq-virtual-account/#onde-posso-consultar-as-taxas-da-minha-conta-virtual

Authorizations:
AppID
path Parameters
accountId
required
string
Example: 6290ccfd42831958a405debc

ID of the Account

Request Body schema: application/json
required
value
number

Value in cents

Responses

Request samples

Content type
application/json
{
  • "value": 7000
}

Response samples

Content type
application/json
{
  • "withdraw": {
    }
}

account register

Endpoint to manage account registrations.

Delete an account registration

Deletes an account registration that is in PENDING status

Authorizations:
AppID
path Parameters
correlationID
required
string non-empty

CorrelationID of the account register to delete

Responses

Response samples

Content type
application/json
{
  • "message": "Account register successfully deleted",
  • "accountRegisterId": "12345678901234"
}

Get account register by CorrelationID

Retrieves an existing account registration by CorrelationID

Authorizations:
AppID
path Parameters
CorrelationID
required
string
Example: 6fe18d8e-5009-4f57-8f1d-5b084b6b83ac

CorrelationID of the account register

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/account-register',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "officialName": "Company Official Name",
  • "tradeName": "Company Trade Name",
  • "type": "BAAS",
  • "taxID": {
    },
  • "status": "PENDING",
  • "correlationID": "6fe18d8e-5009-4f57-8f1d-5b084b6b83ac"
}

application

Endpoints to manage applications for authentication and API access.

Delete an application

Deactivates an application by setting isActive to false and adding a removedAt timestamp

Authorizations:
AppID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'DELETE',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/application',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "success": true
}

Create a new application

Creates a new application for a company. If the company has the APPLICATION_SCOPES_REQUIRED feature enabled, the scopes field is required.

Authorizations:
AppID
Request Body schema: application/json
required

Data to create a new application

accountId
string

The ID of the company bank account

object

Responses

Request samples

Content type
application/json
Example
{
  • "accountId": "507f1f77bcf86cd799439011",
  • "application": {
    }
}

Response samples

Content type
application/json
Example
{
  • "application": {
    }
}

boleto

Endpoints to validate and pay boletos (Boleto OUT).

The Boleto OUT flow has three steps:

  1. Validate the boleto by its barcode (POST /api/v1/boleto/validate) to confirm the amount, due date and beneficiary.
  2. Create the payment (POST /api/v1/payment) with type: "BOLETO" and the boletoBarcode.
  3. Approve the payment (POST /api/v1/payment/approve), unless it was created with autoApprove: true.

Requires the BOLETO_VALIDATE_POST scope on the application.

Validate a boleto by barcode

Validates a boleto by its barcode before paying it. This is step 1 of the Boleto OUT flow: it confirms the amount, due date and beneficiary so you can review the boleto before creating the payment.

The barcode must have 44, 47 or 48 digits. All monetary values are returned in cents.

Requires the BOLETO_VALIDATE_POST scope on the application.

After validating, create the payment with POST /api/v1/payment using type: "BOLETO" and the boletoBarcode.

Authorizations:
AppID
Request Body schema: application/json
required
barcode
required
string

The boleto barcode. Must have 44, 47 or 48 digits.

Responses

Request samples

Content type
application/json
{
  • "barcode": "34195148200000003001095517077320772982609000"
}

Response samples

Content type
application/json
{
  • "boleto": {
    }
}

cashback-fidelity

Endpoint to manage exclusive cashbacks

Get the exclusive cashback amount an user still has to receive by taxID.

Authorizations:
AppID
path Parameters
taxID
required
string
Examples:
  • 60151449000182 -

The raw tax ID from the customer you want to get the balance.

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/cashback-fidelity/balance/60151449000182',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "balance": 0,
  • "status": "string"
}

Get or create cashback for a customer.

Create a new cashback exclusive for the customer with a given taxID. If the customer already has a pending excluisve cashback, this endpoint will return it instead.

Authorizations:
AppID
Request Body schema: application/json
required

Customer's taxID and the cash

taxID
string

Customer taxID (CPF or CNPJ)

value
number

Cashback value in centavos

Responses

Request samples

Content type
application/json
{
  • "value": 100,
  • "taxID": 11111111111
}

Response samples

Content type
application/json
{
  • "cashback": {
    },
  • "message": "string"
}

charge

Endpoint to manage Charges

Get an image of Qr Code from a Charge

Authorizations:
AppID
path Parameters
id
required
string
Examples:
  • fe7834b4060c488a9b0f89811be5f5cf -

charge link payment ID

query Parameters
size
string
Examples:
  • size=768 -

Size for the image. This size should be between 600 and 4096. if the size parameter was not passed, the default value will be 1024.

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/openpix/charge/brcode/image/fe7834b4060c488a9b0f89811be5f5cf.png?size=768',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "error": "string"
}

Get a base64 encoded QR Code image from a Charge

Authorizations:
AppID
path Parameters
id
required
string
Examples:
  • fe7834b4060c488a9b0f89811be5f5cf -

charge ID, payment link ID, or QR code ID

query Parameters
size
string
Examples:
  • size=768 -

Size for the image. This size should be between 600 and 4096. If the size parameter is not passed, the default value will be 1024.

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/image/qrcode/base64/fe7834b4060c488a9b0f89811be5f5cf?size=768',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "success": true,
  • "imageBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

Delete a charge

Authorizations:
AppID
path Parameters
id
required
string
Examples:
  • Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA== -
  • fe7834b4060c488a9b0f89811be5f5cf -

charge ID or correlation ID. You will need URI encoding if your correlation ID has characters outside the ASCII set or reserved characters (%, #, /).

Responses

Request samples 

const http = require('https');

const options = {
  method: 'DELETE',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/charge/Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA==',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "status": "OK",
  • "id": "fe7834b4060c488a9b0f89811be5f5cf"
}

Edit expiration date of a charge

Authorizations:
AppID
path Parameters
id
required
string
Examples:
  • fe7834b4060c488a9b0f89811be5f5cf -

correlation ID. You will need URI encoding if your correlation ID has characters outside the ASCII set or reserved characters (%, #, /).

Request Body schema: application/json
required

Expires date to update charge

expiresDate
string

Expiration date of the charge. Only in ISO 8601 format.

Responses

Request samples

Content type
application/json
{
  • "expiresDate": "2021-04-01T17:28:51.882Z"
}

Response samples

Content type
application/json
{
  • "charge": {
    }
}

Get one charge

Authorizations:
AppID
path Parameters
id
required
string
Example: fe7834b4060c488a9b0f89811be5f5cf

charge ID or correlation ID. You will need URI encoding if your correlation ID has characters outside the ASCII set or reserved characters (%, #, /).

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/charge/fe7834b4060c488a9b0f89811be5f5cf',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "charge": {
    }
}

Get a list of charges

Authorizations:
AppID
query Parameters
start
string <date-time> (Start Date)
Example: start=2020-01-01T00:00:00Z

Start date used in the query. Complies with RFC 3339.

end
string <date-time> (End Date)
Example: end=2020-12-01T17:00:00Z

End date used in the query. Complies with RFC 3339.

status
string
Enum: "ACTIVE" "COMPLETED" "EXPIRED"
customer
string

Customer Correlation ID

subscription
string

Subscription Correlation ID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/charge?start=2020-01-01T00%3A00%3A00Z&end=2020-12-01T17%3A00%3A00Z&status=SOME_STRING_VALUE&customer=SOME_STRING_VALUE&subscription=SOME_STRING_VALUE',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "pageInfo": {
    },
  • "charges": {
    }
}

Create a new Charge

Endpoint to create a new Charge for a customer

Authorizations:
AppID
query Parameters
return_existing
boolean
Examples:
  • return_existing=true -

Make the endpoint idempotent, will return an existent charge if already has a one with the correlationID

Request Body schema: application/json
required

Data to create a new charge

correlationID
required
string

Your correlation ID to keep track of this charge

value
required
number

Value in cents of this charge

type
string
Enum: "DYNAMIC" "OVERDUE" "BOLETO"

Charge type is used to determine whether a charge will have a deadline, fines and interests

comment
string

Comment to be added in infoPagador

expiresIn
number

Expires the charge in seconds (minimum is 5 minutes)

expiresDate
string

Expiration date of the charge. Only in ISO 8601 format.

dueDate
string

Due date for OVERDUE, BOLETO, or subscription charges in ISO 8601 format.

object or object or object (CustomerPayload)

Customer field is not required. However, if you decide to send it, you must send at least one of the following combinations, name + taxID or name + email or name + phone.

ensureSameTaxID
boolean

true to ensure that the payer taxID must be the same as the customer taxID.

fixedLocation
boolean

true to fix the qrcode of the charge, same qrcode to all future charges.

paymentLinkID
string

Payment Link ID, used to link charges to the same qrCode.

daysForDueDate
number

Time in days until the charge hits the deadline so fines and interests start applying. This property is only considered for charges of type OVERDUE

daysAfterDueDate
number

Time in days that a charge is still payable after the deadline. This property is only considered for charges of type OVERDUE

object

Interests configuration. This property is only considered for charges of type OVERDUE

object

Fines configuration. This property is only considered for charges of type OVERDUE

object

Discount settings for the charge. This property is only considered for charges of type OVERDUE.

How it interacts with fines and interests. Discount only applies to payments before the due date (controlled by daysForDueDate). On or after the due date the discount is gone, and fines (applied once) and interests (accruing per day) start adding on top of value. Use the day-by-day simulator to preview the totals a payer sees on each day of the charge lifecycle.

Modality enum follows the BACEN COBV (Cobrança com Vencimento) spec — see bacen.github.io/pix-api for the upstream reference.

Shape of the object depends on modality:

  • For FIXED_VALUE_UNTIL_SPECIFIED_DATE and PERCENTAGE_UNTIL_SPECIFIED_DATE, provide discountFixedDate (array of items with daysActive and value). When multiple entries match the current day (i.e. their daysActive window has not yet expired), the entry with the largest discount wins.
  • For the four advance-day modalities (VALUE_PER_RUNNING_DAY_ADVANCE, VALUE_PER_BUSINESS_DAY_ADVANCE, PERCENTAGE_PER_RUNNING_DAY_ADVANCE, PERCENTAGE_PER_BUSINESS_DAY_ADVANCE), provide a single value.

Rounding. Computed discount and interest amounts are rounded to the nearest cent.

Array of objects

Additional info of the charge

enableCashbackPercentage
boolean

true to enable cashback and false to disable.

enableCashbackExclusivePercentage
boolean

true to enable fidelity cashback and false to disable.

subaccount
string

Pix key of the subaccount to receive the charge

Array of objects

This is the array that will configure how will be splitted the value of the charge

Responses

Request samples

Content type
application/json
Example
{
  • "correlationID": "9134e286-6f71-427a-bf00-241681624587",
  • "value": 100,
  • "comment": "good",
  • "customer": {
    },
  • "additionalInfo": [
    ]
}

Response samples

Content type
application/json
{
  • "charge": {
    }
}

charge refund

Endpoint to manage charge refunds

Get all refunds of a charge

Endpoint to get all refunds of a charge

Authorizations:
AppID
path Parameters
id
required
string
Examples:
  • cf4012c9-b2ac-484d-8121-deedd1c6d8af -
  • fe7834b4060c488a9b0f89811be5f5cf -

The correlation ID of the charge. You will need URI encoding if your correlation ID has characters outside the ASCII set or reserved characters (%, #, /).

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/charge/cf4012c9-b2ac-484d-8121-deedd1c6d8af/refund',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "refunds": [
    ]
}

Create a new refund for a charge

Endpoint to create a new refund for a charge

Authorizations:
AppID
path Parameters
id
required
string
Examples:
  • cf4012c9-b2ac-484d-8121-deedd1c6d8af -
  • fe7834b4060c488a9b0f89811be5f5cf -

The correlation ID of the charge. You will need URI encoding if your correlation ID has characters outside the ASCII set or reserved characters (%, #, /).

Request Body schema: application/json
required

Data to create a new refund for a charge

correlationID
required
string

Your correlation ID to keep track for this refund

value
number

Value in cents for this refund

comment
string <= 140

Comment for this refund. Maximum length of 140 characters.

Responses

Request samples

Content type
application/json
{
  • "correlationID": "a273e72c-9547-4c75-a213-3b0a2735b8d5",
  • "value": 100,
  • "comment": "Comentário do reembolso"
}

Response samples

Content type
application/json
{
  • "refund": {
    }
}

company

Endpoint to manage Company information

Get a Company

Authorizations:
AppID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/company',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "company": {
    }
}

customer

Endpoint to manage Customer

Get one customer

Authorizations:
AppID
path Parameters
id
required
string
Examples:
  • fe7834b4060c488a9b0f89811be5f5cf -
  • 123456789 -

Correlation ID or Tax ID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/customer/fe7834b4060c488a9b0f89811be5f5cf',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "customer": {
    }
}

Get a list of customers

Authorizations:
AppID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/customer',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "pageInfo": {
    },
  • "customers": {
    }
}

Create a new Customer

Endpoint to create a new Customer

Authorizations:
AppID
Request Body schema: application/json
required

Data to create a new customer

One of
name
required
string
email
string
phone
string
taxID
required
string
correlationID
string
object

Responses

Request samples

Content type
application/json
{
  • "name": "Dan",
  • "taxID": "31324227036",
  • "email": "email0@example.com",
  • "phone": "5511999999999",
  • "correlationID": "9134e286-6f71-427a-bf00-241681624586",
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "customer": {
    }
}

Update a Customer

Endpoint to update a Customer

Authorizations:
AppID
path Parameters
correlationID
required
string
Examples:
  • fe7834b4060c488a9b0f89811be5f5cf -

correlation ID

Request Body schema: application/json
required

Data to update a existent customer

name
string
email
string
phone
string
taxID
string
object

Responses

Request samples

Content type
application/json
{
  • "name": "Dan",
  • "email": "email0@example.com",
  • "phone": "5511999999999",
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "customer": {
    }
}

dispute

Endpoint to manage Dispute

Upload new evidence

Upload evidence files for dispute/med. \nOBS para obter esse o id da disputa, veja esse artigo https://developers.woovi.com/docs/disputa/how-add-new-evidence-in-dispute#1-obter-o-id-da-disputa

Authorizations:
AppID
Request Body schema: application/json
required
Array of objects

documents for upload

Array
url
string non-empty

Document url

correlationID
string

Id used by the client

description
string

Responses

Request samples

Content type
application/json
{
  • "documents": [
    ]
}

Response samples

Content type
application/json
{
  • "documents": [
    ]
}

Get one dispute

Authorizations:
AppID
path Parameters
id
required
string
Example: Ea9c291526ae54b4cb41d9909bdf6d792

The id must be the endToEndId of the transaction that originated the Dispute

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/dispute/Ea9c291526ae54b4cb41d9909bdf6d792',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "dispute": {
    }
}

Get a list of disputes

Authorizations:
AppID
query Parameters
start
string <date-time> (Start Date)
Example: start=2020-01-01T00:00:00Z

Start date used in the query. Complies with RFC 3339.

end
string <date-time> (End Date)
Example: end=2020-12-01T17:00:00Z

End date used in the query. Complies with RFC 3339.

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/dispute?start=2020-01-01T00%3A00%3A00Z&end=2020-12-01T17%3A00%3A00Z',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "pageInfo": {
    },
  • "disputes": [
    ]
}

funds recovery

Endpoints to manage funds recoveries (MED — Mecanismo Especial de Devolução).

A funds recovery lets you request the return of a Pix transaction sent from your account in case of scam or fraud. The Central Bank tracks the money path across Pix participants and opens refund solicitations on the accounts the funds went through.

These endpoints require the MED API feature enabled on your account. Contact our support to enable it.

Cancel a funds recovery (MED)

Endpoint to cancel a funds recovery (MED). The request does not need a body.

Only funds recoveries opened by your account that have not reached a terminal status (COMPLETED or CANCELLED) can be cancelled.

Authorizations:
AppID
path Parameters
id
required
string <uuid>
Example: 3e760cd5-39b2-45da-8ab6-b212cf205568

The dictId returned when the funds recovery was created

Responses

Request samples 

const http = require('https');

const options = {
  method: 'POST',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/funds-recovery/3e760cd5-39b2-45da-8ab6-b212cf205568/cancel',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "rootTransactionId": "E31680151202606101530AbCdEf12345",
  • "situationType": "SCAM",
  • "reportDetails": "Payment made to a fake seller. After the payment, the seller stopped responding and never delivered the product.",
  • "dictId": "3e760cd5-39b2-45da-8ab6-b212cf205568",
  • "status": "CANCELLED",
  • "direction": "SENT",
  • "reporterParticipant": "31680151",
  • "creationTime": "2026-06-11T00:30:00.000Z",
  • "lastModified": "2026-06-11T01:10:00.000Z",
  • "createdAt": "2026-06-11T00:30:00.000Z",
  • "updatedAt": "2026-06-11T01:10:00.000Z"
}

Get one funds recovery (MED)

Endpoint to get a funds recovery (MED). Use it to follow the progress of the funds recovery through the status and events fields.

Authorizations:
AppID
path Parameters
id
required
string <uuid>
Example: 3e760cd5-39b2-45da-8ab6-b212cf205568

The dictId returned when the funds recovery was created

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/funds-recovery/3e760cd5-39b2-45da-8ab6-b212cf205568',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "rootTransactionId": "E31680151202606101530AbCdEf12345",
  • "situationType": "SCAM",
  • "reportDetails": "Payment made to a fake seller. After the payment, the seller stopped responding and never delivered the product.",
  • "dictId": "3e760cd5-39b2-45da-8ab6-b212cf205568",
  • "status": "AWAITING_ANALYSIS",
  • "direction": "SENT",
  • "reporterParticipant": "31680151",
  • "creationTime": "2026-06-11T00:30:00.000Z",
  • "lastModified": "2026-06-11T00:35:00.000Z",
  • "events": [
    ],
  • "createdAt": "2026-06-11T00:30:00.000Z",
  • "updatedAt": "2026-06-11T00:35:00.000Z"
}

Open a funds recovery (MED)

Endpoint to open a funds recovery (MED) for a Pix transaction sent from your account.

Only one funds recovery can be opened per transaction. The transaction must have been sent from your account and cannot have been rejected.

Authorizations:
AppID
Request Body schema: application/json
required

Data to open a funds recovery

transactionEndToEndId
required
string

The endToEndId of the Pix transaction sent from your account that you want to recover

situationType
required
string
Enum: "SCAM" "ACCOUNT_TAKEOVER" "COERCION" "FRAUDULENT_ACCESS" "OTHER" "UNKNOWN"

The situation that motivated the funds recovery:

  • SCAM: scam (e.g. fake sale, fake invoice, social engineering)
  • ACCOUNT_TAKEOVER: account takeover
  • COERCION: coercion (e.g. kidnapping, extortion)
  • FRAUDULENT_ACCESS: fraudulent access to credentials
  • OTHER: other kind of fraud
  • UNKNOWN: unknown kind of fraud
details
required
string

Detailed description of what happened. The more context, the better for the analysis.

Responses

Request samples

Content type
application/json
{
  • "transactionEndToEndId": "E31680151202606101530AbCdEf12345",
  • "situationType": "SCAM",
  • "details": "Payment made to a fake seller. After the payment, the seller stopped responding and never delivered the product."
}

Response samples

Content type
application/json
{
  • "rootTransactionId": "E31680151202606101530AbCdEf12345",
  • "situationType": "SCAM",
  • "reportDetails": "Payment made to a fake seller. After the payment, the seller stopped responding and never delivered the product.",
  • "dictId": "3e760cd5-39b2-45da-8ab6-b212cf205568",
  • "status": "CREATED",
  • "direction": "SENT",
  • "reporterParticipant": "31680151",
  • "creationTime": "2026-06-11T00:30:00.000Z",
  • "lastModified": "2026-06-11T00:30:00.000Z",
  • "events": [ ],
  • "createdAt": "2026-06-11T00:30:00.000Z",
  • "updatedAt": "2026-06-11T00:30:00.000Z"
}

kyc

Endpoints for KYC onboarding

Create a KYC onboarding

Creates a new KYC onboarding for a merchant. Returns a link that should be sent to the merchant so they can fill in their registration data.

The API is idempotent by correlationID. If the same correlationID is sent again for the same company, the API returns the existing onboarding link (200 OK) instead of creating a new one.

The fields officialName, tradeName and representatives[].name are automatically populated via data enrichment when available. You do not need to send them in the request.

If redirectUrl is provided, the merchant is automatically redirected to that URL 5 seconds after completing the onboarding flow (terminal states: submitted, approved, or rejected). The redirectUrl is bound to the onboarding link at creation time and cannot be changed later — subsequent idempotent calls will return the original value.

Authorizations:
AppID
Request Body schema: application/json
required
taxID
required
string

CNPJ da empresa do merchant (com ou sem mascara)

correlationID
string

Identificador unico para idempotencia. Se nao informado, o CNPJ sera usado.

redirectUrl
string <uri>

URL para onde o merchant sera redirecionado apos concluir o onboarding. Quando informado, a pagina final do fluxo KYC redireciona automaticamente apos 5 segundos.

Array of objects (KycOnboardingRepresentative)

Socios/representantes da empresa

Responses

Request samples

Content type
application/json
Example
{
  • "taxID": "XX.XXX.XXX/0001-XX"
}

Response samples

Content type
application/json
{}

account limits

Endpoints to query account limits for a given bank account.

Get account limits

Retrieves the most recent account limits configured for a given bank account. Only the public-safe fields are returned; internal-only fields are stripped from the response.

Authorizations:
AppID
path Parameters
accountId
required
string
Examples:
  • 65f1c2e9a1b2c3d4e5f60718 -

Bank account identifier (ObjectId) for which limits should be returned

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/limits/65f1c2e9a1b2c3d4e5f60718',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "limits": {
    }
}

partner (request access)

Partners integrate affiliated companies.
They can register new companies, manage them, and earn money from them.

Get every affiliate company that is managed by you.

Authorizations:
AppID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/partner/affiliate',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "affiliates": [
    ],
  • "pageInfo": {
    }
}

Create a new application to some of your preregistration's company.

As a partner company, you can create a new application to some of your companies. The application should give access to our API to this companies, so they can use it too.

Authorizations:
AppID
Request Body schema: application/json
required

The request body to create a pre registration.

object
object (TaxIDObjectPayload)

Responses

Request samples

Content type
application/json
Example
{
  • "application": {
    },
  • "taxID": {
    }
}

Response samples

Content type
application/json
Example
{
  • "application": {
    }
}

Get an specific preregistration via taxID param.

Authorizations:
AppID
path Parameters
taxID
required
string
Examples:
  • 60151449000182 -

The raw tax ID from the preregistration that you want to get.

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/partner/company/60151449000182',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "preRegistration": {
    }
}

Get every preregistration that is managed by you.

Authorizations:
AppID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/partner/company',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "preRegistrations": [
    ],
  • "pageInfo": {
    }
}

Create a pre registration with a partner reference (your company)

As a partner company, you can create a new pre registration referencing your company as a partner.

Authorizations:
AppID
Request Body schema: application/json
required

The request body to create a pre registration.

object (PreRegistrationObject)
object (PreRegistrationUserObject)

Responses

Request samples

Content type
application/json
{
  • "preRegistration": {
    },
  • "user": {
    }
}

Response samples

Content type
application/json
{
  • "preRegistration": {
    },
  • "user": {
    }
}

payment (request access)

Endpoints to create and manage Pix payment requests. Supports three payment types:

1. Pix Key (PIX_KEY) - Pay directly to a Pix key (CPF, CNPJ, email, phone, or random key).

2. QR Code (QR_CODE) - Pay a Pix QR Code (BR Code). Send the raw QR Code string and the system will decode it, extract the destination and value automatically.

3. Manual (MANUAL) - Pay by providing the destination bank account details directly (holder, account, branch, PSP).

QR Code Payment Flow

To pay a QR Code, follow these steps:

  1. Create the payment - Call POST /api/v1/payment with type: "QR_CODE" and the qrCode field containing the BR Code string. The value is automatically extracted from the QR Code. You can optionally provide a value field to override it (for QR Codes without a fixed value).
  2. Review the response - The response includes the decoded payment details (destination, value, status CREATED).
  3. Approve the payment - Call POST /api/v1/payment/approve with the correlationID to execute the payment.
  4. Check the status - Call GET /api/v1/payment/{id} with the correlationID to verify the payment status and get transaction details.

Approve a Payment Request

Endpoint to approve a payment

Authorizations:
AppID
Request Body schema: application/json
required

Data to approve a payment request

correlationID
string

the correlation ID of the payment to be approved

Responses

Request samples

Content type
application/json
{
  • "correlationID": "payment1"
}

Response samples

Content type
application/json
{
  • "payment": {
    },
  • "transaction": {
    },
  • "destination": {
    }
}

Get one Payment

Authorizations:
AppID
path Parameters
id
required
string
Examples:
  • Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA== -
  • fe7834b4060c488a9b0f89811be5f5cf -

payment ID or correlation ID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/payment/Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA==',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "payment": {
    },
  • "transaction": {
    },
  • "destination": {
    }
}

Get a list of payments

Authorizations:
AppID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/payment',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "pageInfo": {
    },
  • "payments": {
    }
}

Create a Payment Request

Endpoint to request a payment. Supports four payment types: Pix Key (PIX_KEY), QR Code (QR_CODE), Manual (MANUAL), and Boleto (BOLETO).

For QR Code payments, the system decodes the BR Code string and extracts the destination and value automatically.

For Boleto payments, send type: "BOLETO" and the boletoBarcode. The amount, due date and beneficiary are resolved from the boleto, so value and destination are not sent in the body. Validate the barcode first with POST /api/v1/boleto/validate.

Set autoApprove: true to create and immediately approve the payment in a single call, returning the enriched response with transaction and destination data. Without this flag, the payment is created in CREATED status and can be approved later via POST /api/v1/payment/approve.

Authorizations:
AppID
Request Body schema: application/json
required

Data to create a payment request

One of
type
required
string
Enum: "PIX_KEY" "QR_CODE" "MANUAL" "BOLETO"

type of the payment

value
required
number

value of the requested payment in cents

destinationAlias
required
string

the pix key the payment should be sent to

destinationAliasType
required
string
Enum: "CPF" "CNPJ" "EMAIL" "PHONE" "RANDOM"

the type of the pix key the payment should be sent to

correlationID
required
string

a unique identifier for your payment

pixKeyEndToEndId
string

the end to end id of the pix key used for track pix key consultations

comment
string

the comment that will be sent alongside your payment

object

additional metadata for the payment (max 30 keys)

autoApprove
boolean

When true, creates and approves the payment in a single call returning the enriched response. Defaults to false.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "PIX_KEY",
  • "value": 100,
  • "destinationAlias": "c4249323-b4ca-43f2-8139-8232aab09b93",
  • "destinationAliasType": "RANDOM",
  • "comment": "payment comment",
  • "correlationID": "payment1",
  • "pixKeyEndToEndId": "E1234567890",
  • "metadata": {
    }
}

Response samples

Content type
application/json
Example
{
  • "payment": {
    }
}

pixKey

Endpoint to manage Pix Keys

Check data from a Pix key

Get data from a Pix key if it exists

Authorizations:
AppID
path Parameters
pixKey
required
string

The Pix key to check

Responses

Response samples

Content type
application/json
{
  • "pixKey": "string",
  • "type": "CPF",
  • "pixKeyEndToEndId": "string",
  • "owner": {
    }
}

Check data from a Pix key

Get data from a Pix key if it exists

Authorizations:
AppID
Request Body schema: application/json
required
pixKey
required
string

The Pix key to check

Responses

Request samples

Content type
application/json
{
  • "pixKey": "string"
}

Response samples

Content type
application/json
{
  • "pixKey": "string",
  • "type": "CPF",
  • "pixKeyEndToEndId": "string",
  • "owner": {
    }
}

Set a pix key as default

Set a pix key as default

Authorizations:
AppID
path Parameters
pixKey
required
string

The pix key to set as default

Responses

Response samples

Content type
application/json
{
  • "key": "string",
  • "type": "CPF",
  • "isDefault": true
}

Delete a Pix key

Deletes a specific Pix key, you cannot delete the default pix key

Authorizations:
AppID
path Parameters
pixKey
required
string

The Pix key to delete

Responses

Get all Pix keys

Retrieves a list of all Pix keys

Authorizations:
AppID
query Parameters
skip
number
limit
number

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/pix-keys?skip=SOME_NUMBER_VALUE&limit=SOME_NUMBER_VALUE',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "pixKeys": [
    ],
  • "account": {
    }
}

Create a new Pix key

Creates a new Pix key

Authorizations:
AppID
Request Body schema: application/json
required
key
required
string
type
required
string
Enum: "CNPJ" "EVP"

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "type": "CNPJ"
}

Response samples

Content type
application/json
{
  • "key": "string",
  • "type": "CPF",
  • "isDefault": true
}

Get tokens data

Get tokens data

Authorizations:
AppID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/pix-keys/tokens',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "tokens": 0,
  • "maxTokens": 0,
  • "nextRefresh": "string",
  • "tokensAfterRefresh": 0,
  • "refreshRate": 0
}

Get token bucket logs

Get a list of token bucket operation logs

Authorizations:
AppID
query Parameters
skip
number
limit
number
companyBankAccount
string

Filter logs by company bank account ID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/pix-keys/tokens/logs?skip=SOME_NUMBER_VALUE&limit=SOME_NUMBER_VALUE&companyBankAccount=SOME_STRING_VALUE',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "pageInfo": {
    },
  • "logs": [
    ]
}

pixQrCode

Endpoint to manage static QRCodes

Delete a Pix QrCode Static

Endpoint to delete a Pix QrCode Static

Authorizations:
AppID
path Parameters
id
required
string
Examples:
  • fe7834b4060c488a9b0f89811be5f5cf -

QrCode ID, correlationID or identifier

Responses

Request samples 

const http = require('https');

const options = {
  method: 'DELETE',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/qrcode-static/fe7834b4060c488a9b0f89811be5f5cf',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "status": "OK",
  • "id": "fe7834b4060c488a9b0f89811be5f5cf"
}

Get one Pix QrCode

Authorizations:
AppID
path Parameters
id
required
string
Examples:
  • Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA== -
  • fe7834b4060c488a9b0f89811be5f5cf -
  • zr7833b4060c488a9b0f89811 -

pixQrCode ID, correlation ID or emv identifier

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/qrcode-static/Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA==',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "pixQrCode": {
    }
}

Get a list of Pix QrCodes

Authorizations:
AppID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/qrcode-static',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "pageInfo": {
    },
  • "pixQrCodes": {}
}

Create a new Pix QrCode Static

Endpoint to create a new Pix QrCode Static

Authorizations:
AppID
Request Body schema: application/json
required

Data to create a new Pix QrCode Static

name
required
string

Name of this pix qrcode

correlationID
string

Your correlation ID to keep track of this qrcode

value
number

Value in cents of this qrcode

comment
string

Comment to be added in infoPagador

pixKey
string

The pix key that this qrcode is associated with

Responses

Request samples

Content type
application/json
{
  • "name": "my-qr-code",
  • "correlationID": "9134e286-6f71-427a-bf00-241681624586",
  • "value": 100,
  • "comment": "good"
}

Response samples

Content type
application/json
{}

transactions

Endpoint to manage Transactions

Get a Transaction

Authorizations:
AppID
path Parameters
id
required
string

you can use the transaction id from openpix or the endToEndId of transaction from bank

Responses

Response samples

Content type
application/json
{
  • "transaction": {
    }
}

Get a list of transactions

Authorizations:
AppID
query Parameters
start
string <date-time> (Start Date)
Example: start=2020-01-01T00:00:00Z

Start date used in the query. Complies with RFC 3339.

end
string <date-time> (End Date)
Example: end=2020-12-01T17:00:00Z

End date used in the query. Complies with RFC 3339.

charge
string
Example: charge=Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA

You can use the charge ID or correlation ID or transaction ID of charge to get a list of transactions related of this transaction

pixQrCode
string
Example: pixQrCode=Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA

You can use the QrCode static ID or correlation ID or identifier field of QrCode static to get a list of QrCode related of this transaction

withdrawal
string
Example: withdrawal=Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA

You can use the ID or EndToEndId of a withdrawal transaction to get all transactions related to the withdrawal

hasWebhook
boolean
Example: hasWebhook=true

Filter transactions by webhook delivery status. Use true to get only transactions that had a successful webhook delivery (HTTP 200), or false to get transactions without successful webhook delivery.

type
string
Enum: "PAYMENT" "WITHDRAW" "REFUND" "FEE" "INTERNAL_TRANSFER" "BALANCE_BLOCK" "BALANCE_UNBLOCK" "REVERSAL"
Example: type=REFUND

Filter transactions by type

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/transaction?start=2020-01-01T00%3A00%3A00Z&end=2020-12-01T17%3A00%3A00Z&charge=Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA&pixQrCode=Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA&withdrawal=Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA&hasWebhook=true&type=REFUND',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "pageInfo": {
    },
  • "transactions": {
    }
}

refund

Endpoint to manage Refunds

Get one refund

Authorizations:
AppID
path Parameters
id
required
string
Examples:
  • Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA== -
  • fe7834b4060c488a9b0f89811be5f5cf -

refund ID or correlation ID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/refund/Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA==',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "pixTransactionRefund": {
    }
}

Get a list of refunds

Authorizations:
AppID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/refund',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "pageInfo": {
    },
  • "refunds": [
    ]
}

Create a new refund

Endpoint to create a new refund for a customer

Authorizations:
AppID
Request Body schema: application/json
required

Data to create a new refund

value
number
transactionEndToEndId
string

Your transaction ID, or endToEnd ID, to keep track of this refund

correlationID
string

Your correlation ID, unique identifier refund

comment
string <= 140

Comment of this refund. Maximum length of 140 characters.

Responses

Request samples

Content type
application/json
{
  • "transactionEndToEndId": "9134e286-6f71-427a-bf00-241681624586",
  • "correlationID": "9134e286-6f71-427a-bf00-241681624586",
  • "value": 100,
  • "comment": "Comentário do reembolso"
}

Response samples

Content type
application/json
{
  • "refund": {
    }
}

psp

Endpoints to manage Payment Service Providers (PSPs) in the PIX ecosystem.

PSPs are financial institutions that can process PIX payments. Each PSP has unique identifiers like ISPB and COMPE codes used for identification and validation.

Get a list of PSPs (Payment Service Providers)

Authorizations:
AppID
query Parameters
ispb
string
Example: ispb=3030310

Filter PSPs by ISPB code

name
string
Example: name=brasil

Filter PSPs by name

compe
string
Example: compe=001

Filter PSPs by COMPE code

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/psp?ispb=3030310&name=brasil&compe=001',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "success": true,
  • "psps": [
    ]
}

receipt

Get a pdf document related to a payment transaction formated in a receipt style.

Get a PDF document related to a payment transaction formatted as a receipt by type (pix-in, pix-out or pix-refund).

Authorizations:
AppID
path Parameters
ReceiptType
required
string
Enum: "pix-in" "pix-out" "pix-refund"
Examples:
  • pix-in -
  • pix-out -
  • pix-refund -

The ReceiptType from the payment transaction to export.

EndToEndId
required
string
Examples:
  • E12345678202406201221abcdef12345 -

The EndToEndId from the payment transaction to export.

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/receipt/pix-in/E12345678202406201221abcdef12345',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "error": "string"
}

stablecoin

Endpoints for stablecoin deposits

Approve (settle) a stablecoin deposit

Approves a previously created stablecoin deposit identified by its correlationId, triggering the on-chain settlement (pay the stable qrcode) for the company's deposit.

The deposit moves to PROCESSING while settlement is in flight. The call is rejected with 400 when the deposit cannot be approved, e.g. it was already COMPLETED, it is already PROCESSING, there is no source account to pay it, or the provider quote/payment fails.

Requires the STABLECOIN_DEPOSIT_CREATE scope.

Authorizations:
AppID
Request Body schema: application/json
required
correlationId
required
string non-empty

The correlationId supplied when the deposit was created.

Responses

Request samples

Content type
application/json
{
  • "correlationId": "my-unique-id"
}

Response samples

Content type
application/json
{
  • "status": "PROCESSING",
  • "correlationId": "my-unique-id",
  • "depositId": "6650abc1234def567890aaaa"
}

Create a stablecoin deposit

Creates a stablecoin deposit (PIX-in to stable-out) for a company. The deposit converts a BRL amount (in cents) into the requested stablecoin on the chosen network and returns a quote with the applied fees.

The company must have a stable subaccount in CONFIRMED status (a completed KYB). Otherwise the request is rejected with a 400.

Not every asset is available on every network. The supported matrix is:

  • USDT: POLYGON, ETHEREUM, CELO, TRON
  • USDC: POLYGON, ETHEREUM, BASE, CELO
  • BRLA: POLYGON, ETHEREUM, BASE, CELO

If network is omitted it defaults to POLYGON. Sending an asset/network combination outside the matrix above returns a 400.

Idempotency is supported via correlationId.

Authorizations:
AppID
Request Body schema: application/json
required
value
required
number

Amount to deposit, in cents (BRL). Must be positive.

currency
required
string
Enum: "USDT" "USDC" "BRLA"

Stablecoin to receive.

network
string
Default: "POLYGON"
Enum: "POLYGON" "ETHEREUM" "BASE" "CELO" "TRON"

Network to receive the stablecoin on. Defaults to POLYGON. Must be supported for the chosen currency.

subAccountId
string

Stable subaccount id to use. Optional; resolved from the company when omitted.

correlationId
string

Unique identifier for idempotency. Optional.

destinationWalletAddress
string

Explicit destination wallet address for the stablecoin. Optional.

Responses

Request samples

Content type
application/json
Example
{
  • "value": 10000,
  • "currency": "USDT"
}

Response samples

Content type
application/json
{
  • "status": "PENDING",
  • "depositId": "6650...",
  • "correlationId": "my-unique-id",
  • "expiration": "2026-06-05T12:00:00.000Z",
  • "quote": {
    }
}

Get a stablecoin quote without creating a deposit

Returns a PIX (BRL) -> stablecoin quote for the given value and currency without creating a deposit. Use it to display the exact amount of stablecoin the customer would receive before confirming.

The quote is fetched from the provider and cached for 60 seconds.

Requires the STABLECOIN_DEPOSIT_CREATE scope.

Authorizations:
AppID
query Parameters
value
required
number >= 1
Example: value=10000

Amount to quote, in cents (BRL). Must be positive.

currency
string
Default: "USDT"
Enum: "USDT" "USDC" "BRLA"
Example: currency=USDT

Stablecoin to receive. Defaults to USDT.

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/stablecoin/quote?value=10000&currency=USDT',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "status": "ok",
  • "quote": {
    }
}

Get a stablecoin subaccount by id

Fetches a single stablecoin subaccount for the authenticated company by its provider subAccountId.

Returns 404 when no subaccount with that subAccountId exists for the company.

Requires the STABLECOIN_SUBACCOUNT_LIST scope.

Authorizations:
AppID
path Parameters
subAccountId
required
string non-empty

The provider subaccount id.

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "subAccount": {
    }
}

List a company's stablecoin subaccounts

Lists the authenticated company's stablecoin subaccounts, most recent first.

A subaccount is created when the company completes a KYB with the stablecoin provider. Use this endpoint to discover the subAccountId values available to the company.

Requires the STABLECOIN_SUBACCOUNT_LIST scope.

Authorizations:
AppID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/stablecoin/subaccount',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "status": "ok",
  • "subAccounts": [
    ]
}

Request a new stablecoin subaccount (KYB)

Requests the creation of a stablecoin subaccount for the authenticated company, reusing the KYC data already on the referenced account register.

Pass the company's accountRegisterId; the provider subaccount is created immediately and a StableSubAccount is persisted with status IN_REVIEW while the KYB is processed. When the KYB resolves, the merchant receives a STABLECOIN_SUBACCOUNT_CONFIRMED or STABLECOIN_SUBACCOUNT_REJECTED webhook.

The request is idempotent on accountRegisterId: a repeat call returns the existing subaccount (HTTP 200) instead of creating a duplicate. The first, creating call returns HTTP 201.

Requires the STABLECOIN_SUBACCOUNT_CREATE scope and the company STABLECOIN feature.

Authorizations:
AppID
Request Body schema: application/json
required
accountRegisterId
required
string

The account register id whose KYC data backs the KYB.

companyBankAccountId
string

Company bank account to associate with the subaccount. Defaults to the company's default bank account when omitted.

Responses

Request samples

Content type
application/json
Example
{
  • "accountRegisterId": "6650abc1234def567890aaaa"
}

Response samples

Content type
application/json
{
  • "subAccountId": "sub_01HZ...",
  • "status": "IN_REVIEW",
  • "correlationId": "3f1a2b3c-4d5e-6f70-8a9b-0c1d2e3f4a5b"
}

subaccount

Endpoint to manage sub accounts.

Withdraw from a Sub Account

Withdraw from a Sub Account and return the withdrawal transaction information

Authorizations:
AppID
path Parameters
id
required
string
Example: destination@test.com

pix key registered to the subaccount

Request Body schema: application/json
required

Data to make a withdraw partial

value
number

Value of the withdrawal in cents if want to make a partial withdrawal

Responses

Request samples

Content type
application/json
{
  • "value": 1000
}

Response samples

Content type
application/json
{
  • "transaction": {
    }
}

Delete a Sub Account

Deletes a Sub Account if it has no remaining balance

Authorizations:
AppID
path Parameters
id
required
string
Example: destination@test.com

Pix key registered to the subaccount

Responses

Request samples 

const http = require('https');

const options = {
  method: 'DELETE',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/subaccount/destination@test.com',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "status": "OK",
  • "pixKey": "destination@test.com"
}

Get subaccount details

Authorizations:
AppID
path Parameters
id
required
string
Examples:
  • c4249323-b4ca-43f2-8139-8232aab09b93 -

pix key registered to the subaccount

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/subaccount/c4249323-b4ca-43f2-8139-8232aab09b93',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "SubAccount": {
    }
}

Get a list of subaccounts

Authorizations:
AppID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/subaccount',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "subAccounts": [
    ],
  • "pageInfo": {
    }
}

Create a subaccount

Authorizations:
AppID
Request Body schema: application/json
required

Data to create a new subAccount or retrieve existing one

pixKey
string

The pix key for the sub account

name
string

Name of the sub account

Responses

Request samples

Content type
application/json
{
  • "pixKey": "9134e286-6f71-427a-bf00-241681624587",
  • "name": "Test Account"
}

Response samples

Content type
application/json
{
  • "SubAccount": {
    }
}

Credit subaccount

Transfers the amount from the main account to the subaccount.

Authorizations:
AppID
path Parameters
id
required
string
Example: subaccount@test.com

Pix key registered to the subaccount

Request Body schema: application/json
required
value
required
number

Amount to credit to the account

description
string

Optional description for the credit operation

Responses

Request samples

Content type
application/json
{
  • "value": 100,
  • "description": "Monthly deposit"
}

Response samples

Content type
application/json
{
  • "pixKey": "subaccount@test.com",
  • "value": 100,
  • "description": "Monthly deposit",
  • "success": "Sub-account withdrawal has been successfully credited, 100"
}

Debit subaccount

Transfers the amount from the subaccount to the main account.

Authorizations:
AppID
path Parameters
id
required
string
Example: subaccount@test.com

Pix key registered to the subaccount

Request Body schema: application/json
required
value
required
number

Amount to debit from the account

description
string

Optional description for the debit operation

Responses

Request samples

Content type
application/json
{
  • "value": 50,
  • "description": "Monthly payment"
}

Response samples

Content type
application/json
{
  • "pixKey": "subaccount@test.com",
  • "value": 50,
  • "description": "Monthly payment",
  • "success": "Sub-account withdrawal has been successfully debited, 50"
}

Transfer between subaccounts

Transfer between subaccounts

Authorizations:
AppID
Request Body schema: application/json
required

Data to make a new transfer between subaccounts

value
required
number

The value of the transfer in cents

fromPixKey
required
string

The transfer origin pix key

fromPixKeyType
required
string
Enum: "CPF" "CNPJ" "EMAIL" "PHONE" "RANDOM"

The transfer origin pix key type

toPixKey
required
string

The transfer destination pix key

toPixKeyType
required
string
Enum: "CPF" "CNPJ" "EMAIL" "PHONE" "RANDOM"

The transfer destination pix key type

correlationID
string

Your correlation ID to keep track of this transfer

Responses

Request samples

Content type
application/json
{
  • "value": 65,
  • "fromPixKey": "c4249323-b4ca-43f2-8139-874baab09b93",
  • "fromPixKeyType": "RANDOM",
  • "toPixKey": "3143da48-2bc7-49a4-89bd-4e22f73bfb0c",
  • "toPixKeyType": "RANDOM"
}

Response samples

Content type
application/json
{
  • "value": 65,
  • "destinationSubaccount": {
    },
  • "originSubaccount": {
    }
}

Get Sub Account statement

Returns the ledger entries (statement) for a specific subaccount.

Authorizations:
AppID
path Parameters
id
required
string
Example: subaccount@test.com

Pix key registered to the subaccount

query Parameters
skip
integer >= 0

Number of entries to skip for pagination

limit
integer >= 1
Example: limit=20

Maximum number of entries to return

start
string <date-time>
Example: start=2023-01-01T00:00:00.000Z

Start date for filtering entries (ISO 8601 format)

end
string <date-time>
Example: end=2023-12-31T23:59:59.999Z

End date for filtering entries (ISO 8601 format)

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/subaccount/subaccount@test.com/statement?skip=0&limit=20&start=2023-01-01T00%3A00%3A00.000Z&end=2023-12-31T23%3A59%3A59.999Z',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
[
  • {
    }
]

subscription

Endpoint to manage Subscriptions

Get one installment

Authorizations:
AppID
path Parameters
id
required
string
Example: UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM=

The globalID of the installment or the endToEndId from transaction.

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/installments/UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM=',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "installment": {
    }
}

Get a list of installments by subscription

Authorizations:
AppID
path Parameters
id
required
string
Example: UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM=

The globalID of the subscription.

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/subscriptions/UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM=/installments',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "installments": [
    ],
  • "pageInfo": {
    }
}

Cancel an Subscription

Authorizations:
AppID
path Parameters
id
required
string
Example: UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM=

The globalID or correlationID of the subscription.

Responses

Request samples 

const http = require('https');

const options = {
  method: 'PUT',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/subscriptions/UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM=/cancel',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{ }

Get one subscription

Authorizations:
AppID
path Parameters
id
required
string
Example: UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM=

The globalID or correlationID of the subscription.

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/subscriptions/UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM=',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "subscription": {
    }
}

Get a list of subscriptions

Authorizations:
AppID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/subscriptions',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "pageInfo": {
    }
}

Create a new Subscription

Endpoint to create a new Subcription

Authorizations:
AppID
Request Body schema: application/json
required

Data to create a new Subscription

required
object

Customer of this subscription

value
required
number

Value in cents of this subscription

name
string

Name of the subscription

comment
string

Comment to be show in QR Code

number or string
frequency
string
Enum: "WEEKLY" "MONTHLY" "BIMONTHLY" "QUARTERLY" "SEMIANNUALLY" "ANNUALLY"

Frequency of the subscription — the interval between charges (defaults to MONTHLY when omitted):

  • WEEKLY: every week
  • MONTHLY: every month
  • BIMONTHLY: every 2 months
  • QUARTERLY: every 3 months (trimestral)
  • SEMIANNUALLY: every 6 months
  • ANNUALLY: every 12 months For Pix Automático (type: PIX_RECURRING), only the frequencies allowed by the Central Bank apply: WEEKLY, MONTHLY, QUARTERLY, SEMIANNUALLY and ANNUALLY (BIMONTHLY is not supported).
type
required
string
Enum: "PIX_RECURRING" "RECURRENT"

Type of the subscription

dayDue
number >= 3
Default: 7

Days that the charge will take to expire from the generation day.

installmentCount
number

number of installments (optional)

correlationID
required
string

Your correlation ID to keep track of this subscription

Array of objects
object

Pix automatic options

chargeType
string
Enum: "DYNAMIC" "OVERDUE" "BOLETO"

Charge method used for each charge generated by the subscription (defaults to DYNAMIC when omitted):

  • DYNAMIC: a standard Pix charge.
  • OVERDUE: a Pix charge with a due date (supports interest and fine).
  • BOLETO: each charge is issued as a boleto, which can also be paid through its Pix QR Code. Requires the boleto feature enabled for your account — talk to our support. Only applies to type: RECURRENT subscriptions; it is ignored for Pix Automático (type: PIX_RECURRING).

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Pix Automático",
  • "value": 100,
  • "customer": {
    },
  • "correlationID": "My-UniqueID",
  • "comment": "Comentários",
  • "frequency": "WEEKLY",
  • "type": "PIX_RECURRING",
  • "pixRecurringOptions": {
    },
  • "dayGenerateCharge": 25,
  • "dayDue": 3
}

Response samples

Content type
application/json
{
  • "subscription": {
    }
}

Update the value of the next installments of the subscription. It is only possible if pix automatic accepts dynamic value.

Authorizations:
AppID
path Parameters
id
required
string
Example: UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM=

The globalID or correlationID of the subscription.

Responses

Request samples 

const http = require('https');

const options = {
  method: 'PUT',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/subscriptions/UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM=/value',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{ }

CobR

Endpoint to manually create and retry CobR from Pix Automatic

Create a new Cobr Manually

Create a new Cobr Manually.

Authorizations:
AppID
path Parameters
id
required
string
Example: UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM=

The globalID of the installment.

Request Body schema: application/json
optional

Data to create a new Cobr

value
number

Valor da cobrança (Opcional)

Responses

Request samples

Content type
application/json
{
  • "value": 0
}

Response samples

Content type
application/json
{ }

Create a new Retry Manually

Create a new Retry Manually.

Authorizations:
AppID
path Parameters
id
required
string
Example: UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM=

The globalID of the installment.

Request Body schema: application/json
optional

Data to create a new Cobr

value
number

Valor da cobrança (Opcional)

Responses

Request samples

Content type
application/json
{
  • "value": 0
}

Response samples

Content type
application/json
{ }

transfer (request access)

Endpoint to transfer values between accounts.

Create a Transfer

Endpoint to to transfer values between accounts

Authorizations:
AppID
Request Body schema: application/json
required

Data to create a transfer

value
number

value of the transfer in cents

fromPixKey
string

the pix key of the account the value of the transfer will come out from

toPixKey
string

the pix key of the account the value of the transfer will go to

correlationID
string

your correlation ID to keep track of this transfer

Responses

Request samples

Content type
application/json
{
  • "value": 100,
  • "fromPixKey": "from@openpix.com.br",
  • "toPixKey": "to@openpix.com.br",
  • "correlationID": "123e4567-e89b-12d3-a456-426614174000"
}

Response samples

Content type
application/json
{
  • "transaction": {
    }
}

webhook

Endpoint to manage Webhooks

Delete a Webhook

Endpoint to delete a Webhook

Authorizations:
AppID
path Parameters
id
required
string
Examples:
  • Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA== -
  • fe7834b4060c488a9b0f89811be5f5cf -

webhook ID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'DELETE',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/webhook/Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA==',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "status": "string"
}

Get a list of webhooks

Authorizations:
AppID
query Parameters
url
string
Example: url=https://mycompany.com.br/webhook

You can use the url to filter all webhooks

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/webhook?url=https%3A%2F%2Fmycompany.com.br%2Fwebhook',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "pageInfo": {
    },
  • "webhooks": [
    ]
}

Create a new Webhook

Endpoint to create a new Webhook

Authorizations:
AppID
Request Body schema: application/json
required

Data to create a new webhook

object (WebhookPayload)
name
string
event
string (WebhookEventEnum)
Enum: "OPENPIX:CHARGE_CREATED" "OPENPIX:CHARGE_COMPLETED" "OPENPIX:CHARGE_EXPIRED" "OPENPIX:CHARGE_COMPLETED_NOT_SAME_CUSTOMER_PAYER" "OPENPIX:TRANSACTION_RECEIVED" "OPENPIX:TRANSACTION_REFUND_RECEIVED" "PIX_TRANSACTION_REFUND_RECEIVED_CONFIRMED" "PIX_TRANSACTION_REFUND_SENT_CONFIRMED" "PIX_TRANSACTION_REFUND_RECEIVED_REJECTED" "PIX_TRANSACTION_REFUND_SENT_REJECTED" "OPENPIX:MOVEMENT_CONFIRMED" "OPENPIX:MOVEMENT_FAILED" "OPENPIX:MOVEMENT_REMOVED" "OPENPIX:DISPUTE_CREATED" "OPENPIX:DISPUTE_ACCEPTED" "OPENPIX:DISPUTE_REJECTED" "OPENPIX:DISPUTE_CANCELED" "ACCOUNT_REGISTER_APPROVED" "ACCOUNT_REGISTER_REJECTED" "ACCOUNT_REGISTER_PENDING" "PIX_AUTOMATIC_APPROVED" "PIX_AUTOMATIC_REJECTED" "PIX_AUTOMATIC_COBR_CREATED" "PIX_AUTOMATIC_COBR_APPROVED" "PIX_AUTOMATIC_COBR_REJECTED" "PIX_AUTOMATIC_COBR_TRY_REJECTED" "PIX_AUTOMATIC_COBR_TRY_REQUESTED" "PIX_AUTOMATIC_COBR_COMPLETED"

Available events to register a webhook to listen to. If no one selected anyone the default event will be OPENPIX:TRANSACTION_RECEIVED.

  • OPENPIX:CHARGE_CREATED - New charge created

  • OPENPIX:CHARGE_COMPLETED - Charge completed is when a charge is fully paid

  • OPENPIX:CHARGE_EXPIRED - Charge expired is when a charge is not fully paid and expired

  • OPENPIX:TRANSACTION_RECEIVED - New PIX transaction received

  • OPENPIX:TRANSACTION_REFUND_RECEIVED - New PIX transaction refund received or refunded

  • PIX_TRANSACTION_REFUND_RECEIVED_CONFIRMED - Pix transaction refund received confirmed

  • PIX_TRANSACTION_REFUND_SENT_CONFIRMED - Pix transaction refund sent confirmed

  • PIX_TRANSACTION_REFUND_RECEIVED_REJECTED - Pix transaction refund received rejected

  • PIX_TRANSACTION_REFUND_SENT_REJECTED - Pix transaction refund sent rejected

  • OPENPIX:MOVEMENT_CONFIRMED - Payment confirmed is when the pix transaction related to the payment gets confirmed

  • OPENPIX:MOVEMENT_FAILED - Payment failed is when the payment gets approved and a error occurs

  • OPENPIX:MOVEMENT_REMOVED - Payment was removed by a user

  • OPENPIX:MOVEMENT_CONFIRMED - Movement confirmed

  • OPENPIX:MOVEMENT_FAILED - Movement failed

  • OPENPIX:MOVEMENT_REMOVED - Movement removed

  • OPENPIX:DISPUTE_CREATED - Dispute created

  • OPENPIX:DISPUTE_ACCEPTED - Dispute accepted

  • OPENPIX:DISPUTE_REJECTED - Dispute rejected

  • OPENPIX:DISPUTE_CANCELED - Dispute canceled

  • ACCOUNT_REGISTER_APPROVED - Account register approved

  • ACCOUNT_REGISTER_REJECTED - Account register rejected

  • ACCOUNT_REGISTER_PENDING - Account register pending

  • PIX_AUTOMATIC_APPROVED - Pix Automatic approved

  • PIX_AUTOMATIC_REJECTED - Pix Automatic rejected

  • PIX_AUTOMATIC_COBR_CREATED - Pix Automatic cobr created

  • PIX_AUTOMATIC_COBR_APPROVED - Pix Automatic cobr approved

  • PIX_AUTOMATIC_COBR_REJECTED - Pix Automatic cobr rejected

  • PIX_AUTOMATIC_COBR_COMPLETED - Pix Automatic cobr completed

  • PIX_AUTOMATIC_COBR_TRY_REJECTED - Pix Automatic cobr try rejected

  • PIX_AUTOMATIC_COBR_TRY_REQUESTED - Pix Automatic cobr try requested

url
string
authorization
string
isActive
boolean

Responses

Callbacks

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "webhook": {
    }
}

Callback payload samples

Callback
Content type
application/json
{
  • "charge": {
    },
  • "pix": {
    },
  • "pixQrCode": null
}

Get a list of webhook events

Authorizations:
AppID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/webhook/events',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "events": [
    ]
}

Get a list of webhook IPs

Authorizations:
AppID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/webhook/ips',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "ips": [
    ]
}

decode

Parse EMV (PIX) QR code and optionally resolve COB/REC locations

Authorizations:
AppID
Request Body schema: application/json
required
emv
required
string

Raw EMV / PIX QR payload (text)

Responses

Request samples

Content type
application/json
{
  • "emv": "00020126780014br.gov.bcb.pix0136f4c6089a-bfde-4c00-a2d9-9eaa584b02190216CobrancaEstatica5204000053039865406546.285802BR5903Pix6008BRASILIA6229052584767c56c2ab4e65b6670de2a80950014br.gov.bcb.pix2573qr-h.sandbox.pix.bcb.gov.br/rest/api/rec/4b62d4a088fe4f51bcb4c64cf078869163044486"
}

Response samples

Content type
application/json
Example
{
  • "emv": {
    },
  • "cobLocation": null,
  • "recLocation": {
    }
}

invoice

Cancel an invoice

Authorizations:
AppID
path Parameters
correlationID
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Get invoices

Authorizations:
AppID
query Parameters
start
string
Example: start=2021-01-01
end
string
Example: end=2021-01-01
skip
number
limit
number
Example: limit=100

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/invoice?start=2021-01-01&end=2021-01-01&skip=0&limit=100',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "invoices": [
    ]
}

Create a new invoice

Authorizations:
AppID
Request Body schema: application/json
required
One of
description
string
billingDate
required
string <date-time>
correlationID
required
string
charge
string
value
required
number
customerId
string
object

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "billingDate": "2019-08-24T14:15:22Z",
  • "correlationID": "string",
  • "charge": "string",
  • "value": 0,
  • "customerId": "string",
  • "customer": {
    }
}

Response samples

Content type
application/json
{
  • "invoice": {
    }
}

Upload the NFe.io A1 certificate for the invoice integration

Uploads the company's NFe.io A1 certificate (base64-encoded pkcs12) to the configured NFEIO integration. The response returns only the resulting integration status and never echoes the certificate, passphrase or credentials.

Authorizations:
AppID
Request Body schema: application/json
required
pcks12
required
string <byte>

The A1 certificate (pkcs12) encoded as a base64 string

passphrase
required
string

The certificate password

test
boolean

If true, the certificate is not uploaded to NFe.io (validation and upload are skipped)

Responses

Request samples

Content type
application/json
{
  • "pcks12": "string",
  • "passphrase": "string",
  • "test": true
}

Response samples

Content type
application/json
{
  • "integration": {
    }
}

Get the NFe.io integration status and config for the authenticated company

Authorizations:
AppID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/invoice/integration',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "integration": {
    }
}

Activate or deactivate the NFe.io integration for the authenticated company

Authorizations:
AppID
Request Body schema: application/json
required
isActive
required
boolean

Responses

Request samples

Content type
application/json
{
  • "isActive": true
}

Response samples

Content type
application/json
{
  • "integration": {
    }
}

Create or upsert the NFe.io integration for the authenticated company

Upserts the NFe.io integration for the authenticated company and sets its tax fields. Optionally activates it (only allowed once configured).

Authorizations:
AppID
Request Body schema: application/json
optional
cityServiceCode
string
municipalSubscription
string
rpsNumber
string
specialTax
string
taxRegime
string
federalTaxDetermination
string
municipalTaxDetermination
string
isPortalNacional
boolean
isActive
boolean

Responses

Request samples

Content type
application/json
{
  • "cityServiceCode": "string",
  • "municipalSubscription": "string",
  • "rpsNumber": "string",
  • "specialTax": "string",
  • "taxRegime": "string",
  • "federalTaxDetermination": "string",
  • "municipalTaxDetermination": "string",
  • "isPortalNacional": true,
  • "isActive": true
}

Response samples

Content type
application/json
{
  • "integration": {
    }
}

Update the tax fields of the invoice integration

Updates the tax configuration of the authenticated company's existing NFEIO integration (city service code, municipal subscription, rps number, special tax, tax regime, legal nature and tax determination fields). The integration must already exist; otherwise a 404 is returned. The response never echoes credentials.

Authorizations:
AppID
Request Body schema: application/json
required
cityServiceCode
string
municipalSubscription
string
rpsNumber
string
specialTax
string
taxRegime
string
legalNature
string
federalTaxDetermination
string
municipalTaxDetermination
string
isPortalNacional
boolean

Responses

Request samples

Content type
application/json
{
  • "cityServiceCode": "string",
  • "municipalSubscription": "string",
  • "rpsNumber": "string",
  • "specialTax": "string",
  • "taxRegime": "string",
  • "legalNature": "string",
  • "federalTaxDetermination": "string",
  • "municipalTaxDetermination": "string",
  • "isPortalNacional": true
}

Response samples

Content type
application/json
{
  • "integration": { }
}

Issue a NFe.io test invoice for the invoice integration

Issues a test NFe.io invoice for the authenticated company's NFEIO integration. This is the bootstrap step that moves the integration to VALIDATING; once NFe.io confirms the test note via webhook the integration becomes CONFIGURED and active, which unblocks real invoice issuance. A configured integration can no longer issue test invoices.

Authorizations:
AppID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'POST',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/invoice/integration/test',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
{
  • "invoice": {
    },
  • "integration": {
    }
}

Get invoice PDF document

Authorizations:
AppID
path Parameters
correlationID
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "You need feature Invoice to access this endpoint"
}

Get invoice XML document

Authorizations:
AppID
path Parameters
correlationID
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "You need feature Invoice to access this endpoint"
}

statement

Get statement by company

Retrieves the statement/ledger entries for a company's bank account

Authorizations:
AppID
query Parameters
start
string <date-time> (Start Date)
Example: start=2020-01-01T00:00:00Z

Start date used in the query. Complies with RFC 3339.

end
string <date-time> (End Date)
Example: end=2020-12-01T17:00:00Z

End date used in the query. Complies with RFC 3339.

skip
number
limit
number

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.openpix.com.br',
  port: null,
  path: '/api/v1/statement?start=2020-01-01T00%3A00%3A00Z&end=2020-12-01T17%3A00%3A00Z&skip=SOME_NUMBER_VALUE&limit=SOME_NUMBER_VALUE',
  headers: {
    Authorization: '{APP_ID}'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Response samples

Content type
application/json
[
  • {
    }
]