Onboarding API — PF

Onboarding Subseller in Getnet Split Payments lets a marketplace register individual (PF) partners, so Getnet knows where to direct each partner's share of a split payment. A partner's registration stores their identification, address, bank account, and commission rules, and must exist before Getnet can include that partner in any split transaction.

Before registering a partner through the API, confirm that your marketplace itself is already accredited with Getnet. This accreditation is a manual process, handled directly with Getnet, and is a prerequisite for every endpoint below.

Verify Whether the Partner Already Exists

Before registering a partner, check whether their CPF is already registered under your marketplace. Partners can also register directly through Getnet's Portal Minha Conta, so this check avoids a creation call being rejected for duplication.

  1. Send a GET request to /v2/mgm/pf/consult/{merchant_id}/{cpf}, replacing merchant_id with your marketplace's identification number at Getnet (EC, Merchant Establishment) and cpf with the partner's CPF (digits only, up to 11 digits).
  2. Include the Authorization header with the access token, in the format Bearer <token>.
  3. Check the response code:
    • 200: the partner is already registered. The response body returns the partner's current data.
    • 206: no eligible registration was returned for that CPF. Rejected, declined, or de-accredited registrations may not appear in this query and may be handled later as a retry or reuse. Continue at Create the Partner's Pre-Registration.
    • 400, 401, 404, 500: see Check the Response Codes, further below.

Create the Partner's Pre-Registration

Send a POST request to /v2/mgm/pf/create-presubseller with the partner's registration data.
  1. Set the Authorization header with the access token, in the format Bearer <token>.
  2. Build the request body with the required fields listed in the table below.
  3. Send the request and check the response code in the Check the Response Codes table, further below.

Required Fields

FieldTypeRules
merchant_idstringDigits only. Your marketplace's identification number at Getnet (EC).
legal_document_numberstringThe partner's CPF. Digits only, up to 11 digits, and must be REGULAR with the Federal Revenue Service.
legal_namestringFull name, as registered with the Federal Revenue Service for that CPF. At least two names (e.g. "Mario Silveira"). Avoid special characters, accents, or abbreviations.
birth_datestring (date-time)Must match the given CPF, and the partner must be older than 18.
occupationstringAvoid special characters and accents (e.g. write "MEDICO," not "MÉDICO").
emailstringValid email format. No accents or special characters. The domain can't be @getnet or @santander.
business_addressobjectSee Address Rules, further below.
bank_accountsobjectSee Bank Account Rules, further below. Payments are only made to a bank account under the same CPF registered with Getnet.
payment_planintegerMust match a plan returned by List the Available Payment Plans.
accepted_contractstringMust be "S". Although the field accepts "N", the registration only proceeds with "S".
phone or cellphoneobjectAt least one of the two is required. See Phone Rules, further below. cellphone is required if the partner will use Anticipation.

Optional Fields

FieldTypeNotes
mothers_namestring
monthly_gross_incomenumberMust be greater than 0.
gross_equitynumberMust be greater than 0.
residential_addressobject
identification_documentobjectRG document data. Required for Anticipation.
list_commissionsarraySee Commission Rules, further below.
marketplace_storestring"S" or "N".
automatic_anticipationstring"S" or "N".
list_centralizerarray of stringsList of centralized ECs linked to the centralizing EC given in merchant_id.
subsellerid_extstringConditionally required or prohibited, depending on the marketplace's configuration. Required for marketplaces that use a sales plugin. It must not be sent by the others.

Phone Rules

  • Mobile: 9 digits, with the first digit being 9 for most area codes (DDDs). DDDs 41, 46, 47, 48, 49, 51, 53, 54, 55, 61, 62, 64, 65, 66, 67, 68, and 69 have their own rules.
  • Landline: 8 digits, with the first digit 2, 3, 4, or 5. The DDD must appear on ANATEL's list.

Address Rules

  • street is required, can have up to 72 characters, and can't contain special characters.
  • number must be a non-negative integer. For an address with no number, send 0 or null.
  • postal_code is required. Send the CEP (postal code) with digits only, no hyphen, containing 7 or 8 digits.
  • city, state, and district are required. state must be a valid UF (state code). city and district can have up to 72 characters.
  • suite is optional and can hold an address complement, apartment, or unit. When provided, it can have up to 20 characters.
  • The business_address object also contains residential_address_equals:
    • "S": the business address is also used as the residential address.
    • "N": send the residential_address object.
    • If omitted, the default is "S".

Bank Account Rules

  • type_accounts distinguishes a single bank account (unique_account) from brand-specific accounts (custom_accounts). Send only the object that matches type_accounts; never send unique_account and custom_accounts together.
  • unique_account: account_type, bank (bank code), agency, agency_digit, account, account_digit.
  • custom_accounts: an array with at least one item, with the same fields as unique_account, plus brand (e.g. "Mastercard").

Commission Rules

  • brand, product, and payment_plan are required.
  • Set commission_percentage or commission_value, not both. If commission_percentage is greater than 0, commission_value must be 0 or null.
  • commission_percentage accepts values between 0.00 and 100.00. commission_value must be 0.00 or greater.

List the Available Payment Plans

Send a GET request to /v2/mgm/pf/consult/paymentplans/{merchant_id} to get the payment plans available for your marketplace. Use the returned paymentplan_id values when setting payment_plan in Create the Partner's Pre-Registration.

Check the Partner's Registration Status

Send a GET request to /v2/mgm/pf/consult/{merchant_id}/{cpf} to check a partner's current status at any time, using the same call described in Verify Whether the Partner Already Exists.
A callback variant is also available at /v2/mgm/pf/callback/{merchant_id}/{cpf}, which returns the same data inside an array instead of a single object. The callback may include additional report information.

Update the Partner's Registration

Send a PUT request to /v2/mgm/pf/update-subseller with the fields you want to change. Only merchant_id, subseller_id, and legal_document_number are required. The remaining fields follow the same rules as Create the Partner's Pre-Registration and only need to be sent if they're being changed.

De-Accredit the Partner

Send a POST request to /v2/mgm/pf/de-accredit/{merchant_id}/{subseller_id} to de-accredit a partner, replacing subseller_id with the partner's identifier.

Check the Response Codes

CodeMeaning
200Success.
206No eligible registration returned (query only). Rejected, declined, or de-accredited registrations may not appear.
400Invalid request.
401Access denied.
404Not found.
500Internal server error.

These calls cover the individual partner's full lifecycle, from initial verification to de-accreditation. Always validate the result using the response codes above.

Next Steps

  1. Onboarding API — PJ: the same flow for legal-entity partners.
  2. Payment Acceptance: see how to process sales once the partner is registered.

On this page

Onboarding API — PF