Atualizar recebedor

curl --request PATCH \
  --url https://api.sandbox.z2pay.com/v1/recipients/{id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "email": "jsmith@example.com",
  "phone": "<string>",
  "companyType": "<string>",
  "companyLegalName": "<string>",
  "companyFoundingDate": "<string>",
  "annualRevenue": 50000000000000,
  "corporationType": "<string>",
  "birthDate": "<string>",
  "motherName": "<string>",
  "profession": "<string>",
  "monthlyIncome": 50000000000000,
  "legalRepresentativeInfo": {
    "name": "<string>",
    "document": "<string>",
    "email": "jsmith@example.com",
    "motherName": "<string>",
    "birthdate": "<string>",
    "monthlyIncome": 50000000000000,
    "profession": "<string>",
    "phone": "<string>",
    "selfDeclaredRepresentative": true
  },
  "pixKeyType": "<string>",
  "pixKey": "<string>",
  "website": "<string>",
  "address": {
    "address": "<string>",
    "number": "<string>",
    "complement": "<string>",
    "neighborhood": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postalCode": "<string>",
    "referencePoint": "<string>"
  },
  "files": {
    "identificationDocument": "<string>",
    "selfie": "<string>",
    "addressProof": "<string>",
    "socialContract": "<string>",
    "powerOfAttorney": "<string>"
  }
}
'

const options = {
  method: 'PATCH',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    email: 'jsmith@example.com',
    phone: '<string>',
    companyType: '<string>',
    companyLegalName: '<string>',
    companyFoundingDate: '<string>',
    annualRevenue: 50000000000000,
    corporationType: '<string>',
    birthDate: '<string>',
    motherName: '<string>',
    profession: '<string>',
    monthlyIncome: 50000000000000,
    legalRepresentativeInfo: {
      name: '<string>',
      document: '<string>',
      email: 'jsmith@example.com',
      motherName: '<string>',
      birthdate: '<string>',
      monthlyIncome: 50000000000000,
      profession: '<string>',
      phone: '<string>',
      selfDeclaredRepresentative: true
    },
    pixKeyType: '<string>',
    pixKey: '<string>',
    website: '<string>',
    address: {
      address: '<string>',
      number: '<string>',
      complement: '<string>',
      neighborhood: '<string>',
      city: '<string>',
      state: '<string>',
      postalCode: '<string>',
      referencePoint: '<string>'
    },
    files: {
      identificationDocument: '<string>',
      selfie: '<string>',
      addressProof: '<string>',
      socialContract: '<string>',
      powerOfAttorney: '<string>'
    }
  })
};

fetch('https://api.sandbox.z2pay.com/v1/recipients/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.sandbox.z2pay.com/v1/recipients/{id}"

payload = {
    "name": "<string>",
    "email": "jsmith@example.com",
    "phone": "<string>",
    "companyType": "<string>",
    "companyLegalName": "<string>",
    "companyFoundingDate": "<string>",
    "annualRevenue": 50000000000000,
    "corporationType": "<string>",
    "birthDate": "<string>",
    "motherName": "<string>",
    "profession": "<string>",
    "monthlyIncome": 50000000000000,
    "legalRepresentativeInfo": {
        "name": "<string>",
        "document": "<string>",
        "email": "jsmith@example.com",
        "motherName": "<string>",
        "birthdate": "<string>",
        "monthlyIncome": 50000000000000,
        "profession": "<string>",
        "phone": "<string>",
        "selfDeclaredRepresentative": True
    },
    "pixKeyType": "<string>",
    "pixKey": "<string>",
    "website": "<string>",
    "address": {
        "address": "<string>",
        "number": "<string>",
        "complement": "<string>",
        "neighborhood": "<string>",
        "city": "<string>",
        "state": "<string>",
        "postalCode": "<string>",
        "referencePoint": "<string>"
    },
    "files": {
        "identificationDocument": "<string>",
        "selfie": "<string>",
        "addressProof": "<string>",
        "socialContract": "<string>",
        "powerOfAttorney": "<string>"
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

{
  "id": "rec_gk1o75xv3ioi4eoqosorz9s62",
  "accountName": "Loja do Joao",
  "name": "Joao da Silva",
  "email": "joao.silva@example.com",
  "phone": "+5511987654321",
  "document": "12345678901",
  "type": "individual",
  "companyType": null,
  "companyLegalName": null,
  "companyFoundingDate": null,
  "annualRevenue": null,
  "corporationType": null,
  "birthDate": "1990-04-12T00:00:00.000Z",
  "motherName": "Maria da Silva",
  "profession": "Comerciante",
  "monthlyIncome": 850000,
  "legalRepresentativeInfo": null,
  "pixKeyType": "email",
  "pixKey": "joao.silva@example.com",
  "website": "https://lojadojoao.com.br",
  "mainAddress": {
    "id": "radr_n5t8wqz2mxk9rpf4hc7ydv3bj",
    "recipientId": "rec_gk1o75xv3ioi4eoqosorz9s62",
    "address": "Rua das Flores",
    "number": "123",
    "complement": "Apto 45",
    "neighborhood": "Centro",
    "city": "Sao Paulo",
    "state": "SP",
    "postalCode": "01001000",
    "referencePoint": null,
    "isMain": true,
    "isActive": true
  },
  "defaultBankAccount": {
    "id": "rba_bg9eddocogegc2pbjyexzd104",
    "recipientId": "rec_gk1o75xv3ioi4eoqosorz9s62",
    "status": "active",
    "bankHolderName": "Joao da Silva",
    "bankHolderDocument": "12345678901",
    "bankHolderType": "individual",
    "bankCode": "341",
    "bankName": "Itau Unibanco",
    "bankAgency": "1234",
    "bankAccount": "567890",
    "bankAccountDigit": "1",
    "bankAccountType": "checking"
  },
  "documents": [],
  "role": "seller",
  "status": "active",
  "splitValue": 10,
  "splitType": "percentage",
  "pixAntecipationDays": null,
  "bankSlipAntecipationDays": null,
  "creditCardAntecipationDays": null,
  "approvedAt": "2025-06-20T14:30:00.000Z",
  "refusedAt": null,
  "analysisComplete": true,
  "pendencies": [],
  "pendenciesSummary": {
    "open": 0,
    "blocking": 0,
    "warning": 0
  },
  "createdAt": "2025-06-18T09:15:00.000Z",
  "updatedAt": "2025-06-20T14:30:00.000Z"
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "issues": [
      {
        "path": "status",
        "message": "Status inválido. Valores aceitos: pending, waiting_payment, paid, refused, canceled, refunded"
      },
      {
        "path": "startDate",
        "message": "Data deve ser ISO 8601 com timezone (ex.: 2026-06-24T00:00:00Z)"
      }
    ]
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

{
  "error": "A request with this idempotency key is already being processed"
}

{
  "error": "Idempotency key already used with a different request body"
}

PATCH

recipients

{id}

Atualizar recebedor

curl --request PATCH \
  --url https://api.sandbox.z2pay.com/v1/recipients/{id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "email": "jsmith@example.com",
  "phone": "<string>",
  "companyType": "<string>",
  "companyLegalName": "<string>",
  "companyFoundingDate": "<string>",
  "annualRevenue": 50000000000000,
  "corporationType": "<string>",
  "birthDate": "<string>",
  "motherName": "<string>",
  "profession": "<string>",
  "monthlyIncome": 50000000000000,
  "legalRepresentativeInfo": {
    "name": "<string>",
    "document": "<string>",
    "email": "jsmith@example.com",
    "motherName": "<string>",
    "birthdate": "<string>",
    "monthlyIncome": 50000000000000,
    "profession": "<string>",
    "phone": "<string>",
    "selfDeclaredRepresentative": true
  },
  "pixKeyType": "<string>",
  "pixKey": "<string>",
  "website": "<string>",
  "address": {
    "address": "<string>",
    "number": "<string>",
    "complement": "<string>",
    "neighborhood": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postalCode": "<string>",
    "referencePoint": "<string>"
  },
  "files": {
    "identificationDocument": "<string>",
    "selfie": "<string>",
    "addressProof": "<string>",
    "socialContract": "<string>",
    "powerOfAttorney": "<string>"
  }
}
'

const options = {
  method: 'PATCH',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    email: 'jsmith@example.com',
    phone: '<string>',
    companyType: '<string>',
    companyLegalName: '<string>',
    companyFoundingDate: '<string>',
    annualRevenue: 50000000000000,
    corporationType: '<string>',
    birthDate: '<string>',
    motherName: '<string>',
    profession: '<string>',
    monthlyIncome: 50000000000000,
    legalRepresentativeInfo: {
      name: '<string>',
      document: '<string>',
      email: 'jsmith@example.com',
      motherName: '<string>',
      birthdate: '<string>',
      monthlyIncome: 50000000000000,
      profession: '<string>',
      phone: '<string>',
      selfDeclaredRepresentative: true
    },
    pixKeyType: '<string>',
    pixKey: '<string>',
    website: '<string>',
    address: {
      address: '<string>',
      number: '<string>',
      complement: '<string>',
      neighborhood: '<string>',
      city: '<string>',
      state: '<string>',
      postalCode: '<string>',
      referencePoint: '<string>'
    },
    files: {
      identificationDocument: '<string>',
      selfie: '<string>',
      addressProof: '<string>',
      socialContract: '<string>',
      powerOfAttorney: '<string>'
    }
  })
};

fetch('https://api.sandbox.z2pay.com/v1/recipients/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.sandbox.z2pay.com/v1/recipients/{id}"

payload = {
    "name": "<string>",
    "email": "jsmith@example.com",
    "phone": "<string>",
    "companyType": "<string>",
    "companyLegalName": "<string>",
    "companyFoundingDate": "<string>",
    "annualRevenue": 50000000000000,
    "corporationType": "<string>",
    "birthDate": "<string>",
    "motherName": "<string>",
    "profession": "<string>",
    "monthlyIncome": 50000000000000,
    "legalRepresentativeInfo": {
        "name": "<string>",
        "document": "<string>",
        "email": "jsmith@example.com",
        "motherName": "<string>",
        "birthdate": "<string>",
        "monthlyIncome": 50000000000000,
        "profession": "<string>",
        "phone": "<string>",
        "selfDeclaredRepresentative": True
    },
    "pixKeyType": "<string>",
    "pixKey": "<string>",
    "website": "<string>",
    "address": {
        "address": "<string>",
        "number": "<string>",
        "complement": "<string>",
        "neighborhood": "<string>",
        "city": "<string>",
        "state": "<string>",
        "postalCode": "<string>",
        "referencePoint": "<string>"
    },
    "files": {
        "identificationDocument": "<string>",
        "selfie": "<string>",
        "addressProof": "<string>",
        "socialContract": "<string>",
        "powerOfAttorney": "<string>"
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

{
  "id": "rec_gk1o75xv3ioi4eoqosorz9s62",
  "accountName": "Loja do Joao",
  "name": "Joao da Silva",
  "email": "joao.silva@example.com",
  "phone": "+5511987654321",
  "document": "12345678901",
  "type": "individual",
  "companyType": null,
  "companyLegalName": null,
  "companyFoundingDate": null,
  "annualRevenue": null,
  "corporationType": null,
  "birthDate": "1990-04-12T00:00:00.000Z",
  "motherName": "Maria da Silva",
  "profession": "Comerciante",
  "monthlyIncome": 850000,
  "legalRepresentativeInfo": null,
  "pixKeyType": "email",
  "pixKey": "joao.silva@example.com",
  "website": "https://lojadojoao.com.br",
  "mainAddress": {
    "id": "radr_n5t8wqz2mxk9rpf4hc7ydv3bj",
    "recipientId": "rec_gk1o75xv3ioi4eoqosorz9s62",
    "address": "Rua das Flores",
    "number": "123",
    "complement": "Apto 45",
    "neighborhood": "Centro",
    "city": "Sao Paulo",
    "state": "SP",
    "postalCode": "01001000",
    "referencePoint": null,
    "isMain": true,
    "isActive": true
  },
  "defaultBankAccount": {
    "id": "rba_bg9eddocogegc2pbjyexzd104",
    "recipientId": "rec_gk1o75xv3ioi4eoqosorz9s62",
    "status": "active",
    "bankHolderName": "Joao da Silva",
    "bankHolderDocument": "12345678901",
    "bankHolderType": "individual",
    "bankCode": "341",
    "bankName": "Itau Unibanco",
    "bankAgency": "1234",
    "bankAccount": "567890",
    "bankAccountDigit": "1",
    "bankAccountType": "checking"
  },
  "documents": [],
  "role": "seller",
  "status": "active",
  "splitValue": 10,
  "splitType": "percentage",
  "pixAntecipationDays": null,
  "bankSlipAntecipationDays": null,
  "creditCardAntecipationDays": null,
  "approvedAt": "2025-06-20T14:30:00.000Z",
  "refusedAt": null,
  "analysisComplete": true,
  "pendencies": [],
  "pendenciesSummary": {
    "open": 0,
    "blocking": 0,
    "warning": 0
  },
  "createdAt": "2025-06-18T09:15:00.000Z",
  "updatedAt": "2025-06-20T14:30:00.000Z"
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "issues": [
      {
        "path": "status",
        "message": "Status inválido. Valores aceitos: pending, waiting_payment, paid, refused, canceled, refunded"
      },
      {
        "path": "startDate",
        "message": "Data deve ser ISO 8601 com timezone (ex.: 2026-06-24T00:00:00Z)"
      }
    ]
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

{
  "error": "A request with this idempotency key is already being processed"
}

{
  "error": "Idempotency key already used with a different request body"
}

PATCH /recipients/:id Faz parte do recurso Recebedores — os estados do vínculo, o ciclo de aprovação e o catálogo de pendências estão lá. Atualização parcial: envie só os campos que quer alterar. É por aqui que se corrige o que a análise apontou em pendencies.

O cadastro tem um dono. O mesmo recebedor pode receber de várias contas — o vínculo é por documento —, mas os dados cadastrais pertencem à conta que o criou. Se o cadastro foi criado por outra conta e você apenas o tem vinculado, a alteração responde 403.

document e kind não são alteráveis. O documento é o que identifica o recebedor na plataforma inteira — trocá-lo seria outra pessoa. Se o documento está errado, o caminho é cadastrar de novo com o correto e desvincular o antigo.

Corrigir os dados não reabre a análise sozinho. A atualização grava o cadastro; a nova rodada acontece quando o conjunto volta a estar completo. Acompanhe por GET /recipients/{id} ou pelos webhooks recipient.* — ver Ciclo de aprovação.

O titular da conta bancária tem de ser o próprio recebedor. A exceção é o MEI, em que também vale o CPF do representante legal. Qualquer outro titular é recusado.

Mandar address, bankAccount ou files cobra o cadastro completo, igual ao POST — a diferença é que aqui a conferência olha o cadastro já mesclado, não só o que você enviou. Quem já passou pelo formulário não precisa reenviar documento nem selfie para corrigir um campo; mas completar um recebedor que ainda está em new exige o pacote inteiro do type dele, listado em Criar recebedor.

legalRepresentativeInfo é gravado inteiro. Envie o objeto completo, inclusive legalRepresentativeInfo.role — um objeto sem esse campo apaga o vínculo que estava gravado.

Recebedor company cujo representante está gravado sem role precisa recebê-lo para qualquer correção nesses blocos. Como a conferência olha o cadastro mesclado, e nele não há o vínculo, mandar address, bankAccount ou files responde 400 em legalRepresentativeInfo.role até o objeto do representante chegar com o campo. Já a procuração enviada num KYC anterior conta como enviada e não precisa ser reenviada — ver Criar recebedor.

As regras de formato valem aqui também: phone com DDD e número, CPF do representante legal válido, e pixKeyType e pixKey sempre em par. O que não passar volta em 400, com todos os campos de uma vez em error.issues[].

Exemplo

curl -X PATCH https://api.sandbox.z2pay.com/v1/recipients/rec_v57bi6ruyolouw3cpaq2ofy1k \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+5511912345678",
    "website": "https://lojadojoao.com.br"
  }'

Resposta 200

{
  "id": "rec_v57bi6ruyolouw3cpaq2ofy1k",
  "name": "Loja do João ME",
  "document": "12345678000190",
  "email": "financeiro@lojadojoao.com.br",
  "phone": "+5511912345678",
  "website": "https://lojadojoao.com.br",
  "role": "seller",
  "status": "pending"
}

O exemplo está abreviado — o playground ao lado mostra o corpo inteiro.

Authorizations

x-api-key

string

header

required

API Key da Credential (gerada no Backoffice)

Headers

Idempotency-Key

string

Chave única para garantir idempotência da requisição

Path Parameters

string

required

ID do recebedor

Body

application/json

name

string

Minimum string length: 2

string<email>

phone

string | null

type

enum<string>

Available options:

individual,

company

companyType

string | null

companyLegalName

string | null

companyFoundingDate

string | null

annualRevenue

integer

Required range: 0 <= x <= 100000000000000

corporationType

string | null

birthDate

string | null

motherName

string | null

profession

string | null

monthlyIncome

integer | null

Required range: 0 <= x <= 100000000000000

legalRepresentativeInfo

object | null

Show child attributes

pixKeyType

string | null

pixKey

string | null

website

string | null

Maximum string length: 1024

politicallyExposed

enum<string> | null

Available options:

no,

yes,

related

address

object

Show child attributes

bankAccount

object

Show child attributes

files

object

Show child attributes

Response

Recebedor atualizado

string

Identificador único do registro.

accountName

string | null

Nome da conta do recebedor.

name

string

Nome do registro.

string

E-mail de contato.

phone

string | null

Telefone de contato.

document

string

Documento (CPF ou CNPJ) do titular.

type

string

Tipo do recebedor: individual (pessoa física) ou company (pessoa jurídica).

companyType

string | null

Tipo ou natureza jurídica da empresa.

companyLegalName

string | null

Razão social da empresa.

companyFoundingDate

string<date-time> | null

Data de fundação da empresa (ISO 8601).

annualRevenue

integer | null

Faturamento anual do recebedor, em centavos.

corporationType

string | null

Tipo societário da empresa.

birthDate

string<date-time> | null

Data de nascimento do recebedor (ISO 8601).

motherName

string | null

Nome da mãe do recebedor.

profession

string | null

Profissão do recebedor.

monthlyIncome

integer | null

Renda mensal do recebedor, em centavos.

legalRepresentativeInfo

object | null

Dados do representante legal da empresa.

pixKeyType

string | null

Tipo da chave PIX (ex.: email, cpf, cnpj, phone, random).

pixKey

string | null

Chave PIX do recebedor.

website

string | null

Site do recebedor.

mainAddress

object | null

Endereço principal do recebedor.

defaultBankAccount

object | null

Conta bancária padrão do recebedor.

documents

object[] | null

Documentos enviados para verificação (KYC) do recebedor.

role

string

Papel do recebedor no split (ex.: seller).

status

string

Situação da conta bancária. Valores: active, inactive, pending.

splitValue

number | null

Valor do split do recebedor (percentual ou fixo, conforme splitType).

splitType

string | null

Tipo do valor de split do recebedor (ex.: percentage, fixed).

pixAntecipationDays

integer | null

Prazo de antecipação para PIX, em dias.

bankSlipAntecipationDays

integer | null

Prazo de antecipação para boleto, em dias.

creditCardAntecipationDays

integer | null

Prazo de antecipação para cartão de crédito, em dias.

approvedAt

string<date-time> | null

Data e hora em que o recebedor foi aprovado (ISO 8601).

refusedAt

string<date-time> | null

Data e hora em que o recebedor foi recusado (ISO 8601).

analysisComplete

boolean

Indica se a análise cadastral terminou. false enquanto houver rodada de análise aberta para este recebedor na sua conta.

pendencies

object[]

Pendências apontadas pela análise. Cada item traz code (estável, para automação), field, severity (blocking ou warning), status (open ou resolved), message e action (texto traduzido) e as datas do grupo.

pendenciesSummary

object

Contagem das pendências abertas: open (total), blocking e warning.

createdAt

string<date-time>

Data e hora de criação do registro (ISO 8601).

updatedAt

string<date-time>

Data e hora da última atualização do registro (ISO 8601).

Cobranças

Clientes & Cartões

Checkout

Cobrança recorrente

Split & Recebedores

Webhooks & Eventos

Valores & Taxas

Atualizar recebedor

Exemplo

Authorizations

Headers

Path Parameters

Body

Response

​Exemplo

Authorizations

Headers

Path Parameters

Body

Response

Exemplo