Listar recebedores
curl --request GET \
--url https://api.sandbox.z2pay.com/v1/recipients \
--header 'x-api-key: <api-key>'const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.sandbox.z2pay.com/v1/recipients', 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"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"data": [
{
"id": "rec_gk1o75xv3ioi4eoqosorz9s62",
"name": "Joao da Silva",
"email": "joao.silva@example.com",
"document": "12345678901",
"type": "individual",
"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"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 1,
"totalPages": 1
}
}{
"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"
}
}Recebedores
Listar recebedores
Lista paginada dos recebedores vinculados à sua conta, com filtro por e-mail ou documento.
GET
/
recipients
Listar recebedores
curl --request GET \
--url https://api.sandbox.z2pay.com/v1/recipients \
--header 'x-api-key: <api-key>'const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.sandbox.z2pay.com/v1/recipients', 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"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"data": [
{
"id": "rec_gk1o75xv3ioi4eoqosorz9s62",
"name": "Joao da Silva",
"email": "joao.silva@example.com",
"document": "12345678901",
"type": "individual",
"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"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 1,
"totalPages": 1
}
}{
"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"
}
}GET /recipients
Faz parte do recurso recebedores — os conceitos e o objeto estão lá.
Retorna a lista paginada dos recebedores vinculados à sua conta. Apenas recebedores do tipo
merchant aparecem aqui.
Os dois filtros são exatos, e combiná-los é restritivo.
email exige o endereço completo e
document o CPF/CNPJ como foi cadastrado — valores parciais não retornam nada. Se você informar
os dois e eles apontarem para recebedores diferentes, a lista volta vazia, em vez de trazer
os dois.Exemplo
curl -G https://api.sandbox.z2pay.com/v1/recipients -H "x-api-key: SUA_CHAVE_DE_SANDBOX" --data-urlencode "limit=10"
{
"data": [
{
"id": "rec_v57bi6ruyolouw3cpaq2ofy1k",
"name": "Loja do João ME",
"email": "contato@lojadojoao.com.br",
"document": "12345678000190",
"type": "company",
"phone": "+5511999998888",
"status": "active",
"role": "seller",
"defaultBankAccount": {
"id": "rba_nub9kaa2xd5ptruubjel1w65z",
"bankCode": "341",
"bankName": "Itaú",
"bankAgency": "1234",
"bankAccount": "56789",
"bankAccountDigit": "0",
"bankHolderName": "Loja do João ME",
"bankHolderDocument": "12345678000190"
},
"createdAt": "2026-06-01T13:00:00.000Z",
"updatedAt": "2026-06-10T09:30:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 10,
"total": 1,
"totalPages": 1
}
}
Authorizations
API Key da Credential (gerada no Backoffice)
Query Parameters
Página da listagem. Padrão: 1.
Required range:
x >= 1Itens por página. Padrão: 20. Máximo: 100.
Required range:
1 <= x <= 100E-mail do recebedor. Correspondência exata, um valor por requisição — envie o endereço completo.
CPF ou CNPJ do recebedor. Correspondência exata, um valor por requisição — envie exatamente como foi cadastrado, com ou sem pontuação.
Minimum string length:
11