Pular para o conteúdo principal
API docs by Redocly

Woovi (1.0.0)

Download OpenAPI specification:Download

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

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

👉 https://api.woovi.com/

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.woovi.com',
  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.woovi.com',
  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

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.woovi.com',
  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.woovi.com',
  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
id
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
id
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.woovi.com',
  port: null,
  path: '/api/v1/account-register/6fe18d8e-5009-4f57-8f1d-5b084b6b83ac',
  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"
}

anticipation

Endpoints to integrate the Anticipation product: register beneficiaries and sync their advanceable balances from an ERP/payroll.

Approve an anticipation request

Approves a PENDING request and triggers the Pix Out to the beneficiary. Idempotent: re-approving an already-approved request returns 200 with the current state; a rejected/terminal one returns 409. Requires the anticipation.request.approve scope.

Authorizations:
AppID
path Parameters
id
required
string

Anticipation request id.

Responses

Response samples

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

Bulk-sync beneficiary balances

Absolute set of availableAmount/maxAdvanceableAmount for up to 1000 beneficiaries in one call (nightly payroll sync). Returns a per-item report so partial failures can be reconciled.

Authorizations:
AppID
Request Body schema: application/json
required
required
Array of objects [ 1 .. 1000 ] items
Array ([ 1 .. 1000 ] items)
taxID
required
string

Beneficiary payout key (CPF or CNPJ).

availableAmount
required
integer >= 0

Available balance, in cents.

maxAdvanceableAmount
required
integer >= 0

Advanceable limit, in cents. Cannot exceed availableAmount.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "processed": 0,
  • "succeeded": 0,
  • "failed": 0,
  • "results": [
    ]
}

Activate a beneficiary

Reactivates a beneficiary previously deactivated.

Authorizations:
AppID
path Parameters
taxID
required
string

Payout key (CPF or CNPJ), with or without mask.

Responses

Response samples

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

Deactivate a beneficiary

Deactivates a beneficiary; blocks new anticipations and app login.

Authorizations:
AppID
path Parameters
taxID
required
string

Payout key (CPF or CNPJ), with or without mask.

Responses

Response samples

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

Register a beneficiary

Registers a beneficiary bound to the company resolved from the app_id. Idempotent on the payout key: send ?return_existing=true to get the existing beneficiary (200) instead of a 409.

Authorizations:
AppID
query Parameters
return_existing
boolean

When true, an already-existing beneficiary is returned with 200 instead of a 409.

Request Body schema: application/json
required
name
required
string [ 2 .. 120 ] characters

Beneficiary name.

taxID
required
string

Payout key (CPF or CNPJ), with or without mask.

cpf
string or null

The person's CPF. Required when taxID is a CNPJ.

notifyEmail
string or null <email>

Email used for notifications.

notifyPhone
string or null

Phone used for notifications.

availableAmount
integer or null >= 0

Available balance, in cents.

maxAdvanceableAmount
integer or null >= 0

Advanceable limit, in cents.

autoApprove
boolean or null

Per-beneficiary override of the company auto-approval.

feeDestinationAccountId
string or null

Fee destination account (overrides the company setting).

paymentDaysOverride
Array of integers or null[ items [ 1 .. 31 ] ]

Per-beneficiary payment days (1-31).

object or null

Per-beneficiary rolling frequency window.

correlationID
string or null

Your correlation ID, echoed back in the response.

Responses

Request samples

Content type
application/json
{
  • "name": "João da Silva",
  • "taxID": "12345678909",
  • "notifyEmail": "[email protected]",
  • "notifyPhone": "+5511999999999",
  • "availableAmount": 500000,
  • "maxAdvanceableAmount": 350000,
  • "correlationID": "erp-benef-42"
}

Response samples

Content type
application/json
{
  • "beneficiary": {
    },
  • "correlationID": "string"
}

List anticipation requests

Lists the company's anticipation requests. Poll ?status=PENDING to discover requests awaiting your approval before settlement. Requires the anticipation.request.read scope.

Authorizations:
AppID
query Parameters
status
string
Enum: "PENDING" "PROCESSING" "CONFIRMED" "CANCELED" "PAID" "OVERDUE" "FAILED"

Filter by status.

limit
integer

Max items to return (default 100, capped at 1000).

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.woovi.com',
  port: null,
  path: '/api/v1/anticipation?status=SOME_STRING_VALUE&limit=SOME_INTEGER_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
{
  • "anticipations": [
    ],
  • "count": 1
}

Reject an anticipation request

Rejects a PENDING request (releases the reserved cycle limit). Idempotent: re-rejecting a canceled request returns 200; an approved/terminal one returns 409. Requires the anticipation.request.approve scope.

Authorizations:
AppID
path Parameters
id
required
string

Anticipation request id.

Request Body schema: application/json
optional
reason
string

Optional rejection reason (audited).

Responses

Request samples

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

Response samples

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

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.woovi.com',
  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.

List boleto transactions

Lists the boleto transactions of your company, most recent first, so you can reconcile boleto receivables and payments against your own records.

A transaction is either a BOLETO_IN — a boleto your payer paid — or a BOLETO_OUT — a boleto your company paid. All monetary values are in cents.

value is the amount that actually moved, which for a boleto paid after the due date is above the emitted amount in charge.value because of interest and fine. finesValue and interestsValue split that difference, as charged by the bank, so you can reconcile an overdue boleto without recomputing it from the charge settings. Each is absent when there was none, so a boleto paid on time carries neither.

Two independent date ranges are offered because they answer different questions: start/end filter by when the transaction was created, and settledStart/settledEnd by when Woovi credited the amount to your account. Both dates come back on every item.

Requires the BOLETO_TRANSACTION_GET_LIST scope on the application.

Authorizations:
AppID
query Parameters
type
string
Enum: "BOLETO_IN" "BOLETO_OUT"

Only transactions of this type.

status
string
Enum: "CREATED" "PROCESSING" "PENDING" "CONFIRMED" "REJECTED"

Only transactions in this status.

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

Only transactions created from this date on.

end
string <date-time>

Only transactions created up to this date.

settledStart
string <date-time>

Only transactions settled from this date on.

settledEnd
string <date-time>

Only transactions settled up to this date.

skip
integer <= 10000
Default: 0

Rows to skip. Capped at 10000 — past that, narrow the window with the date filters instead of paginating deeper.

limit
integer <= 100
Default: 100

Rows to return.

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.woovi.com',
  port: null,
  path: '/api/v1/boleto-transaction?type=SOME_STRING_VALUE&status=SOME_STRING_VALUE&start=2026-07-01T00%3A00%3A00.000Z&end=SOME_STRING_VALUE&settledStart=SOME_STRING_VALUE&settledEnd=SOME_STRING_VALUE&skip=SOME_INTEGER_VALUE&limit=SOME_INTEGER_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
{
  • "status": "OK",
  • "pageInfo": {
    },
  • "boletoTransactions": [
    ]
}

Get a boleto transaction

Returns one boleto transaction of your company.

The id is the boletoTransactionID delivered in the BOLETO_SETTLED webhook, so you can confirm a settlement you were notified about.

Requires the BOLETO_TRANSACTION_GET scope on the application.

Authorizations:
AppID
path Parameters
boletoTransactionID
required
string
Example: btx_019fa55beec9775faf8a069d64dcde54

The boleto transaction id, as delivered in the webhook.

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.woovi.com',
  port: null,
  path: '/api/v1/boleto-transaction/btx_019fa55beec9775faf8a069d64dcde54',
  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
{
  • "boletoTransaction": {
    }
}

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.woovi.com',
  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.woovi.com',
  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.woovi.com',
  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.woovi.com',
  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.woovi.com',
  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.woovi.com',
  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.

Split

You can split the value of a charge across other accounts by sending the splits array in the request body. Each item accepts:

  • value: amount in cents that will be split to the destination.
  • pixKey: Pix key of the account that will receive this split.
  • splitType: how the split is processed — one of SPLIT_INTERNAL_TRANSFER, SPLIT_SUB_ACCOUNT or SPLIT_PARTNER. See how each split type is processed.

See the Charge with Split Internal Transfer and Charge with Split Subaccounts request body examples below for the full payload shape.

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)
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.woovi.com',
  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.woovi.com',
  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.woovi.com',
  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": {
    }
}

Update a Customer

Endpoint to update a Customer

Authorizations:
AppID
path Parameters
id
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": "[email protected]",
  • "phone": "5511999999999",
  • "address": {
    }
}

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.woovi.com',
  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": "[email protected]",
  • "phone": "5511999999999",
  • "correlationID": "9134e286-6f71-427a-bf00-241681624586",
  • "address": {
    }
}

Response samples

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

dispute

Endpoint to manage Dispute

Upload new evidence

Upload evidence files for a dispute (MED).

How to get the dispute id

Authorizations:
AppID
path Parameters
id
required
string

id of the dispute the evidence belongs to

Request Body schema: application/json
required
Array of objects

documents for upload

Array
url
string non-empty

Public url to download the document from. Send either url or fileId, not both.

fileId
string non-empty

Id of a file previously uploaded to POST /api/v1/files with purpose DISPUTE_EVIDENCE. Send either url or fileId, not both. Requires the DISPUTE_EVIDENCE_FILE_ID feature.

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.woovi.com',
  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.woovi.com',
  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": [
    ]
}

file

Endpoint to upload files that other Woovi APIs consume, such as the evidence of a dispute.

Upload a file

Uploads a file and returns its metadata with a pre-signed download URL. The file is sent as multipart/form-data on the file field, together with the purpose that describes what the file is for.

Send exactly one file per request, of one of the supported content types, up to 10 MiB (10485760 bytes).

When you send a correlationID, repeating the request with the same correlationID and purpose returns the file already stored (200) instead of uploading a second copy, so the request is safe to retry. Without a correlationID one is generated for you and every call stores a new file.

The url in the response is temporary and expires at urlExpiresAt; ask for the file again to get a fresh one.

Authorizations:
AppID
Request Body schema: multipart/form-data
required
file
required
string <binary>

The file itself. Its content type must be one of application/pdf, image/png, image/jpeg or image/webp, and its leading bytes must match the declared content type.

purpose
required
string (FilePurpose)
Value: "DISPUTE_EVIDENCE"

What the file will be used for

correlationID
string non-empty

Your own identifier for this upload. Reusing it for the same purpose returns the file stored on the first call. Defaults to a generated UUID.

Responses

Request samples 

const http = require('https');

const options = {
  method: 'POST',
  hostname: 'api.woovi.com',
  port: null,
  path: '/api/v1/files',
  headers: {
    Authorization: '{APP_ID}',
    'content-type': 'multipart/form-data; boundary=---011000010111000001101001'
  }
};

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.write('-----011000010111000001101001\r\nContent-Disposition: form-data; name="file"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name="purpose"\r\n\r\nDISPUTE_EVIDENCE\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name="correlationID"\r\n\r\nevidence-2026-08-1042\r\n-----011000010111000001101001--\r\n');
req.end();

Response samples

Content type
application/json
{}

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.woovi.com',
  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.woovi.com',
  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.

website and businessDescription can be pre-filled by the caller. In the Brazilian flow businessDescription is the only field gating the COMPANY_DATA onboarding step, so sending it here lets the merchant skip that step of the wizard. On an idempotent replay both fields are only written when still empty — data typed by the applicant is never overwritten.

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

TaxID da empresa do merchant. CNPJ no fluxo brasileiro; EIN/CUIT/RUC etc. quando internationalAccount e true.

taxIDType
string

Tipo do taxID da empresa. Default BR:CNPJ. Obrigatorio quando internationalAccount e true (ex. EUA:EIN, AR:CUIT, PY:RUC).

partner
boolean
Default: false

Opt-in para criar uma empresa afiliada (partner-style). Quando true, exige company (o user e opcional) e que a empresa autenticada tenha a feature PARTNER (+ KYC_ONBOARDING_LINK). Sem partner: true, o fluxo permanece BAAS (AccountRegister na empresa autenticada).

internationalAccount
boolean
Default: false

Quando true, cria onboarding internacional (INTERNACIONAL_ACCOUNT + feature KYC_INTERNACIONAL). Requer que a empresa autenticada tenha a feature KYC_INTERNACIONAL.

correlationID
string

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

website
string <uri>

Website da empresa do merchant. Gravado no AccountRegister e, no modo partner, tambem na Company afiliada. Num replay idempotente so e preenchido se ainda estiver vazio.

businessDescription
string

Descricao da atividade da empresa. Gravado no AccountRegister e, no fluxo brasileiro, e o unico campo que libera a etapa COMPANY_DATA do onboarding — enviar aqui poupa essa etapa do wizard. Num replay idempotente so e preenchido se ainda estiver vazio.

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 (fluxo brasileiro)

object (KycOnboardingCompanyPayload)

When partner: true, creates a new affiliate Company under the authenticated partner (partner-style onboarding) and attaches the onboarding link to that company instead of the BAAS company. company is required; user is optional.

object (KycOnboardingUserPayload)

Optional admin user created for the affiliate company. When omitted, the affiliate is created without an admin user.

Responses

Request samples

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

Response samples

Content type
application/json
{}

Get a KYC validation by correlationID

Reads back a validation created with POST /api/v1/kyc-validation/taxid, scoped to your own company. Free — reading a validation is never billed.

Poll this until status leaves PROCESSING, or subscribe to the KYC_VALIDATION_COMPLETED / KYC_VALIDATION_FAILED webhook events and skip the polling entirely.

Requires the KYC_VALIDATION feature on the company and the KYC_VALIDATION_GET scope on the application.

Authorizations:
AppID
path Parameters
correlationID
required
string <= 128 characters
Example: my-unique-id

The correlationID you sent when creating the validation.

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.woovi.com',
  port: null,
  path: '/api/v1/kyc-validation/my-unique-id',
  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
Example
{
  • "correlationID": "my-unique-id",
  • "taxId": "02916265000160",
  • "status": "COMPLETED",
  • "result": "REJECTED",
  • "riskLevel": "HIGH",
  • "reasons": [
    ],
  • "createdAt": "2026-08-24T14:00:06.386Z",
  • "completedAt": "2026-08-24T14:00:06.462Z"
}

Create a KYC validation for a Tax ID

Screens a CPF or CNPJ against fraud, dispute, sanctions, PEP and lawsuit signals and returns a verdict.

Requires the KYC_VALIDATION feature on the company and the KYC_VALIDATION_POST scope on the application.

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

CPF (11 digits) or CNPJ (14 digits) to be screened. A mask is accepted — everything that is not a digit is stripped before validation.

correlationID
required
string [ 1 .. 128 ] characters

Your own identifier for this validation. It is the idempotency key: sending the same correlationID again returns the original validation with 200 and is not billed a second time. It is also how you read the result back.

Responses

Request samples

Content type
application/json
Example
{
  • "taxId": "02.916.265/0001-60",
  • "correlationID": "my-unique-id"
}

Response samples

Content type
application/json
{
  • "correlationID": "my-unique-id",
  • "taxId": "02916265000160",
  • "status": "COMPLETED",
  • "result": "REJECTED",
  • "riskLevel": "HIGH",
  • "reasons": [
    ],
  • "createdAt": "2026-08-24T14:00:06.386Z",
  • "completedAt": "2026-08-24T14:00:06.462Z"
}

account limits

Endpoints to query account limits for a given bank account.

Limits are expressed in cents and split into a day and a night window, delimited by dayStartAt and nightStartAt. A limit field that is absent from the response has no cap configured for that window.

List your limit requests

Returns the limit-increase requests of your company, newest first.

Authorizations:
AppID
query Parameters
limit
integer

How many requests to return (max 100, default 20)

skip
integer

How many requests to skip

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.woovi.com',
  port: null,
  path: '/api/v1/limits/request?limit=SOME_INTEGER_VALUE&skip=SOME_INTEGER_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
{
  • "limitRequests": [
    ],
  • "pageInfo": {
    }
}

Ask to raise the limits of an account

Opens a limit-increase request for one of your accounts. It is created with status: IN_REVIEW; poll GET /api/v1/limits/request/{limitRequestId} until it becomes APPROVED (with approvedLimits) or REJECTED.

Upload the supporting document FIRST

A limit request is never accepted without at least one document justifying it, and the document does not travel in this request. It is a two-step flow, and the order matters:

Step 1 — upload the file. Send it to POST /api/v1/files as multipart/form-data, with purpose=ACCOUNT_LIMIT_REQUEST. That endpoint needs the FILE_POST scope and accepts application/pdf, image/png, image/jpeg and image/webp up to 10 MiB. Keep the file.id it returns.

curl -X POST https://api.woovi.com/api/v1/files \
  -H 'Authorization: <your AppID>' \
  -F 'purpose=ACCOUNT_LIMIT_REQUEST' \
  -F '[email protected]'

Step 2 — open the request with that id, in documents[].fileId:

curl -X POST https://api.woovi.com/api/v1/limits/request \
  -H 'Authorization: <your AppID>' \
  -H 'Content-Type: application/json' \
  -d '{"companyBankAccountId":"65f1c2e9a1b2c3d4e5f60718",
       "pixDayLimit":5000000,
       "pixNightLimit":200000,
       "documents":[{"fileId":"68c7d0a1f0b2c3d4e5f60718"}]}'

A fileId is only accepted when the file belongs to your company and was uploaded with purpose=ACCOUNT_LIMIT_REQUEST. Anything else — a file of another company, another purpose, or an id that does not exist — answers 400 and no request is created. Uploading the file with the wrong purpose is the most common cause of that 400: upload it again with the right one, you do not need to delete the first.

The limits you send

Limits are in cents and use the same field names as GET /api/v1/limits/{accountId}, so read the current values there, raise the ones you need, and send them here. pixDayLimit and pixNightLimit are always required. No field may be below its current value, and at least one must be above it — otherwise the request is a 400.

Only one request per account can be IN_REVIEW at a time; a second one answers 409 while the first is still being analysed.

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

The account whose limits should be raised

required
Array of objects [ 1 .. 10 ] items

The files that justify the increase, between 1 and 10. Upload each one first with POST /api/v1/files using purpose=ACCOUNT_LIMIT_REQUEST.

description
string <= 500 characters

Free text for the analyst reviewing the request

limitRequestReason
string <= 500 characters
pixDayLimit
required
number
pixNightLimit
required
number
pixOutSameHolderDayLimit
number
pixOutSameHolderNightLimit
number
pixOutDifferentHolderDayLimit
number
pixOutDifferentHolderNightLimit
number
pixInSameHolderDayLimit
number
pixInSameHolderNightLimit
number
pixInDifferentHolderDayLimit
number
pixInDifferentHolderNightLimit
number

Responses

Request samples

Content type
application/json
{
  • "companyBankAccountId": "65f1c2e9a1b2c3d4e5f60718",
  • "pixDayLimit": 5000000,
  • "pixNightLimit": 200000,
  • "documents": [
    ],
  • "description": "faturamento dos ultimos 12 meses"
}

Response samples

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

Get one limit request

Returns one limit-increase request. This is the endpoint to poll after creating a request.

status stays IN_REVIEW until Woovi decides, and then becomes:

  • APPROVED — approvedLimits carries what was actually granted, and it may be lower than what you asked for. The account's effective limits change at the same moment, so GET /api/v1/limits/{accountId} reflects them right away.
  • REJECTED — nothing changed on the account. You may open a new request for the same account once this one is decided.

approvedLimits is absent while the request is still IN_REVIEW.

A request of another company answers 404, never a 403 — the id alone never confirms that a request exists.

Authorizations:
AppID
path Parameters
limitRequestId
required
string
Examples:
  • 68c7d0a1f0b2c3d4e5f6071a -

Woovi identifier of the limit request

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.woovi.com',
  port: null,
  path: '/api/v1/limits/request/68c7d0a1f0b2c3d4e5f6071a',
  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
{
  • "limitRequest": {
    }
}

Get account limits

Retrieves the most recent account limits configured for a given bank account, including the stablecoin (stableIn* / stableOut*) limits. Only the public-safe fields are returned; internal-only fields are stripped from the response. Fields with no cap configured are omitted 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.woovi.com',
  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.woovi.com',
  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.woovi.com',
  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.woovi.com',
  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.woovi.com',
  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.woovi.com',
  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

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.woovi.com',
  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.woovi.com',
  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.woovi.com',
  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": [
    ]
}

pixKey check (request access)

Endpoints to look up the holder of a Pix key through the DICT.

This endpoint is not enabled by default. It queries the DICT for the holder of a Pix key that is not yours, so it has to be requested from support and goes through an internal review before being turned on. Calls are billed per query.

If what you need is to confirm that an account belongs to who you expect, use bank data validation instead — it is available to every account with no approval:

Check data from a Pix key

Get data from a Pix key if it exists.

This endpoint is not enabled by default. It queries the DICT for the holder of a Pix key that is not yours, so it has to be requested from support and goes through an internal review before being turned on. Calls are billed per query.

If what you need is to confirm that an account belongs to who you expect, use bank data validation instead — it is available to every account with no approval:

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.

This endpoint is not enabled by default. It queries the DICT for the holder of a Pix key that is not yours, so it has to be requested from support and goes through an internal review before being turned on. Calls are billed per query.

If what you need is to confirm that an account belongs to who you expect, use bank data validation instead — it is available to every account with no approval:

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": {
    }
}

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.woovi.com',
  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.woovi.com',
  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.woovi.com',
  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

query Parameters
companyBankAccount
string
Example: companyBankAccount=507f1f77bcf86cd799439011

Restrict the lookup to another bank account of your company instead of the one linked to the appID. Only a MASTER application of a company with the MASTER_APP_READ_ANY_ACCOUNT feature can use it. Use the accountId returned by GET /api/v1/account.

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.woovi.com',
  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.woovi.com',
  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.woovi.com',
  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.woovi.com',
  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.woovi.com',
  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.

There are two fee models, and the amount field you send picks one:

  • grossAmount (recommended): all-in. The Woovi fee comes OUT of it, so the account is debited exactly grossAmount and the provider is paid the remainder.
  • value (legacy): the amount paid to the provider, with the Woovi fee charged ON TOP — the account is debited value + wooviFee.

Either way the response breaks the total down into wooviFee and providerFee, and GET /api/v1/stablecoin/quote reports the same numbers for the same input.

The deposit is always credited to the stable subaccount of the CompanyBankAccount linked to the authenticated AppID. The AppID must have a companyBankAccount configured (otherwise 400 APPLICATION_COMPANY_BANK_ACCOUNT_MISSING), and that bank account must have a stable subaccount in CONFIRMED status (a completed KYB) — another bank account's subaccount on the same company is never used. Otherwise the request is rejected with a 400.

subAccountId, when sent, must belong to that same CompanyBankAccount.

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

  • USDT: POLYGON, ETHEREUM, CELO, TRON, BNB
  • USDC: POLYGON, ETHEREUM, BASE, CELO, BNB
  • 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" "BNB"

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
{
  • "grossAmount": 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 pre-signed URL to upload a limit-increase document

Step 1 of the monthly limit-increase flow: returns a pre-signed URL to upload one supporting document (comprovante) — proof of financial capacity, company address proof or UBO (partner) address proof.

The file goes straight from the client to storage; it never transits the API. The URL is scoped to a key that belongs to the authenticated company, is single use and expires in expiresIn seconds.

Upload it with PUT <uploadUrl> sending the same Content-Type returned in headers and the raw file as the body — no multipart, no extra headers. Then post the returned document object on POST /api/v1/stablecoin/limit/request (or on POST /api/v1/stablecoin/limit/request/{limitRequestId}/document).

Files above maxSizeBytes, or whose content type is not one of application/pdf, image/jpeg, image/png, image/webp, are rejected when the document is attached to the request.

Requires the STABLECOIN_SUBACCOUNT_CREATE scope and the company STABLECOIN feature.

Authorizations:
AppID
Request Body schema: application/json
required
type
required
string (StablecoinLimitDocumentType)
Enum: "PROOF_OF_FINANCIAL_CAPACITY" "PROOF_OF_ADDRESS_COMPANY" "PROOF_OF_ADDRESS_UBO"

Category of the supporting document (comprovante): PROOF_OF_FINANCIAL_CAPACITY (proof of financial capacity — bank statements of the UBO/partner), PROOF_OF_ADDRESS_COMPANY (company registered-address proof) or PROOF_OF_ADDRESS_UBO (UBO/partner residence-address proof).

fileName
required
string

Original file name. Sanitized before it becomes the object key.

mimeType
required
string
Enum: "application/pdf" "image/jpeg" "image/png" "image/webp"

Content type of the file. Signed into the upload URL: the PUT must send exactly this Content-Type.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "PROOF_OF_ADDRESS_COMPANY",
  • "fileName": "comprovante-endereco-empresa.pdf",
  • "mimeType": "application/pdf"
}

Response samples

Content type
application/json
{
  • "uploadUrl": "https://woovi-media.s3.us-east-1.amazonaws.com/stablecoin/limit-request/...",
  • "method": "PUT",
  • "headers": {
    },
  • "expiresIn": 900,
  • "maxSizeBytes": 10485760,
  • "document": {
    }
}

Add a supporting document to a limit-increase request

Attaches one more comprovante to a request that is still IN_REVIEW — the path for "the analysis asked for another address proof" or for retrying a document whose submissionStatus came back FAILED.

The document must have been uploaded through POST /api/v1/stablecoin/limit/document first, and the same ownership, size and content-type checks of the create call apply. A request accepts at most 10 documents.

The push to the KYB provider runs in the background: poll GET /api/v1/stablecoin/limit/request/{limitRequestId}.

Requires the STABLECOIN_SUBACCOUNT_CREATE scope and the company STABLECOIN feature.

Authorizations:
AppID
path Parameters
limitRequestId
required
string
Example: 6650abc1234def567890bbbb

The limitRequestId returned when the request was created.

Request Body schema: application/json
required
type
required
string (StablecoinLimitDocumentType)
Enum: "PROOF_OF_FINANCIAL_CAPACITY" "PROOF_OF_ADDRESS_COMPANY" "PROOF_OF_ADDRESS_UBO"

Category of the supporting document (comprovante): PROOF_OF_FINANCIAL_CAPACITY (proof of financial capacity — bank statements of the UBO/partner), PROOF_OF_ADDRESS_COMPANY (company registered-address proof) or PROOF_OF_ADDRESS_UBO (UBO/partner residence-address proof).

bucketName
required
string
path
required
string
fileName
string
mimeType
string

Responses

Request samples

Content type
application/json
{
  • "type": "PROOF_OF_ADDRESS_UBO",
  • "bucketName": "woovi-media",
  • "path": "stablecoin/limit-request/6650abc1234def567890aaaa/91ae-endereco-socio.pdf",
  • "fileName": "endereco-socio.pdf",
  • "mimeType": "application/pdf"
}

Response samples

Content type
application/json
{
  • "limitRequestId": "6650abc1234def567890bbbb",
  • "companyBankAccountId": "6650abc1234def567890dddd",
  • "status": "IN_REVIEW",
  • "desiredMonthlyLimit": 50000000,
  • "description": "Aumento de volume para folha de pagamento",
  • "submissionStatus": "PROCESSING",
  • "documents": [
    ],
  • "createdAt": "2026-08-06T12:00:00.000Z",
  • "updatedAt": "2026-08-06T12:00:00.000Z"
}

Get a limit-increase request

Returns the request, its documents and how far the delivery to the KYB provider got (submissionStatus).

status is the analysis outcome (IN_REVIEW, APPROVED, REJECTED) — the monthly ceiling is raised by the analysis team, so APPROVED is what tells the merchant the new limit is in place.

Requires the STABLECOIN_SUBACCOUNT_LIST scope and the company STABLECOIN feature.

Authorizations:
AppID
path Parameters
limitRequestId
required
string
Example: 6650abc1234def567890bbbb

The limitRequestId returned when the request was created.

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.woovi.com',
  port: null,
  path: '/api/v1/stablecoin/limit/request/6650abc1234def567890bbbb',
  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
{
  • "limitRequestId": "6650abc1234def567890bbbb",
  • "companyBankAccountId": "6650abc1234def567890dddd",
  • "status": "IN_REVIEW",
  • "desiredMonthlyLimit": 50000000,
  • "description": "Aumento de volume para folha de pagamento",
  • "submissionStatus": "PROCESSING",
  • "documents": [
    ],
  • "createdAt": "2026-08-06T12:00:00.000Z",
  • "updatedAt": "2026-08-06T12:00:00.000Z"
}

Request a higher monthly stablecoin limit

Step 2 of the monthly limit-increase flow: opens the request with the supporting documents (comprovantes) already uploaded through POST /api/v1/stablecoin/limit/document.

Each document is checked before the request is persisted: it must live in the company's own storage prefix, must actually have been uploaded, must be within the size ceiling and must carry an accepted content type.

The push to the KYB provider runs in the background — the response comes back with submissionStatus: PROCESSING. Poll GET /api/v1/stablecoin/limit/request/{limitRequestId} until it flips to SENT or FAILED.

The request raises the ceiling of the account the AppID answers for (companyBankAccountId in the response). A company that holds several accounts — a BaaS partner holds one per sub-merchant, each with its own KYB — asks for each one separately, with that account's AppID.

Only one request per account can be under review at a time; while it is IN_REVIEW, extra documents go to POST /api/v1/stablecoin/limit/request/{limitRequestId}/document. The ceiling itself is raised by the analysis team once the documents are approved — a successful call does not change the limit by itself.

Requires the STABLECOIN_SUBACCOUNT_CREATE scope, the company STABLECOIN feature and a confirmed stablecoin subaccount.

Authorizations:
AppID
Request Body schema: application/json
required
desiredMonthlyLimit
required
integer

Requested monthly limit, in BRL cents.

description
string

Free-text justification shown to the analyst.

required
Array of objects (StablecoinLimitDocumentRef) [ 1 .. 10 ] items

Responses

Request samples

Content type
application/json
{
  • "desiredMonthlyLimit": 50000000,
  • "description": "Aumento de volume para folha de pagamento",
  • "documents": [
    ]
}

Response samples

Content type
application/json
{
  • "limitRequestId": "6650abc1234def567890bbbb",
  • "companyBankAccountId": "6650abc1234def567890dddd",
  • "status": "IN_REVIEW",
  • "desiredMonthlyLimit": 50000000,
  • "description": "Aumento de volume para folha de pagamento",
  • "submissionStatus": "PROCESSING",
  • "documents": [
    ],
  • "createdAt": "2026-08-06T12:00:00.000Z",
  • "updatedAt": "2026-08-06T12:00:00.000Z"
}

List the company limit-increase requests

Returns this company's limit-increase requests, newest first (up to 20).

Requires the STABLECOIN_SUBACCOUNT_LIST scope and the company STABLECOIN feature.

Authorizations:
AppID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.woovi.com',
  port: null,
  path: '/api/v1/stablecoin/limit/request',
  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",
  • "limitRequests": [
    ]
}

Approve a pending payout (execute Pix off-ramp)

Approves a payout previously created with POST /api/v1/stablecoin/payout. Identified by correlationId only. Refreshes the provider quote (tokens expire quickly), opens the ticket (debits INTERNAL float and sends BRL via Pix), and moves the payout to PROCESSING.

Same two-step pattern as deposit approve (POST /deposit/approve).

Requires the STABLECOIN_PAYOUT_CREATE scope.

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

The correlationId sent when creating the payout.

Responses

Request samples

Content type
application/json
{
  • "correlationId": "payout-001"
}

Response samples

Content type
application/json
{
  • "status": "PROCESSING",
  • "correlationId": "string",
  • "payoutId": "string"
}

Get the current status of a payout

Returns the current state of a payout created through POST /api/v1/stablecoin/payout.

While the payout is still in flight the provider ticket is re-read and the payout is updated before responding. Terminal payouts are served from storage.

Requires the STABLECOIN_PAYOUT_CREATE scope.

Authorizations:
AppID
path Parameters
payoutId
required
string

The payoutId returned by the create call.

Responses

Response samples

Content type
application/json
{
  • "status": "PENDING",
  • "payoutId": "string",
  • "correlationId": "string",
  • "ticketId": "string",
  • "subAccountId": "string",
  • "pixKey": "string",
  • "brCode": "string",
  • "pixKeyOwner": {
    },
  • "endToEndId": "string",
  • "failureReason": "string",
  • "isRefunded": false,
  • "refund": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "quote": {
    }
}

List payouts, or get one by correlationId

With correlationId, returns the single payout created under that idempotency key — the same body as GET /api/v1/stablecoin/payout/{payoutId}.

Without it, lists the authenticated company's payouts, newest first.

The list is served from storage: unlike the single-payout call it does not re-read the provider ticket, so a payout still in flight is as fresh as the last webhook or status read. Read an individual payout to force a sync.

isRefunded tells a settled payout that came back from one that did not. A returned payout keeps status: COMPLETED — the Pix did leave — so the status alone never reveals the return. Whether the money is usable again is refund.status (CONFIRMED = spendable, FAILED = needs reconciliation), not the flag.

Requires the STABLECOIN_PAYOUT_CREATE scope.

Authorizations:
AppID
query Parameters
correlationId
string

The idempotency key sent on create. Returns a single payout instead of a list.

status
string
Enum: "PENDING" "PROCESSING" "COMPLETED" "FAILED"

Only payouts in this status.

isRefunded
string
Enum: "true" "false"

true lists only settled payouts that were returned; false only those that were not.

start
string <date-time>

Only payouts created at or after this ISO date.

end
string <date-time>

Only payouts created at or before this ISO date.

skip
integer [ 0 .. 10000 ]
Default: 0

Documents to skip. Capped at 10000 — page deeper with start/end, since past that MongoDB walks the index for every skipped document.

limit
integer [ 1 .. 100 ]
Default: 100

Page size. Values above 100 are capped at 100.

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.woovi.com',
  port: null,
  path: '/api/v1/stablecoin/payout?correlationId=SOME_STRING_VALUE&status=SOME_STRING_VALUE&isRefunded=SOME_STRING_VALUE&start=SOME_STRING_VALUE&end=SOME_STRING_VALUE&skip=SOME_INTEGER_VALUE&limit=SOME_INTEGER_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
Example
{
  • "status": "ok",
  • "payouts": [
    ],
  • "pageInfo": {
    }
}

Pay out INTERNAL balance to BRL via Pix

Converts a stablecoin balance held on the company's INTERNAL float into BRL and sends it to the given Pix key. Supported debit assets: USDT, USDC, BRLA.

value is the target Pix amount in BRL cents (ex.: 10000 = R$ 100,00). The INTERNAL debit in currency is taken from the provider quote. The subaccount is resolved from the Application's companyBankAccount, same as the wallets endpoint.

Flow (same two-step pattern as deposit): quote (fixed BRL) → balance check → consume Woovi OUT limit (BRL cents) → resolve Pix beneficiary → persist as PENDING. Call POST /api/v1/stablecoin/payout/approve to open the provider ticket and move to PROCESSING.

Fund the INTERNAL float first via GET /api/v1/stablecoin/wallets (send USDT/USDC/BRLA on-chain to a returned address), then call this endpoint.

Idempotency is supported via correlationId: reusing one returns the payout already created for it.

Requires the STABLECOIN_PAYOUT_CREATE scope.

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

Target Pix amount in BRL cents (ex. 10000 = R$ 100,00).

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

INTERNAL float asset to debit (amount from quote).

pixKey
required
string

Destination Pix key.

correlationId
string or null

Optional idempotency key echoed back on the response.

pixMessage
string or null

Optional Pix message sent with the transfer.

Responses

Request samples

Content type
application/json
{
  • "value": 10000,
  • "currency": "USDC",
  • "pixKey": "13d3109f-3a1e-4c56-b76d-d2db7213b9f2",
  • "correlationId": "string",
  • "pixMessage": "string"
}

Response samples

Content type
application/json
{
  • "status": "PENDING",
  • "payoutId": "string",
  • "correlationId": "string",
  • "pixKey": "string",
  • "pixKeyOwner": {
    },
  • "quote": {
    }
}

Quote an INTERNAL balance off-ramp to BRL via Pix

Returns a quote for delivering a target BRL amount via Pix, debiting INTERNAL float (USDT / USDC / BRLA). The fixed side is BRL; the response inputAmount is how much of currency will be spent.

value is the target Pix amount in BRL cents (ex.: 10000 = R$ 100,00).

The Woovi fee (STABLE_PAYOUT_FEE, priced from the AppID bank account's stable payout fee settings) is reported as wooviFee. It is a SEPARATE BRL debit charged when the payout is approved — it is never deducted from outputAmount, so the total cost of the payout is outputAmount worth of float plus wooviFee in BRL. It comes back null when the fee service cannot price it; the payout itself still goes through.

Requires the STABLECOIN_PAYOUT_CREATE scope.

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

Target Pix amount in BRL cents (ex. 10000 = R$ 100,00).

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

INTERNAL float asset to debit (amount returned on the quote).

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.woovi.com',
  port: null,
  path: '/api/v1/stablecoin/payout/quote?value=10000&currency=USDC',
  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 quote without creating a deposit

Returns a PIX (BRL) -> stablecoin quote without creating a deposit, broken down into BOTH fees: the Woovi fee (priced from the AppID bank account's stable deposit fee settings, including its configured minimum) and the provider fee. Use it to display the exact amount of stablecoin the customer would receive, and the exact BRL that leaves the account, before confirming.

The amount field you send picks the fee model, exactly as in POST /api/v1/stablecoin/deposit:

  • grossAmount (recommended): all-in. The Woovi fee comes OUT of it, so grossAmount is what the account is debited and inputAmount is what the provider is quoted over.
  • value (legacy): the amount paid to the provider, with the Woovi fee charged ON TOP — the account is debited grossAmount = value + wooviFee.

BRL-denominated assets (BRLA) are charged the configured MINIMUM Woovi fee only: the percentage is meaningless against a BRL value, so it never scales with the amount.

The AppID must have a companyBankAccount configured, otherwise the fee cannot be priced and the request is rejected with 400 APPLICATION_COMPANY_BANK_ACCOUNT_MISSING. A quote is never returned without the Woovi fee — that would under-report what the customer pays.

The provider leg is cached for 60 seconds.

Requires the STABLECOIN_DEPOSIT_CREATE scope.

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

Legacy model: amount paid to the provider, in cents (BRL), with the Woovi fee charged on top. Send this or grossAmount, never both.

grossAmount
number >= 1
Example: grossAmount=10000

All-in model: total to debit, in cents (BRL). The Woovi fee comes out of it. Send this or value, never both.

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.woovi.com',
  port: null,
  path: '/api/v1/stablecoin/quote?value=10000&grossAmount=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": {
    }
}

Read the INTERNAL balances of a subaccount's float

Returns the provider's INTERNAL balance per asset for this subaccount — exactly the balance POST /api/v1/stablecoin/payout debits.

Poll this after sending funds to one of the addresses from GET /api/v1/stablecoin/wallets (or the subaccount wallets route) and only create the payout once the credit has landed.

Only subaccounts belonging to the authenticated company resolve; any other id returns 404.

Requires the STABLECOIN_SUBACCOUNT_LIST scope.

Authorizations:
AppID
path Parameters
subAccountId
required
string

Provider subaccount id (subAccountId, not the Woovi id).

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "subAccountId": "string",
  • "balances": {
    }
}

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": {
    }
}

Read the KYB USD (fiat rail) state of the company subaccount

Status of the USD rail on the company's CONFIRMED stablecoin subaccount: how far its KYB USD got and whether the provider currently accepts a USD ticket for it.

Poll this after POST /api/v1/stablecoin/subaccount/kyb/usd — the submission only creates the attempt, and the verdict lands later. While the attempt can still change verdict the stored status is reconciled with the provider on every read, so a rejection shows up here as soon as the provider has it.

usdUnlocked is the field that actually gates the rail: an APPROVED attempt alone is not enough, and it never turns true in the provider sandbox.

Requires the STABLECOIN_SUBACCOUNT_LIST scope and the company STABLECOIN feature.

Authorizations:
AppID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.woovi.com',
  port: null,
  path: '/api/v1/stablecoin/subaccount/kyb/usd',
  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
Example
{
  • "status": "ok",
  • "usdKyb": {
    }
}

Submit KYB USD (fiat rail) for a confirmed stablecoin subaccount

Unlocks the USD fiat rail on a company stablecoin subaccount that already has KYB Level 1 approved (StableSubAccount.status = CONFIRMED).

The call uploads the supporting documents to the provider, submits Proof of Financial Capacity (and waits until it is APPROVED), optionally submits a company Proof of Address, then submits the KYB USD attempt.

Document URLs must be publicly fetchable (or pre-signed) HTTPS links to the PDF/image files. Typical sources: files already uploaded during onboarding / RFI, or merchant-hosted temporary URLs.

Required documents:

  • proofOfFinancialCapacityUrl — proof of financial capacity (PoFC)
  • proofOfRevenueUrl — proof of revenue

Optional documents:

  • proofOfAddressCompanyUrl — company proof of address (raises limits; independent of the USD rail, but accepted in the same call)

Also required:

  • businessType — Bridge business type enum
  • businessIndustries — at least one industry from the StablecoinSubAccountKybUsdIndustry enum (e.g. SOFTWARE; OTHER when none fits)
  • website — required only when the company website was not captured at KYB Level 1

The subaccount must belong to the authenticated company and be CONFIRMED. Requires the STABLECOIN_SUBACCOUNT_CREATE scope and the company STABLECOIN feature.

The call is synchronous and waits on the provider: it can take up to two minutes, and answers 504 when the Proof of Financial Capacity is still not approved by then (the document ids come back, so nothing has to be re-uploaded).

A 201 only means the attempt was created — poll GET /api/v1/stablecoin/subaccount/kyb/usd for the verdict and for usdUnlocked.

Note: USD fiat rails are not available in the provider sandbox — submission may appear to succeed, but usdUnlocked will not become true there.

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

Provider subaccount id that already completed KYB Level 1.

businessType
required
string
Enum: "cooperative" "corporation" "llc" "other" "partnership" "sole_prop" "trust"

Bridge business type for the USD rail.

businessIndustries
required
Array of strings (StablecoinSubAccountKybUsdIndustry) non-empty unique
Items Enum: "SOFTWARE" "ECOMMERCE" "PROFESSIONAL_SERVICES" "MARKETING" "FOOD" "HEALTH" "EDUCATION" "LOGISTICS" "CONSTRUCTION" "FINANCIAL" "OTHER"

Industries the company operates in. At least one is required. Pick from the enum — the API maps each id to the provider's industry code; when none fits, send OTHER.

website
string <uri>

Company website. Required only when it was not captured at KYB Level 1.

proofOfRevenueUrl
required
string <uri>

HTTPS URL of the proof-of-revenue document (PDF/image). Downloaded by the API and uploaded to the provider as PROOF-OF-REVENUE.

proofOfFinancialCapacityUrl
required
string <uri>

HTTPS URL of the proof-of-financial-capacity document (PDF/image). Uploaded as PROOF-OF-FINANCIAL-CAPACITY, then submitted for verification. KYB USD is only requested after this attempt is APPROVED.

proofOfAddressCompanyUrl
string <uri>

Optional HTTPS URL of the company proof-of-address document (PDF/image). Uploaded as PROOF-OF-ADDRESS-COMPANY and submitted for verification to raise operating limits.

Responses

Request samples

Content type
application/json
Example
{}

Response samples

Content type
application/json
{
  • "subAccountId": "sub_01HZ...",
  • "usdKybAttemptId": "7d2f5b18-3e9c-4a7f-d246-6b0e1f8d4c52",
  • "proofOfRevenueDocId": "5f8d3c16-b2e7-4a9f-c834-1e6b0d5f2a91",
  • "proofOfFinancialCapacityDocId": "c4e9b27f-1a3d-4e8c-b561-7d2f0a9e4b38",
  • "proofOfFinancialCapacityAttemptId": "1e6b8c43-5f2a-4d9e-b782-4c1f0a7e3b65",
  • "proofOfAddressDocId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "proofOfAddressAttemptId": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}

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.woovi.com',
  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 a stablecoin subaccount (KYB) for the company behind your AppID, reusing the KYC data already on its account register.

The body can be empty — the target account is resolved from the credentials. Send accountRegisterId only to target another account register of the same company (a BaaS partner asking for one of its sub-merchants), and companyBankAccountId only to override which account the subaccount is stamped with.

Every gate runs before the response, so status is the verdict:

status Meaning
IN_REVIEW Accepted. The outcome arrives as a STABLECOIN_SUBACCOUNT_CONFIRMED or STABLECOIN_SUBACCOUNT_REJECTED webhook.
AWAITING_DOCUMENTS Documents are missing. Send the merchant to rfi.url; answering it re-runs the KYB.
REJECTED Refused for good — screening, fraud markers, a CNPJ that is not ACTIVE, a refused KYC score. reasonCode says which.
FAILED Blocked by a gap in the account register that only a Woovi operator can fix. Retrying does not help.

Repeat calls are idempotent on the resolved account register: they return the existing subaccount with its current verdict (HTTP 200, including an RFI link that is still open) 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
optional
accountRegisterId
string

The account register id whose KYC data backs the KYB. Must belong to the authenticated company. Defaults to the account register of the bank account behind the AppID.

companyBankAccountId
string

Company bank account to associate with the subaccount. Defaults to the bank account configured on the AppID, then to the company's default bank account.

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{}

List the deposit addresses of a subaccount's float

Returns the wallets the provider holds for this subaccount. Sending an asset on-chain to one of these addresses credits the subaccount's INTERNAL balance — the same balance POST /api/v1/stablecoin/swap spends and POST /api/v1/stablecoin/withdraw pays out from.

Use this to resolve where to prefund instead of hardcoding an address: funding a different account's wallet leaves the swap float empty and the swap fails for lack of balance.

Only subaccounts belonging to the authenticated company resolve; any other id returns 404.

Requires the STABLECOIN_SUBACCOUNT_LIST scope.

Authorizations:
AppID
path Parameters
subAccountId
required
string

Provider subaccount id (subAccountId, not the Woovi id).

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "subAccountId": "string",
  • "wallets": [
    ]
}

Get the current status of a swap

Returns the current state of a swap created through POST /api/v1/stablecoin/swap, so a caller can poll it to completion instead of replaying the create request with the same correlationId.

While the swap is still in flight (CREATED, PENDING, PROCESSING) the provider ticket is re-read and the swap is updated before responding, with at most one provider read every 3 seconds per swap. Terminal swaps (COMPLETED, FAILED) are served straight from storage.

A FAILED swap carries failureReason with the provider's own reason whenever it reported one.

Requires the STABLECOIN_SWAP_CREATE scope.

Authorizations:
AppID
path Parameters
swapId
required
string
Example: 6650abc1234def567890aaaa

The swapId returned by the create call.

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.woovi.com',
  port: null,
  path: '/api/v1/stablecoin/swap/6650abc1234def567890aaaa',
  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": "COMPLETED",
  • "swapId": "string",
  • "correlationId": "string",
  • "ticketId": "string",
  • "subAccountId": "string",
  • "network": "string",
  • "destinationWalletAddress": "string",
  • "txHash": "string",
  • "expiration": "string",
  • "failureReason": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "quote": {
    }
}

Get the current status of a swap by correlationId

Same as GET /api/v1/stablecoin/swap/{swapId}, looked up by the correlationId the caller sent on create. When a correlationId was reused across several swaps, the most recent one is returned.

Requires the STABLECOIN_SWAP_CREATE scope.

Authorizations:
AppID
query Parameters
correlationId
required
string

The idempotency key sent on create.

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.woovi.com',
  port: null,
  path: '/api/v1/stablecoin/swap?correlationId=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
{
  • "status": "COMPLETED",
  • "swapId": "string",
  • "correlationId": "string",
  • "ticketId": "string",
  • "subAccountId": "string",
  • "network": "string",
  • "destinationWalletAddress": "string",
  • "txHash": "string",
  • "expiration": "string",
  • "failureReason": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "quote": {
    }
}

Swap a stablecoin asset, optionally delivering it on-chain

Converts a balance from one stablecoin asset into another on the company's Avenia (sub-)account. Supported assets: BRLA, USDC, USDT.

value is the amount spent from the source (from) asset balance, in cents.

Two output modes, one provider ticket either way:

  • Without network / destinationWalletAddress — an INTERNAL -> INTERNAL conversion. The output stays as a balance on the sub-account. from and to must be different assets.
  • With both — an INTERNAL -> <network> ticket: the output is delivered on-chain to destinationWalletAddress instead of being credited to the balance. There is no second call and no second fee: the conversion and the delivery are quoted and settled as one ticket. In this mode from and to may be the same asset, which makes the request a plain on-chain payout with no conversion.

The two fields are only meaningful together — sending one without the other is a 400.

When the subaccount has enforceWalletWhitelist on, an on-chain destinationWalletAddress must be an approved (network, address) pair; the request is rejected before any limit is consumed or any provider call is made. An INTERNAL-only swap moves nothing off-platform and is not gated by the whitelist.

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

Idempotency is supported via correlationId: reusing one returns the swap already created for it instead of creating a second provider ticket. Always send one when delivering on-chain — without it a retry sends the funds twice.

Requires the STABLECOIN_SWAP_CREATE scope.

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

Amount to swap, in cents of the source asset.

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

Source asset to spend.

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

Destination asset to receive.

network
string or null
Enum: "POLYGON" "ETHEREUM" "BASE" "CELO" "TRON" "BNB"

Deliver the output on this chain instead of crediting the INTERNAL balance. Must be sent together with destinationWalletAddress. Supported per asset — USDT: POLYGON, ETHEREUM, CELO, TRON, BNB; USDC: POLYGON, ETHEREUM, BASE, CELO, BNB; BRLA: POLYGON, ETHEREUM, BASE, CELO.

destinationWalletAddress
string or null

External address that receives the output. Must be sent together with network.

subAccountId
string or null

Optional Avenia sub-account to swap on.

correlationId
string or null

Optional idempotency key echoed back on the response.

Responses

Request samples

Content type
application/json
Example
{
  • "value": 100000,
  • "from": "BRLA",
  • "to": "USDC"
}

Response samples

Content type
application/json
{
  • "status": "PENDING",
  • "swapId": "string",
  • "correlationId": "string",
  • "expiration": "string",
  • "network": "string",
  • "destinationWalletAddress": "string",
  • "quote": {
    }
}

Get a stablecoin swap quote without creating a swap

Quotes converting value (in cents of the from asset) into the to asset without creating a swap. Use it to display the exact output amount before confirming. Supported assets: BRLA, USDC, USDT.

Pass the same network the swap will use to price the whole thing through to the chain. The delivery fee and gas only exist on that leg, so an INTERNAL-only quote understates the cost of a swap that ends on-chain. Without network, from and to must be different; with one they may match (a payout with no conversion).

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

Requires the STABLECOIN_SWAP_CREATE scope.

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

Amount to quote, in cents of the source asset. Must be positive.

from
required
string
Enum: "USDT" "USDC" "BRLA"
Example: from=BRLA

Source asset to spend.

to
required
string
Enum: "USDT" "USDC" "BRLA"
Example: to=USDC

Destination asset to receive.

network
string
Enum: "POLYGON" "ETHEREUM" "BASE" "CELO" "TRON" "BNB"
Example: network=BASE

Quote the on-chain delivery leg too, instead of stopping at the INTERNAL balance.

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.woovi.com',
  port: null,
  path: '/api/v1/stablecoin/swap/quote?value=100000&from=BRLA&to=USDC&network=BASE',
  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": {
    }
}

List custodian deposit wallets for the AppID bank account

Returns the deposit addresses for the stable sub-account linked to the authenticated Application's companyBankAccount (live from the provider — not stored in Mongo).

A company can have more than one bank account / KYB sub-account. The sub-account is resolved from Application.companyBankAccount (the account bound to the AppID), not from the company alone.

Sending an asset on-chain to one of these addresses credits the INTERNAL float used by POST /api/v1/stablecoin/payout (USDT/USDC/BRLA → Pix).

For an explicit provider id use GET /api/v1/stablecoin/subaccount/{subAccountId}/wallets. To read the float balance after funding use GET /api/v1/stablecoin/subaccount/{subAccountId}/balances.

Requires the STABLECOIN_SUBACCOUNT_LIST scope.

Authorizations:
AppID

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.woovi.com',
  port: null,
  path: '/api/v1/stablecoin/wallets',
  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",
  • "companyBankAccountId": "string",
  • "subAccountId": "string",
  • "wallets": [
    ]
}

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

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

Pix key registered to the subaccount

Responses

Request samples 

const http = require('https');

const options = {
  method: 'DELETE',
  hostname: 'api.woovi.com',
  port: null,
  path: '/api/v1/subaccount/[email protected]',
  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 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.woovi.com',
  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.woovi.com',
  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

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": "[email protected]",
  • "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

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": "[email protected]",
  • "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

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.woovi.com',
  port: null,
  path: '/api/v1/subaccount/[email protected]/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.woovi.com',
  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.woovi.com',
  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.woovi.com',
  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.woovi.com',
  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.woovi.com',
  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": {
    }
}

Generate the payment book (carnê) of a subscription

Builds the payment book (carnê) of a subscription as a PDF — one slip per installment, in a single request, up to the month/year you ask for.

Only for type: RECURRENT subscriptions. Pix Automático (PIX_RECURRING) has no payment book: there the payer's bank executes each charge on its own date, so the charges cannot be brought forward into a document. Asking for the payment book of a Pix Automático subscription is answered with 400.

A subscription's future installments do not exist as charges yet — each one is created close to its own due date. Printing a booklet brings that forward.

The call is synchronous and creates every missing charge in the period. Nothing is queued and there is no ticket to poll: it walks the installments up to the cutoff you asked for, creates the charge of each one that does not have it, and answers only once the PDF is ready. Response time is therefore much longer than a normal call, and grows with the number of charges to create — a long booklet asked for the first time is the worst case, because none of its installments exist yet. Raise your client's timeout before asking for a long period; the default in most HTTP libraries is too short for this.

Those charges are real: they show on your statement, fire the usual webhooks when paid, and follow your account's commercial terms, including any boleto issuing fee that applies to it. So treat it as a write even though it is a GET: do not put it behind a blind retry, a link prefetch or a monitoring check, and ask only for the period you are going to hand to the customer.

month and year are required and reach at most the end of next year. There is no default — the pair decides how many charges are created, so the caller states it.

Repeating the request is safe: an installment that already has a charge does not get a second one, so a reprint costs nothing and widening the window creates only the difference. That is also the recovery if your client times out — call the same URL again.

The booklet carries a slip for each in-range installment that is still open. Installments already paid or expired are left out, so it never invites paying the same one twice — which is why the slip count can be lower than the number of installments in the period.

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

The globalID or the id of the subscription. Unlike the other subscription endpoints, this one does not accept a correlationID.

query Parameters
month
required
integer [ 1 .. 12 ]
Example: month=12

Last month the booklet reaches, 1–12. Required.

year
required
integer
Example: year=2027

Last year the booklet reaches. Required, and limited to the current year or the next one — a later year is answered with 400, it is not truncated to the ceiling. A month/year already past is accepted and simply yields fewer slips.

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.woovi.com',
  port: null,
  path: '/api/v1/subscriptions/UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM=/payment-book?month=12&year=2027',
  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
Example
{
  • "error": "O carnê exige o mês e o ano até onde gerar"
}

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.woovi.com',
  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
{}

Response samples

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

webhook

Endpoint to manage Webhooks

Account blockings changed Webhook

The blockings on a bank account changed. Requires the SEND_WEBHOOK_TO_BLOCK_COMPANY_BANK_ACCOUNT feature.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "COMPANY_BANK_ACCOUNT_BLOCKED"
object
blockings
Array of strings
Items Enum: "PIX_IN" "PIX_OUT" "PIX_REFUND_SENT" "PIX_REFUND_RECEIVED" "PIX_OUT_BLOCK_THIRD_PARTY_CNPJ" "PIX_IN_BLOCK_THIRD_PARTY_CNPJ" "PIX_OUT_BLOCK_THIRD_PARTY_CPF" "BOLETO_OUT" "PIX_OUT_ALLOW_LIST_ONLY" "INTERNAL_TRANSFER_OUT" "INTERNAL_TRANSFER_IN" "PIX_REFUND"

Responses

Request samples

Content type
application/json
{
  • "event": "COMPANY_BANK_ACCOUNT_BLOCKED",
  • "account": {
    },
  • "blockings": [
    ]
}

Account register approved Webhook

A sub-account register was approved by compliance and the account can transact.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "ACCOUNT_REGISTER_APPROVED"
object
object

Responses

Request samples

Content type
application/json
{
  • "event": "ACCOUNT_REGISTER_APPROVED",
  • "accountRegister": {
    },
  • "account": {
    }
}

Account register rejected Webhook

A sub-account register was rejected by compliance.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "ACCOUNT_REGISTER_REJECTED"
object

Responses

Request samples

Content type
application/json
{
  • "event": "ACCOUNT_REGISTER_REJECTED",
  • "accountRegister": {
    }
}

Account register pending Webhook

A sub-account register is under compliance analysis.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "ACCOUNT_REGISTER_PENDING"
object

Responses

Request samples

Content type
application/json
{
  • "event": "ACCOUNT_REGISTER_PENDING",
  • "accountRegister": {
    }
}

Account register step updated Webhook

The end customer completed one step of the onboarding, or the BC Protege+ gate blocked one. A single event covers all eleven steps: step, stepScope and stepStatus say which step changed and how.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "ACCOUNT_REGISTER_STEP_UPDATED"
object

The cumulative onboarding state carried by every onboarding event. A single event is enough to know where the register stands — there is no need to replay the webhook history.

Responses

Request samples

Content type
application/json
{
  • "event": "ACCOUNT_REGISTER_STEP_UPDATED",
  • "accountRegister": {
    }
}

Account register in review Webhook

The register entered compliance analysis, either because the end customer submitted the onboarding or because an operator moved a pending register back into review. retryCount greater than zero means the register had already been sent back before.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "ACCOUNT_REGISTER_IN_REVIEW"
object (WebhookAccountRegisterOnboarding)

The cumulative onboarding state carried by every onboarding event. A single event is enough to know where the register stands — there is no need to replay the webhook history.

Responses

Request samples

Content type
application/json
{
  • "event": "ACCOUNT_REGISTER_IN_REVIEW",
  • "accountRegister": {
    }
}

Account register documents requested Webhook

Compliance asked for new documents (a request for information). Lists what was asked of the company and of each representative, and which steps went back to pending because of it. A request does not always send the register back to the customer — check status.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "ACCOUNT_REGISTER_DOCUMENTS_REQUESTED"
object

The cumulative onboarding state carried by every onboarding event. A single event is enough to know where the register stands — there is no need to replay the webhook history.

Responses

Request samples

Content type
application/json
{
  • "event": "ACCOUNT_REGISTER_DOCUMENTS_REQUESTED",
  • "accountRegister": {
    }
}

Account register RFI resolved Webhook

The end customer sent every document compliance had asked for, and the request for information was closed. Paired with ACCOUNT_REGISTER_DOCUMENTS_REQUESTED it measures how long a customer took to answer a pending request.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "ACCOUNT_REGISTER_RFI_RESOLVED"
object (WebhookAccountRegisterOnboarding)

The cumulative onboarding state carried by every onboarding event. A single event is enough to know where the register stands — there is no need to replay the webhook history.

Responses

Request samples

Content type
application/json
{
  • "event": "ACCOUNT_REGISTER_RFI_RESOLVED",
  • "accountRegister": {
    }
}

Boleto settled Webhook

A boleto was settled by the issuing bank. Emitted by service-boleto, and distinct from the charge being paid — settlement is when the funds clear.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "BOLETO_SETTLED"
object
object

Responses

Request samples

Content type
application/json
{
  • "event": "BOLETO_SETTLED",
  • "charge": {
    },
  • "boleto": {
    }
}

Charge created Webhook

A charge was created.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "OPENPIX:CHARGE_CREATED"
object (WebhookCharge)

The charge the event refers to. Superset of the fields observed across the charge and transaction events; a given event carries the subset that applies to it.

object
object

Responses

Request samples

Content type
application/json
{
  • "event": "OPENPIX:CHARGE_CREATED",
  • "charge": {
    },
  • "company": {
    },
  • "account": {
    }
}

Charge completed Webhook

A charge was paid in full.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "OPENPIX:CHARGE_COMPLETED"
object (WebhookCharge)

The charge the event refers to. Superset of the fields observed across the charge and transaction events; a given event carries the subset that applies to it.

object
object
object

Responses

Request samples

Content type
application/json
{
  • "event": "OPENPIX:CHARGE_COMPLETED",
  • "charge": {
    },
  • "pix": {
    },
  • "company": {
    },
  • "account": {
    }
}

Charge expired Webhook

A charge reached its expiration without being paid in full.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "OPENPIX:CHARGE_EXPIRED"
object (WebhookCharge)

The charge the event refers to. Superset of the fields observed across the charge and transaction events; a given event carries the subset that applies to it.

object
object

Responses

Request samples

Content type
application/json
{
  • "event": "OPENPIX:CHARGE_EXPIRED",
  • "charge": {
    },
  • "company": {
    },
  • "account": {
    }
}

Charge completed by another payer Webhook

A charge was paid by a payer whose taxID differs from the charge customer. Only sent when the charge does not enforce the same taxID.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "OPENPIX:CHARGE_COMPLETED_NOT_SAME_CUSTOMER_PAYER"
object (WebhookCharge)

The charge the event refers to. Superset of the fields observed across the charge and transaction events; a given event carries the subset that applies to it.

object
object
object
object

Responses

Request samples

Content type
application/json
{
  • "event": "OPENPIX:CHARGE_COMPLETED_NOT_SAME_CUSTOMER_PAYER",
  • "charge": {
    },
  • "pix": {
    },
  • "company": {
    },
  • "account": {
    },
  • "payer": {
    }
}

Dispute created Webhook

A MED dispute was opened against a transaction of this account.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "OPENPIX:DISPUTE_CREATED"
object

Responses

Request samples

Content type
application/json
{
  • "event": "OPENPIX:DISPUTE_CREATED",
  • "dispute": {
    }
}

Dispute accepted Webhook

A MED dispute was accepted and the amount is returned to the payer.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "OPENPIX:DISPUTE_ACCEPTED"
object

Responses

Request samples

Content type
application/json
{
  • "event": "OPENPIX:DISPUTE_ACCEPTED",
  • "dispute": {
    }
}

Dispute rejected Webhook

A MED dispute was rejected and the amount stays with this account.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "OPENPIX:DISPUTE_REJECTED"
object

Responses

Request samples

Content type
application/json
{
  • "event": "OPENPIX:DISPUTE_REJECTED",
  • "dispute": {
    }
}

Dispute canceled Webhook

A MED dispute was canceled by the reporting institution.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "OPENPIX:DISPUTE_CANCELED"
object

Responses

Request samples

Content type
application/json
{
  • "event": "OPENPIX:DISPUTE_CANCELED",
  • "dispute": {
    }
}

Payment confirmed Webhook

An outbound payment was confirmed and the Pix left the account.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "OPENPIX:MOVEMENT_CONFIRMED"
object
object

Responses

Request samples

Content type
application/json
{
  • "event": "OPENPIX:MOVEMENT_CONFIRMED",
  • "payment": {
    },
  • "transaction": {
    }
}

Payment failed Webhook

An outbound payment was approved but failed on the way out. error carries the reason.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "OPENPIX:MOVEMENT_FAILED"
object
object
object

Responses

Request samples

Content type
application/json
{
  • "event": "OPENPIX:MOVEMENT_FAILED",
  • "payment": {
    },
  • "transaction": {
    },
  • "error": {
    }
}

Payment removed Webhook

An outbound payment was removed before being approved.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "OPENPIX:MOVEMENT_REMOVED"
object

Responses

Request samples

Content type
application/json
{
  • "event": "OPENPIX:MOVEMENT_REMOVED",
  • "payment": {
    }
}

Pix Automatic mandate approved Webhook

The payer's bank approved the recurring mandate.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "PIX_AUTOMATIC_APPROVED"
object
dayGenerateCharge
integer
value
integer
status
string
correlationID
string
object
globalID
string

Responses

Request samples

Content type
application/json
{
  • "event": "PIX_AUTOMATIC_APPROVED",
  • "customer": {
    },
  • "dayGenerateCharge": 24,
  • "value": 100,
  • "status": "ACTIVE",
  • "correlationID": "UniqueID1344445457t11653453223241",
  • "pixRecurring": {
    },
  • "globalID": "UGF5bWVudFN1YnNjcmlwdGlvbjo2OGE4ODMyMWQ2NWNiMmQ1MDdhMmVlMjk="
}

Pix Automatic mandate rejected Webhook

The payer rejected the recurring mandate.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "PIX_AUTOMATIC_REJECTED"
object
dayGenerateCharge
integer
value
integer
status
string
correlationID
string
object
globalID
string

Responses

Request samples

Content type
application/json
{
  • "event": "PIX_AUTOMATIC_REJECTED",
  • "customer": {
    },
  • "dayGenerateCharge": 24,
  • "value": 100,
  • "status": "INACTIVE",
  • "correlationID": "UniqueID1344445457t11653453223241",
  • "pixRecurring": {
    },
  • "globalID": "UGF5bWVudFN1YnNjcmlwdGlvbjo2OGE4ODMyMWQ2NWNiMmQ1MDdhMmVlMjk="
}

Pix Automatic cobr created Webhook

A recurring charge was created for an installment of the mandate.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "PIX_AUTOMATIC_COBR_CREATED"
dateGenerateCharge
string
expiration
integer
installmentNumber
integer
value
integer
status
string
createdAt
string
object
correlationID
string
paymentSubscriptionGlobalID
string
globalID
string

Responses

Request samples

Content type
application/json
{
  • "event": "PIX_AUTOMATIC_COBR_CREATED",
  • "dateGenerateCharge": "2025-08-24T12:00:00.000Z",
  • "expiration": 259200,
  • "installmentNumber": 1,
  • "value": 100,
  • "status": "SCHEDULED",
  • "createdAt": "2025-08-22T14:48:02.697Z",
  • "cobr": {
    },
  • "correlationID": "9134e286-6f71-427a-bf00-100000000005",
  • "paymentSubscriptionGlobalID": "UGF5bWVudFN1YnNjcmlwdGlvbjo2OGFjYmNkNGE5NTY1M2VmMjQzYjY2Zjc=",
  • "globalID": "UGF5bWVudFN1YnNjcmlwdGlvbkluc3RhbGxtZW50OjY4YTg4MzIyZDY1Y2IyZDUwN2EyZWUzYg=="
}

Pix Automatic cobr approved Webhook

The payer's bank approved the recurring charge.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "PIX_AUTOMATIC_COBR_APPROVED"
dateGenerateCharge
string
expiration
integer
installmentNumber
integer
value
integer
status
string
createdAt
string
object
correlationID
string
paymentSubscriptionGlobalID
string
globalID
string

Responses

Request samples

Content type
application/json
{
  • "event": "PIX_AUTOMATIC_COBR_APPROVED",
  • "dateGenerateCharge": "2025-08-24T12:00:00.000Z",
  • "expiration": 259200,
  • "installmentNumber": 1,
  • "value": 100,
  • "status": "ACTIVE",
  • "createdAt": "2025-08-22T14:48:02.697Z",
  • "cobr": {
    },
  • "correlationID": "9134e286-6f71-427a-bf00-100000000005",
  • "paymentSubscriptionGlobalID": "UGF5bWVudFN1YnNjcmlwdGlvbjo2OGFjYmNkNGE5NTY1M2VmMjQzYjY2Zjc=",
  • "globalID": "UGF5bWVudFN1YnNjcmlwdGlvbkluc3RhbGxtZW50OjY4YTg4MzIyZDY1Y2IyZDUwN2EyZWUzYg=="
}

Pix Automatic cobr rejected Webhook

The payer's bank rejected the recurring charge.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "PIX_AUTOMATIC_COBR_REJECTED"
dateGenerateCharge
string
expiration
integer
installmentNumber
integer
value
integer
status
string
createdAt
string
object
correlationID
string
paymentSubscriptionGlobalID
string
globalID
string

Responses

Request samples

Content type
application/json
{
  • "event": "PIX_AUTOMATIC_COBR_REJECTED",
  • "dateGenerateCharge": "2025-08-24T12:00:00.000Z",
  • "expiration": 259200,
  • "installmentNumber": 1,
  • "value": 100,
  • "status": "CANCEL",
  • "createdAt": "2025-08-22T14:48:02.697Z",
  • "cobr": {
    },
  • "correlationID": "9134e286-6f71-427a-bf00-100000000005",
  • "paymentSubscriptionGlobalID": "UGF5bWVudFN1YnNjcmlwdGlvbjo2OGFjYmNkNGE5NTY1M2VmMjQzYjY2Zjc=",
  • "globalID": "UGF5bWVudFN1YnNjcmlwdGlvbkluc3RhbGxtZW50OjY4YTg4MzIyZDY1Y2IyZDUwN2EyZWUzYg=="
}

Pix Automatic cobr completed Webhook

A recurring charge was paid.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "PIX_AUTOMATIC_COBR_COMPLETED"
dateGenerateCharge
string
expiration
integer
installmentNumber
integer
value
integer
status
string
createdAt
string
object
correlationID
string
paymentSubscriptionGlobalID
string
globalID
string

Responses

Request samples

Content type
application/json
{
  • "event": "PIX_AUTOMATIC_COBR_COMPLETED",
  • "dateGenerateCharge": "2025-08-24T12:00:00.000Z",
  • "expiration": 259200,
  • "installmentNumber": 1,
  • "value": 100,
  • "status": "COMPLETED",
  • "createdAt": "2025-08-22T14:48:02.697Z",
  • "cobr": {
    },
  • "correlationID": "9134e286-6f71-427a-bf00-100000000005",
  • "paymentSubscriptionGlobalID": "UGF5bWVudFN1YnNjcmlwdGlvbjo2OGFjYmNkNGE5NTY1M2VmMjQzYjY2Zjc=",
  • "globalID": "UGF5bWVudFN1YnNjcmlwdGlvbkluc3RhbGxtZW50OjY4YTg4MzIyZDY1Y2IyZDUwN2EyZWUzYg=="
}

Pix Automatic cobr retry requested Webhook

A new attempt was requested for a recurring charge.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "PIX_AUTOMATIC_COBR_TRY_REQUESTED"
dateGenerateCharge
string
expiration
integer
installmentNumber
integer
value
integer
status
string
createdAt
string
object
correlationID
string
paymentSubscriptionGlobalID
string
globalID
string

Responses

Request samples

Content type
application/json
{
  • "event": "PIX_AUTOMATIC_COBR_TRY_REQUESTED",
  • "dateGenerateCharge": "2025-09-05T12:00:00.000Z",
  • "expiration": 1209600,
  • "installmentNumber": 2,
  • "value": 1,
  • "status": "SCHEDULED",
  • "createdAt": "2025-09-04T03:00:20.372Z",
  • "cobr": {
    },
  • "correlationID": "9134e286-6f71-427a-bf00-100000000005",
  • "paymentSubscriptionGlobalID": "UGF5bWVudFN1YnNjcmlwdGlvbjo2ODlhNTA1NmVjY2NkZTViMzdmYzE0MDE=",
  • "globalID": "UGF5bWVudFN1YnNjcmlwdGlvbkluc3RhbGxtZW50OjY4YjkwMGM0ZDE5ZTBlY2QwMmQ2NzViMg=="
}

Pix Automatic cobr retry rejected Webhook

The payer's bank rejected the retry.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "PIX_AUTOMATIC_COBR_TRY_REJECTED"
dateGenerateCharge
string
expiration
integer
installmentNumber
integer
value
integer
status
string
createdAt
string
object
correlationID
string
paymentSubscriptionGlobalID
string
globalID
string

Responses

Request samples

Content type
application/json
{
  • "event": "PIX_AUTOMATIC_COBR_TRY_REJECTED",
  • "dateGenerateCharge": "2025-09-05T12:00:00.000Z",
  • "expiration": 1209600,
  • "installmentNumber": 2,
  • "value": 1,
  • "status": "CANCELED",
  • "createdAt": "2025-09-04T03:00:20.372Z",
  • "cobr": {
    },
  • "correlationID": "9134e286-6f71-427a-bf00-100000000005",
  • "paymentSubscriptionGlobalID": "UGF5bWVudFN1YnNjcmlwdGlvbjo2ODlhNTA1NmVjY2NkZTViMzdmYzE0MDE=",
  • "globalID": "UGF5bWVudFN1YnNjcmlwdGlvbkluc3RhbGxtZW50OjY4YjkwMGM0ZDE5ZTBlY2QwMmQ2NzViMg=="
}

Refund received confirmed Webhook

A refund credited to this account was confirmed.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "PIX_TRANSACTION_REFUND_RECEIVED_CONFIRMED"
object
object
object
object

Responses

Request samples

Content type
application/json
{
  • "event": "PIX_TRANSACTION_REFUND_RECEIVED_CONFIRMED",
  • "refundTransaction": {
    },
  • "originalTransaction": {
    },
  • "company": {
    },
  • "account": {
    }
}

Refund received rejected Webhook

A refund credited to this account was rejected. error carries the reason.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "PIX_TRANSACTION_REFUND_RECEIVED_REJECTED"
object
object
object
object
error
string

Responses

Request samples

Content type
application/json
{
  • "event": "PIX_TRANSACTION_REFUND_RECEIVED_REJECTED",
  • "refundTransaction": {
    },
  • "originalTransaction": {
    },
  • "company": {
    },
  • "account": {
    },
  • "error": "AC06 - Conta bloqueada do Pix"
}

Refund sent confirmed Webhook

A refund this account sent was confirmed.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "PIX_TRANSACTION_REFUND_SENT_CONFIRMED"
object
object
object
object

Responses

Request samples

Content type
application/json
{
  • "event": "PIX_TRANSACTION_REFUND_SENT_CONFIRMED",
  • "refundTransaction": {
    },
  • "originalTransaction": {
    },
  • "company": {
    },
  • "account": {
    }
}

Refund sent rejected Webhook

A refund this account sent was rejected. error carries the reason.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "PIX_TRANSACTION_REFUND_SENT_REJECTED"
object
object
object
object
error
string

Responses

Request samples

Content type
application/json
{
  • "event": "PIX_TRANSACTION_REFUND_SENT_REJECTED",
  • "refundTransaction": {
    },
  • "originalTransaction": {
    },
  • "company": {
    },
  • "account": {
    },
  • "error": "ED05 - Pagamento rejeitado pelo PSP do recebedor"
}

Stablecoin deposit completed Webhook

A stablecoin deposit settled. Emitted by woovi-stablecoin.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "STABLECOIN_DEPOSIT_COMPLETED"
object
object

Public company info.

Responses

Request samples

Content type
application/json
{
  • "event": "STABLECOIN_DEPOSIT_COMPLETED",
  • "stableDeposit": {
    },
  • "company": {
    }
}

Stablecoin deposit failed Webhook

A stablecoin deposit did not settle. reason always comes; errorCode only when the provider gave one.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "STABLECOIN_DEPOSIT_FAILED"
object
object

Public company info.

reason
string
errorCode
string

Responses

Request samples

Content type
application/json
{
  • "event": "STABLECOIN_DEPOSIT_FAILED",
  • "stableDeposit": {
    },
  • "company": {
    },
  • "reason": "quote expired before settlement",
  • "errorCode": "QUOTE_EXPIRED"
}

Stablecoin payout completed Webhook

A stablecoin payout was paid out over Pix. Emitted by woovi-stablecoin.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "STABLECOIN_PAYOUT_COMPLETED"
object
object

Public company info.

Responses

Request samples

Content type
application/json
{
  • "event": "STABLECOIN_PAYOUT_COMPLETED",
  • "stablePayout": {
    },
  • "company": {
    }
}

Stablecoin payout failed Webhook

A stablecoin payout did not go out.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "STABLECOIN_PAYOUT_FAILED"
object
object

Public company info.

reason
string
errorCode
string

Responses

Request samples

Content type
application/json
{
  • "event": "STABLECOIN_PAYOUT_FAILED",
  • "stablePayout": {
    },
  • "company": {
    },
  • "reason": "pix key not found"
}

Stablecoin payout refund confirmed Webhook

A settled stablecoin payout was returned and the funds are available again in your stablecoin balance — safe to refund your end customer. stablePayout.status stays COMPLETED: the Pix did leave, so the return is reported under refund instead of rolling the status back. refund.providerTicketId is the return's own ticket and is the idempotency key; refund.amount is in cents of refund.currency (the input asset), never the BRL outputAmount.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "STABLECOIN_PAYOUT_REFUND_CONFIRMED"
object
object

Public company info.

object

The returned money, as reported by the provider.

Responses

Request samples

Content type
application/json
{
  • "event": "STABLECOIN_PAYOUT_REFUND_CONFIRMED",
  • "stablePayout": {
    },
  • "company": {
    },
  • "refund": {
    }
}

Stablecoin payout refund failed Webhook

A settled stablecoin payout was returned but the funds are not available to you — do not credit your end customer, this needs reconciliation. Either the return leg itself did not land, or the credit is not withdrawable from your sub-account; refund.failureReason says which, and refund.destination is NONE when the money was not credited to the sub-account balance.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "STABLECOIN_PAYOUT_REFUND_FAILED"
object
object

Public company info.

object

The returned money, as reported by the provider.

Responses

Request samples

Content type
application/json
{
  • "event": "STABLECOIN_PAYOUT_REFUND_FAILED",
  • "stablePayout": {
    },
  • "company": {
    },
  • "refund": {
    }
}

Stablecoin sub-account confirmed Webhook

A stablecoin sub-account cleared onboarding and can transact.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "STABLECOIN_SUBACCOUNT_CONFIRMED"
object
object

Public company info.

Responses

Request samples

Content type
application/json
{
  • "event": "STABLECOIN_SUBACCOUNT_CONFIRMED",
  • "stableSubAccount": {
    },
  • "company": {
    }
}

Stablecoin sub-account rejected Webhook

A stablecoin sub-account was rejected. rejectionLabels carries the compliance labels when there are any.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "STABLECOIN_SUBACCOUNT_REJECTED"
object
object

Public company info.

reason
string
rejectionLabels
Array of strings

Responses

Request samples

Content type
application/json
{
  • "event": "STABLECOIN_SUBACCOUNT_REJECTED",
  • "stableSubAccount": {
    },
  • "company": {
    },
  • "reason": "document mismatch",
  • "rejectionLabels": [
    ]
}

Pix received Webhook

A Pix credit was received, either against a charge or against a static QR code. charge and pixQrCode are null when the Pix arrived with neither.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "OPENPIX:TRANSACTION_RECEIVED"
WebhookCharge (object) or null
PixQrCode (object) or null
object
object
object
Array of objects (Refund)

Responses

Request samples

Content type
application/json
{
  • "event": "OPENPIX:TRANSACTION_RECEIVED",
  • "charge": null,
  • "pixQrCode": null,
  • "pix": {
    },
  • "company": {
    },
  • "account": {
    },
  • "refunds": [ ]
}

Pix refund received (deprecated) Webhook

Superseded by the PIX_TRANSACTION_REFUND_* events, which report the refund leg and its outcome separately.

Authorizations:
AppID
Request Body schema: application/json
required
event
required
string
Value: "OPENPIX:TRANSACTION_REFUND_RECEIVED"
object (WebhookCharge)

The charge the event refers to. Superset of the fields observed across the charge and transaction events; a given event carries the subset that applies to it.

PixQrCode (object) or null
object
object
object
Array of objects (Refund)

Responses

Request samples

Content type
application/json
{
  • "event": "OPENPIX:TRANSACTION_REFUND_RECEIVED",
  • "charge": {
    },
  • "pixQrCode": null,
  • "pix": {
    },
  • "company": {
    },
  • "account": {
    },
  • "refunds": [ ]
}

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.woovi.com',
  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.woovi.com',
  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" "ACCOUNT_REGISTER_STEP_UPDATED" "ACCOUNT_REGISTER_IN_REVIEW" "ACCOUNT_REGISTER_DOCUMENTS_REQUESTED" "ACCOUNT_REGISTER_RFI_RESOLVED" "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" "COMPANY_BANK_ACCOUNT_BLOCKED" "STABLECOIN_DEPOSIT_COMPLETED" "STABLECOIN_DEPOSIT_FAILED" "STABLECOIN_PAYOUT_COMPLETED" "STABLECOIN_PAYOUT_FAILED" "STABLECOIN_PAYOUT_REFUND_CONFIRMED" "STABLECOIN_PAYOUT_REFUND_FAILED" "STABLECOIN_SUBACCOUNT_CONFIRMED" "STABLECOIN_SUBACCOUNT_REJECTED" "BOLETO_SETTLED" "KYC_VALIDATION_COMPLETED" "KYC_VALIDATION_FAILED"

The event to listen to. If omitted, the webhook will be registered to listen the OPENPIX:TRANSACTION_RECEIVED. Event called when a new pix transactions is received

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.woovi.com',
  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.woovi.com',
  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": [
    ]
}

Get the public keys that verify the webhook signature

Retorna a chave pública usada para verificar o header x-webhook-signature, presente em todo webhook enviado pela Woovi.

A assinatura é base64(RSA-SHA256) sobre o corpo bruto da request — verifique antes de fazer parse do JSON, porque reserializar muda os bytes e invalida a assinatura.

Este endpoint não exige autenticação: a chave é pública por definição, e quem recebe webhook normalmente valida a assinatura em um contexto que não tem o AppID em mãos.

A resposta é uma lista, e não uma chave só, para permitir rotação: durante uma troca de chave publicamos a antiga e a nova ao mesmo tempo, com is_current indicando qual está assinando agora. Aceite qualquer chave da lista ao verificar e você não quebra quando a rotação acontecer.

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.woovi.com',
  port: null,
  path: '/api/v1/webhook/public-keys',
  headers: {}
};

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
{
  • "public_keys": [
    ]
}

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.woovi.com',
  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.woovi.com',
  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.woovi.com',
  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
companyBankAccount
string
Example: companyBankAccount=507f1f77bcf86cd799439011

Read the statement of another bank account of your company instead of the one linked to the appID. Only a MASTER application of a company with the MASTER_APP_READ_ANY_ACCOUNT feature can use it. Use the accountId returned by GET /api/v1/account.

Responses

Request samples 

const http = require('https');

const options = {
  method: 'GET',
  hostname: 'api.woovi.com',
  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&companyBankAccount=507f1f77bcf86cd799439011',
  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
[
  • {
    }
]