Ir para o conteúdo
Docs

Saques

Envie saques PIX a partir do saldo disponível, consulte e liste saques.

O objeto saque

Um saque envia dinheiro do saldo disponível para uma chave PIX. O valor fica reservado enquanto o saque está pending.

Campos

  • idstring

    Identificador do saque na MaxxiPay.

  • objectstring
    sempre "payout"
  • statusenum

    Situação atual do saque.

    reviewpendingpaidcanceledfailed
  • railstring
    sempre "pix"
  • amountCentsinteger

    Valor do saque em centavos.

  • currencystring
    sempre "BRL"
  • pixKeystring · pode ser nulo
  • pixKeyTypeenum · pode ser nulo
    CPFCNPJEMAILPHONEEVP
  • namestring · pode ser nulo

    Nome do titular da chave de destino.

  • documentNumberstring · pode ser nulo

    CPF ou CNPJ do titular, só dígitos.

  • externalIdstring · pode ser nulo
  • metadataobject · texto → texto
  • failureReasonstring · pode ser nulo
  • createdAtstring · ISO 8601
  • updatedAtstring · ISO 8601
ExemploJSON
{
  "id": "a41e7c3b-55d2-4f0e-8b19-7c2d6e0f9a31",
  "object": "payout",
  "status": "paid",
  "rail": "pix",
  "amountCents": 150000,
  "currency": "BRL",
  "pixKey": "financeiro@empresa.com.br",
  "pixKeyType": "EMAIL",
  "name": "Empresa Exemplo Ltda",
  "documentNumber": "11222333000181",
  "externalId": "repasse-2026-11",
  "metadata": {},
  "failureReason": null,
  "createdAt": "2026-11-02T18:20:00.000Z",
  "updatedAt": "2026-11-02T18:20:09.000Z"
}

Criar um saque

POST/v1/payouts

Envia um saque PIX a partir do saldo disponível. O valor fica reservado até a confirmação.

Escopo
payouts:write
Idempotency-Key
Obrigatório
Sucesso
201

Exige o escopo payouts:write: marque Criar saques ao criar a chave em Desenvolvedor › Credenciais. Só rail: "pix" é aceito.

Corpo da requisição

  • railstringobrigatório

    Trilho do saque. Use pix.

    sempre "pix"
  • amountCentsintegerobrigatório

    Valor do saque em centavos, debitado do saldo disponível.

    maior que 0máximo 5.000.000.000
  • pixKeystringobrigatório

    Chave PIX de destino.

    1 a 140 caracteres
  • pixKeyTypeenumobrigatório

    Tipo da chave PIX: CPF, CNPJ, EMAIL, PHONE ou EVP (aleatória).

    CPFCNPJEMAILPHONEEVP
  • documentNumberstringobrigatório

    CPF ou CNPJ do titular da chave.

  • namestringobrigatório

    Nome do titular da chave.

    3 a 120 caracteres
  • externalIdstringopcional

    Identificador do seu sistema, como o número do pedido. Serve para conciliação e para filtrar listas.

    1 a 100 caracteres
  • metadataobject · texto → textoopcional

    Pares chave e valor de texto guardados com o recurso e devolvidos nas respostas e webhooks. Até 20 chaves.

    chaves até 40 caracteresvalores até 500 caracteres

Resposta

Devolve o objeto saque com status pending.

Erros desta rota

  • 400idempotency_key_requiredFaltou o cabeçalho Idempotency-Key ou ele tem menos de 8 ou mais de 120 caracteres.
  • 422invalid_bodyUm campo do corpo não passou na validação. O campo vem em error.field.
  • 403account_not_verifiedA conta ainda não foi verificada. Cobranças e saques ficam bloqueados até a aprovação.
  • 403merchant_blockedA conta está bloqueada. Cobranças e saques estão suspensos.
  • 422insufficient_balanceO saldo disponível não cobre o saque.
  • 422limit_per_payoutO valor passa do máximo por saque da conta. O padrão é R$ 10.000,00 e o valor em vigor vem em error.message.
  • 409idempotency_conflictA Idempotency-Key já foi usada com outro conteúdo.
  • 502processing_failedO processamento PIX recusou a operação. O motivo vem em error.message e em failureReason.

Exemplo de retorno, pelo contrato da rota. Não cria cobrança nem saque.

const response = await fetch("https://api.maxxipay.com/v1/payouts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAXXIPAY_API_KEY}`,
    "Idempotency-Key": "repasse-2026-11",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    rail: "pix",
    amountCents: 150000,
    pixKey: "financeiro@empresa.com.br",
    pixKeyType: "EMAIL",
    documentNumber: "11.222.333/0001-81",
    name: "Empresa Exemplo Ltda",
    externalId: "repasse-2026-11"
  }),
});

const payout = await response.json();
RespostaJSON201 Created
{
  "id": "a41e7c3b-55d2-4f0e-8b19-7c2d6e0f9a31",
  "object": "payout",
  "status": "pending",
  "rail": "pix",
  "amountCents": 150000,
  "currency": "BRL",
  "pixKey": "financeiro@empresa.com.br",
  "pixKeyType": "EMAIL",
  "name": "Empresa Exemplo Ltda",
  "documentNumber": "11222333000181",
  "externalId": "repasse-2026-11",
  "metadata": {},
  "failureReason": null,
  "createdAt": "2026-11-02T18:20:00.000Z",
  "updatedAt": "2026-11-02T18:20:00.000Z"
}

Consultar um saque

GET/v1/payouts/{id}

Busca um saque pelo identificador.

Escopo
payouts:read
Idempotency-Key
Não se aplica
Sucesso
200

Parâmetros de caminho

  • idstringobrigatório

    Identificador do saque.

Resposta

Devolve o objeto saque.

Erros desta rota

  • 404not_foundO recurso não existe ou pertence a outra empresa.

Exemplo de retorno, pelo contrato da rota. Não cria cobrança nem saque.

const response = await fetch("https://api.maxxipay.com/v1/payouts/a41e7c3b-55d2-4f0e-8b19-7c2d6e0f9a31", {
  headers: {
    Authorization: `Bearer ${process.env.MAXXIPAY_API_KEY}`,
  },
});

const payout = await response.json();
RespostaJSON200 OK
{
  "id": "a41e7c3b-55d2-4f0e-8b19-7c2d6e0f9a31",
  "object": "payout",
  "status": "paid",
  "rail": "pix",
  "amountCents": 150000,
  "currency": "BRL",
  "pixKey": "financeiro@empresa.com.br",
  "pixKeyType": "EMAIL",
  "name": "Empresa Exemplo Ltda",
  "documentNumber": "11222333000181",
  "externalId": "repasse-2026-11",
  "metadata": {},
  "failureReason": null,
  "createdAt": "2026-11-02T18:20:00.000Z",
  "updatedAt": "2026-11-02T18:20:09.000Z"
}

Listar saques

GET/v1/payouts

Lista os saques da empresa do mais recente para o mais antigo, com filtros e paginação por cursor.

Escopo
payouts:read
Idempotency-Key
Não se aplica
Sucesso
200

Parâmetros de consulta

  • limitintegeropcional

    Quantidade de itens por página, de 1 a 100. Padrão 20.

    mínimo 1máximo 100padrão 20
  • cursorstringopcional

    Valor de nextCursor da página anterior. Omita para começar do item mais recente.

    1 a 200 caracteres
  • statusenumopcional

    Filtra pelo status do saque.

    reviewpendingpaidcanceledfailed
  • externalIdstringopcional

    Filtra pelo externalId informado na criação.

    1 a 100 caracteres
  • createdFromstring · ISO 8601opcional

    Inclui só itens criados a partir deste instante (ISO 8601).

  • createdTostring · ISO 8601opcional

    Inclui só itens criados antes deste instante (ISO 8601).

Resposta

Devolve uma lista paginada de objetos saque.

Erros desta rota

  • 422invalid_queryUm parâmetro de consulta é inválido. O parâmetro vem em error.field.
  • 422invalid_cursorO cursor não foi gerado pela API.

Exemplo de retorno, pelo contrato da rota. Não cria cobrança nem saque.

const response = await fetch("https://api.maxxipay.com/v1/payouts?limit=20", {
  headers: {
    Authorization: `Bearer ${process.env.MAXXIPAY_API_KEY}`,
  },
});

const page = await response.json();
RespostaJSON200 OK
{
  "object": "list",
  "data": [
    {
      "id": "a41e7c3b-55d2-4f0e-8b19-7c2d6e0f9a31",
      "object": "payout",
      "status": "paid",
      "rail": "pix",
      "amountCents": 150000,
      "currency": "BRL",
      "pixKey": "financeiro@empresa.com.br",
      "pixKeyType": "EMAIL",
      "name": "Empresa Exemplo Ltda",
      "documentNumber": "11222333000181",
      "externalId": "repasse-2026-11",
      "metadata": {},
      "failureReason": null,
      "createdAt": "2026-11-02T18:20:00.000Z",
      "updatedAt": "2026-11-02T18:20:09.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
esc