Payment Facilitators

A payment facilitator sells through sub-merchants and settles their transactions under its own Getnet credential. Card schemes, payment arrangements, and regulators require you to identify the sub-merchant behind every transaction. You send that identification in the data.sub_merchant object of each authorization request.

Availability

Payment facilitators are available for ecommerce (card not present) and card-present transactions:

Availability is a commercial rule tied to your credential, not an API validation. The API accepts sub_merchant on any card authorization. A request outside the table above does not fail on schema grounds. Confirm your coverage with Integration Support before you build.

Enablement

Getnet records payment facilitator status on your credential. No request field turns the product on, so request enablement when you apply for your credential. When your credential is already active but not enabled, contact Integration Support before you integrate.

Object placement

Place sub_merchant at data.sub_merchant, as a sibling of data.payment. Do not nest it inside data.payment or data.additional_data.

Sub-merchant data is transaction data, not a registration. There is no onboarding endpoint, so you send the object on every authorization. The object applies to authorization requests only:

Only the two authorization operations act on sub_merchant, so identify the sub-merchant at authorization time. What happens if you send it elsewhere depends on the operation: Boleto rejects the request, and cancel accepts it and ignores the object.

Sub-merchant identification is independent of split-payment fields such as data.additional_data.split. Those fields have their own integration requirements.

Getnet does not echo the sub_merchant object in the payment response.

Minimal request

This request carries only the six required fields. Use it as your starting point:

{
  "idempotency_key": "4c3cbdc2-b41e-4e1c-b7fe-90ed10abd9bb",
  "order_id": "izgyekkmb8sd",
  "data": {
    "amount": 500,
    "currency": "BRL",
    "payment": {
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "soft_descriptor": "FACILIT*SUBCOMERCIO",
      "dynamic_mcc": "5812",
      "card": {
        "number": "4012001037141112",
        "expiration_month": "12",
        "expiration_year": "30"
      }
    },
    "sub_merchant": {
      "identification_code": "9058345",
      "document_type": "CNPJ",
      "document_number": "77415914000148",
      "address": "Dark Tower 207",
      "city": "Sao Paulo",
      "state": "SP"
    }
  }
}

Request with optional fields

The same request, with the address detail and the acceptor contact block added:

{
  "idempotency_key": "4c3cbdc2-b41e-4e1c-b7fe-90ed10abd9bb",
  "order_id": "izgyekkmb8sd",
  "data": {
    "amount": 500,
    "currency": "BRL",
    "payment": {
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "soft_descriptor": "FACILIT*SUBCOMERCIO",
      "dynamic_mcc": "5812",
      "card": {
        "number": "4012001037141112",
        "expiration_month": "12",
        "expiration_year": "30"
      }
    },
    "sub_merchant": {
      "identification_code": "9058345",
      "document_type": "CNPJ",
      "document_number": "77415914000148",
      "address": "Dark Tower",
      "address_number": "207",
      "district": "Centro",
      "city": "Sao Paulo",
      "state": "SP",
      "postal_code": "90520000",
      "country_code": "BR",
      "business_name": "Company Ltd",
      "acceptor": {
        "url_address": "https://site.getnet.com.br",
        "customer_service_phone_number": "551140041234",
        "tax_id": "77415914000148"
      }
    }
  }
}

Required fields

Six fields are required whenever you send the object. The sub_merchant object itself is optional in the API contract. Whether you must send it comes from your facilitator credential, not from the request schema. All fields in the tables below sit inside data.sub_merchant.

All values in this object except foreign_amount describe the sub-merchant itself and stay the same on every transaction for that sub-merchant. Take them from the sub-merchant’s onboarding record that you hold as facilitator, never from the cardholder, the buyer, or the order. foreign_amount is the only per-transaction value.

Document types

Send the type that matches the sub-merchant’s country of registration. The API accepts any of the eleven values in any market. It does not check the value against document_number, and it does not validate the number’s format, so pairing the two correctly is your responsibility.

Optional fields

The Global API uses a flat address shape. address_number, address_complement, district, city, state, postal_code, and country_code are all siblings of address.

foreign_type describes the cart, not the payload. You identify one sub-merchant per transaction, because sub_merchant is a single object and never a list. Send P to flag a mixed cart, not to enumerate sub-merchants.

Acceptor object

The acceptor object holds contact data of the sub-merchant, used to reach the establishment behind the transaction. Every field is optional and static per sub-merchant. Send the sub-merchant’s own contacts here, not the facilitator’s.

Getnet includes url_address, phone_number, and tax_id in fraud analysis.

The object carries three phone fields. Use acceptor.customer_service_phone_number for the support line the cardholder calls, acceptor.phone_number for the sub-merchant’s general line, and phone_number at the root of the object for the number registered with the facilitator. Getnet forwards all three.

Descriptor and MCC

Identifying the sub-merchant takes more than the sub_merchant object. The card schemes also expect two fields on data.payment, alongside the card data:

For facilitator transactions, the schemes expect soft_descriptor to name both parties. Send the facilitator identifier in 3, 7, or 12 characters, then an asterisk, then the sub-merchant identifier. For example FAC*SUCOMERCIO, FACILIT*SUBCOMERCIO, or FACILITADOR1*SUBCOMERC.

For cross-border sellers, Getnet truncates soft_descriptor to 18 characters and adds the GNT* prefix. That rewrite overrides the facilitator format, so the cardholder sees a different value from the one you send.

Market-specific requirements

Some markets add requirements on top of the six base fields. Mastercard requires iva_category for transactions in Argentina. Getnet does not enforce these rules, so it accepts the request and the acquirer or the issuer declines it later.

Validation errors

Getnet returns HTTP 400 with a ValidationError body when the object fails validation. Three cases trigger it: a missing required field, a value over the limits above, or a property that is not listed on this page.

The details array carries one entry per offending field, so a single response reports every problem at once. The example below rejects three at the same time: city is missing, state exceeds 3 characters, and complement is not a property the object accepts.

{
  "message": "Bad Request",
  "name": "ValidationError",
  "status_code": 400,
  "details": [
    {
      "status": "DENIED",
      "error_code": "GENERIC-400",
      "description": "data,sub_merchant,city is invalid",
      "description_detail": "\"data.sub_merchant.city\" is required"
    },
    {
      "status": "DENIED",
      "error_code": "GENERIC-400",
      "description": "data,sub_merchant,state is invalid",
      "description_detail": "\"data.sub_merchant.state\" length must be less than or equal to 3 characters long"
    },
    {
      "status": "DENIED",
      "error_code": "GENERIC-400",
      "description": "data,sub_merchant,complement is invalid",
      "description_detail": "\"data.sub_merchant.complement\" is not allowed"
    }
  ]
}

Getnet accepts only the properties listed on this page. Any other property inside sub_merchant returns "data.sub_merchant.<field>" is not allowed. A misspelled field name therefore returns HTTP 400 instead of being ignored.

A request that satisfies the six required fields can still be declined later in the flow. Card-scheme rules are evaluated after Getnet accepts the request, as described in Market-specific requirements.

Related resources

• Create a Single-Step Card Payment
• Create Combined Card Payments
• Create a Staged Digital Wallet Operator Payment
• Payments endpoint reference
• Errors reference