Skip to main content
Recipients are the sellers/merchants who receive payouts from your sales. You register a recipient, it gets linked to your company with a role and a status, and from that point it can be used as a destination in a payment split. A global recipient (unique CPF/CNPJ on the platform) is linked to your company through a link. The endpoint responses combine the recipient’s data (name, document, bank account) with the link data (status, role, split configuration).
All requests use the x-api-key header. See Authentication. The sandbox base URL is https://api.sandbox.z2pay.com.

​
Concepts

Role

seller (default when creating via API), owner (the company’s primary recipient) or platform (internal). There is at most 1 owner per company.

Link status

new, pending, active, refused or inactive. A recipient must be eligible to receive payouts before being used in a split.
Recipient owner is the primary recipient linked to your company with role: "owner". Use GET /recipients/owner to find out who the owner is without needing to know their ID.

​
Endpoints

MethodRouteDescription
GET/recipientsPaginated list of the company’s recipients
GET/recipients/ownerReturns the recipient with the owner role
GET/recipients/:idFetches a recipient by ID
POST/recipientsCreates or links a recipient to the company
PUT/recipients/:idUpdates a recipient’s data
POST/recipients/:id/kyc-linkGenerates a KYC link for the recipient to complete their information
DELETE/recipients/:idUnlinks the recipient from the company

​
List recipients

GET /recipients
Returns the paginated list of recipients linked to your company. Accepts optional filters by email or document. Only merchant-type recipients appear in this listing.

​
Query parameters

​
page
integer
Current page (pagination).
​
limit
integer
Number of items per page.
​
email
string
Filters by the recipient’s exact email address. Must be a valid email.
​
document
string
Filters by document (CPF/CNPJ). Minimum of 11 characters.

​
Example

curl https://api.sandbox.z2pay.com/recipients?limit=10 \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "data": [
    {
      "id": "rec_8x2k9d1p4q",
      "name": "Loja do João ME",
      "email": "contato@lojadojoao.com.br",
      "document": "12345678000190",
      "type": "company",
      "phone": "+5511999998888",
      "status": "active",
      "role": "seller",
      "companyId": "comp_a1b2c3d4e5",
      "defaultBankAccount": {
        "id": "rba_3k9d8f2j1",
        "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
  }
}
Filter combinations are restrictive: if email and document are both provided and refer to different recipients, the list will come back empty.

​
Fetch owner recipient

GET /recipients/owner
Returns the recipient linked to your company with role: "owner". If the company does not have an owner defined, the response is null. 
curl https://api.sandbox.z2pay.com/recipients/owner \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "id": "rec_owner1a2b3c",
  "name": "Minha Empresa LTDA",
  "email": "financeiro@minhaempresa.com.br",
  "document": "98765432000110",
  "type": "company",
  "status": "active",
  "role": "owner",
  "companyId": "comp_a1b2c3d4e5",
  "splitValue": null,
  "splitType": null,
  "createdAt": "2026-05-01T10:00:00.000Z",
  "updatedAt": "2026-05-01T10:00:00.000Z"
}
When there is no owner, the response body is literally null (status 200). Handle this case in your code before accessing any fields.

​
Fetch recipient by ID

GET /recipients/:id
​
id
string
required
Recipient ID (prefix rec_).
curl https://api.sandbox.z2pay.com/recipients/rec_8x2k9d1p4q \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "id": "rec_8x2k9d1p4q",
  "name": "Loja do João ME",
  "email": "contato@lojadojoao.com.br",
  "document": "12345678000190",
  "type": "company",
  "status": "active",
  "role": "seller",
  "companyId": "comp_a1b2c3d4e5",
  "splitValue": 10,
  "splitType": "percentage",
  "createdAt": "2026-06-01T13:00:00.000Z",
  "updatedAt": "2026-06-10T09:30:00.000Z"
}
Returns 404 if the recipient is not linked to your company. See Errors.

​
Create recipient

POST /recipients
Creates a recipient (global registration by CPF/CNPJ) and links it to your company with role: "seller". If a merchant recipient with the same document or email already exists, it is reused and its data is updated with what you send. Returns status 201. Supports idempotency via the Idempotency-Key header — see Conventions.
The initial link status depends on the data provided: if both a primary address and a bank account are filled in, the link starts as pending; otherwise, it starts as new.

​
Body fields

​
name
string
required
Recipient’s name. Minimum of 2 characters.
​
email
string
required
Recipient’s valid email address.
​
document
string
required
CPF or CNPJ. Minimum of 11 characters.
​
type
string
required
Recipient type. Values: individual or company.
​
phone
string
Recipient’s phone number.
​
kind
string
Recipient category. Values: merchant or platform. Use merchant for the public API.
​
companyType
string
Company type (free text). Relevant when type = company.
​
companyLegalName
string
Legal company name.
​
companyFoundingDate
string
Company founding date.
​
annualRevenue
integer
Annual revenue, in cents (integer).
​
corporationType
string
Legal entity type (free text).
​
birthDate
string
Date of birth. Relevant when type = individual.
​
motherName
string
Mother’s name.
​
profession
string
Profession.
​
monthlyIncome
integer
Monthly income, in cents (integer).
​
pixKeyType
string
Pix key type.
​
pixKey
string
Pix key.
​
website
string
Recipient’s website.
​
legalRepresentativeInfo
object
Legal representative data. Fields: name (string, required), document (string, required), email (string), motherName (string), birthdate (string), monthlyIncome (number), profession (string), phone (string), selfDeclaredRepresentative (boolean).
​
address
object
Address. All fields are optional: address, number, complement, neighborhood, city, state (max. 2 characters), postalCode, referencePoint.
​
bankAccount
object
Bank account for payouts. Fields below.
​
files
object
Documents in base64: identificationDocument, selfie, socialContract (all optional).

​
bankAccount object

​
bankAccount.bankHolderName
string
required
Account holder’s name. Minimum of 2 characters.
​
bankAccount.bankHolderDocument
string
required
Account holder’s document. Minimum of 11 characters.
​
bankAccount.bankCode
string
required
Bank code. Minimum of 1 character.
​
bankAccount.bankAgency
string
required
Bank branch. Minimum of 1 character.
​
bankAccount.bankAccount
string
required
Account number. Minimum of 1 character.
​
bankAccount.bankHolderType
string
Account holder type (free text).
​
bankAccount.bankName
string
Bank name.
​
bankAccount.bankAccountDigit
string
Account check digit.
​
bankAccount.bankAccountType
string
Account type (free text).

​
Example

curl -X POST https://api.sandbox.z2pay.com/recipients \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c1f9b2a-3d4e-4a55-9c0b-1e2f3a4b5c6d" \
  -d '{
    "name": "Loja do João ME",
    "email": "contato@lojadojoao.com.br",
    "document": "12345678000190",
    "type": "company",
    "phone": "+5511999998888",
    "bankAccount": {
      "bankHolderName": "Loja do João ME",
      "bankHolderDocument": "12345678000190",
      "bankCode": "341",
      "bankName": "Itaú",
      "bankAgency": "1234",
      "bankAccount": "56789",
      "bankAccountDigit": "0"
    }
  }'

{
  "id": "rec_8x2k9d1p4q",
  "name": "Loja do João ME",
  "email": "contato@lojadojoao.com.br",
  "document": "12345678000190",
  "type": "company",
  "phone": "+5511999998888",
  "kind": "merchant",
  "status": "new",
  "role": "seller",
  "companyId": "comp_a1b2c3d4e5",
  "splitValue": null,
  "splitType": null,
  "createdAt": "2026-06-24T12:00:00.000Z",
  "updatedAt": "2026-06-24T12:00:00.000Z"
}

​
Update recipient

PUT /recipients/:id
Updates the data of a recipient already linked to your company. All body fields are optional (send only what you want to change) — the available fields are the same as the POST creation endpoint. Returns 404 if the recipient is not linked to your company. Supports idempotency via the Idempotency-Key header.
​
id
string
required
Recipient ID (prefix rec_).
curl -X PUT https://api.sandbox.z2pay.com/recipients/rec_8x2k9d1p4q \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+5511988887777"
  }'

{
  "id": "rec_8x2k9d1p4q",
  "name": "Loja do João ME",
  "phone": "+5511988887777",
  "updatedAt": "2026-06-24T12:05:00.000Z"
}

POST /recipients/:id/kyc-link
Generates a temporary link for the recipient to complete or validate their information via KYC (Know Your Customer). Use this when the recipient needs to submit documents or complete their registration before being approved to receive payouts. Returns status 201. Supports idempotency via the Idempotency-Key header. Returns 404 if the recipient is not linked to your company.
​
id
string
required
Recipient ID (prefix rec_).
curl -X POST https://api.sandbox.z2pay.com/recipients/rec_8x2k9d1p4q/kyc-link \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "kycUrl": "https://kyc.z2pay.com/recipient/kyc_tok_9f8e7d6c5b4a",
  "expiresAt": "2026-06-25T12:00:00.000Z"
}
​
kycUrl
string
URL for the recipient to access the KYC flow.
​
expiresAt
string
Link expiration date/time (ISO 8601 with timezone).
DELETE /recipients/:id
Removes the recipient’s link to your company (soft delete of the link). The recipient’s global registration is not deleted. Supports idempotency via the Idempotency-Key header.
​
id
string
required
Recipient ID (prefix rec_).
curl -X DELETE https://api.sandbox.z2pay.com/recipients/rec_8x2k9d1p4q \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

​
Common errors

  • 404 — recipient not linked to your company (on GET /:id, PUT /:id and POST /:id/kyc-link).
  • 401 — x-api-key missing or invalid. See Authentication.
  • 400 — invalid body (e.g., document with fewer than 11 characters, type outside the enum).
Full error format in Errors.

​
See also

Splits

Use recipients as payout destinations in payments.

Settlement

How and when recipients receive their funds.

Customers

Manage payer customers.

Conventions

Idempotency, pagination and formats.