# 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:

| Model | Argentina | Brazil | Mexico |
| --- | :---: | :---: | :---: |
| Card not present (ecommerce) | ✅ | ✅ | ✅ |
| Card present | - | ✅ | - |

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:

| Operation | Send `data.sub_merchant`? |
| --- | --- |
| `/payments` authorization | Yes — as a sibling of `data.payment`. |
| `/payments/combined` authorization | Yes — in the combined payment data. Getnet copies the object to each payment in the array. |
| `/payments/capture` | No — the operation does not use the object. |
| `/payments/cancel` | No — Getnet accepts the request and ignores the object. |
| `/payments/boleto` | No — Getnet rejects the request with `"data.sub_merchant" is not allowed`. |
| `/payments/qrcode` and `/payments/qrcode/pix` | No — the operation does not use the object. |

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:

```json
{
  "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:

```json
{
  "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.

| Attribute | Type | Description | Required |
| --- | --- | --- | --- |
| `identification_code` | String | Sub-merchant identifier assigned by the facilitator. Maximum 15 characters for Visa and Mastercard. American Express is not subject to this limit. Example: `"9058345"` | Yes |
| `document_type` | String | Legal document type of the sub-merchant, from the country where it is registered. See [Document types](#document-types). Example: `"CNPJ"` | Yes |
| `document_number` | String | Number of the document named in `document_type`, without punctuation or mask. Send a CNPJ as `77415914000148`, not `77.415.914/0001-48`. Separate from `acceptor.tax_id`. Minimum 5 and maximum 25 characters. Example: `"77415914000148"` | Yes |
| `address` | String | Street or public-place name from the sub-merchant's registered address, as a plain string, never a nested object. Getnet removes accents and special characters before processing. Maximum 60 characters. Example: `"Dark Tower"` | Yes |
| `city` | String | City where the sub-merchant is registered, not the city where the purchase happens. It must match the onboarding record. Maximum 40 characters. Example: `"Sao Paulo"` | Yes |
| `state` | String | Sub-merchant state or region abbreviation, up to 3 characters. Send the local abbreviation, such as `SP`, not a full ISO 3166-2 subdivision code, which does not fit. Example: `"SP"` | Yes |

<Callout type="note">

These six fields are the API contract, and it does not vary by model. The API applies no condition based on wallet type, so the [Staged Digital Wallet Operator](/en/global-api/sep-api/payment-guides-api/card-payments/create-sdwo-payment) model validates the same six. That model also documents `postal_code` and `business_name` as required. Getnet does not enforce those two, so confirm with Integration Support whether your model needs them.

</Callout>

### 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.

| Value | Document | Country |
| --- | --- | --- |
| `CPF` | Cadastro de Pessoa Física | Brazil |
| `CNPJ` | Cadastro Nacional de Pessoa Jurídica | Brazil |
| `PASSPORT_BR` | Passport | Brazil |
| `DNI` | Documento Nacional de Identidad | Argentina |
| `CUIL` | Código Único de Identificación Laboral | Argentina |
| `CUIT` | Código Único de Identificación Tributaria | Argentina |
| `PASSPORT_AR` | Passport | Argentina |
| `RUT` | Rol Único Tributario | Chile |
| `CI` | Cédula de Identidad | Chile |
| `CURP` | Clave Única de Registro de Población | Mexico |
| `RFC` | Registro Federal de Contribuyentes | Mexico |

## 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`.

| Attribute | Type | Description | Required |
| --- | --- | --- | --- |
| `gateway_id` | String | Sub-merchant gateway identifier. Maximum 11 characters. Contact Integration Support to find out whether your integration uses this field. Example: `"GW123456"` | No |
| `postal_code` | String | Postal code of the sub-merchant's registered address, not the buyer's shipping code. Send digits only, without a separator, so a Brazilian CEP goes as `90520000` rather than `90520-000`. Maximum 15 characters. Example: `"90520000"` | No |
| `district` | String | District or neighborhood of the sub-merchant's registered address. Maximum 60 characters. Example: `"Centro"` | No |
| `country_code` | String | Sub-merchant country code. Send ISO 3166-1 alpha-2 (`BR`) or alpha-3 (`BRA`). Getnet validates only the length, not the value against the ISO list. Example: `"BR"` | No |
| `address_number` | String | Building or street number of the sub-merchant's registered address. Send it in this field instead of appending it to `address`. Maximum 6 characters. Example: `"207"` | No |
| `address_complement` | String | Additional detail of the sub-merchant's registered address, such as a floor, room, or block. This is the only complement field the API accepts. Maximum 60 characters. Example: `"Floor 2"` | No |
| `business_name` | String | Trading or company name of the sub-merchant, as registered with the facilitator. Send it whenever you have it, because Getnet includes it in fraud analysis. Accepts an empty string or null for sub-merchants registered without a trading name. It does not control what the cardholder sees on the statement — that comes from `soft_descriptor`. Maximum 80 characters. Example: `"Company Ltd"` | No |
| `foreign_type` | String | Composition of sub-merchants in the transaction. Send `F` for Full Foreign (all sub-merchants are international), `P` for Partial Foreign (the cart mixes international and national sub-merchants), or `D` for Full Domestic (all sub-merchants are national). The value is case-insensitive. | No |
| `foreign_amount` | Integer | Foreign-currency transaction amount in cents. You do not declare the currency in the request. It comes from the sub-merchant configuration. Zero is accepted. Example: `0` | No |
| `phone_number` | String | Phone number registered with the facilitator for this sub-merchant, sent at the root of the object. See the note under [Acceptor object](#acceptor-object) on the three phone fields. Maximum 16 characters. Example: `"5511999999999"` | No |
| `iva_category` | String | IVA/VAT tax category. Maximum 50 characters. Mastercard requires it in Argentina, but Getnet neither enforces the rule nor validates the value. Example: `"1"` | No |

`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.

| Attribute | Type | Description | Required |
| --- | --- | --- | --- |
| `acceptor.url_address` | String | Website of the sub-merchant. This is not the same as `data.additional_data.url`, which refers to the merchant of record. Send the sub-merchant's site here even when the two differ, and Getnet forwards both. Maximum 256 characters. Example: `"https://site.getnet.com.br"` | No |
| `acceptor.customer_service_phone_number` | String | Phone number the cardholder can call to reach the sub-merchant's customer service. Maximum 16 characters. Example: `"551140041234"` | No |
| `acceptor.phone_number` | String | Sub-merchant's general line, sent inside the acceptor block. Maximum 16 characters. Example: `"5511999999999"` | No |
| `acceptor.additional_contact` | String | Any further contact channel for the sub-merchant, such as an email address, when the phone fields are not enough. Maximum 256 characters. Example: `"contact@getnet.com.br"` | No |
| `acceptor.tax_id` | String | Tax identifier of the sub-merchant, sent with the acceptor contact data. Separate from `document_number`, which carries the legal document that identifies the sub-merchant. Send `document_number` even when both values are the same. Maximum 35 characters. Example: `"77415914000148"` | No |

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:

| Field | Description |
| --- | --- |
| `data.payment.soft_descriptor` | Text shown on the cardholder statement. Maximum 22 characters. Getnet truncates longer values instead of rejecting them. It keeps letters, digits, spaces, and the asterisk, so the separator in the facilitator format survives. Accented characters become their unaccented equivalent, and every other character is removed. |
| `data.payment.dynamic_mcc` | Merchant Category Code of the sub-merchant. Up to four digits. Getnet left-pads shorter values with zeros, so `"799"` becomes `"0799"`. Values with more than four digits can be declined. |

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`.

<Callout type="warning">

Getnet does not enforce either requirement. A request without `dynamic_mcc`, or with a `soft_descriptor` that ignores the format above, is still accepted. Meeting the scheme rules is your responsibility, and the schemes can penalize transactions that miss them.

</Callout>

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.

<Callout type="warning">

Additional local requirements may apply for some countries and merchants. Confirm with Integration Support which requirements apply to your market.

</Callout>

## 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.

| Attribute | Description |
| --- | --- |
| `message` | `Bad Request` for every validation failure. |
| `name` | Error type. `ValidationError` for a schema violation. |
| `status_code` | HTTP status of the response. |
| `details[].status` | Status of the rejected transaction. Always `DENIED`. |
| `details[].error_code` | Error code. `GENERIC-400` for validation failures. |
| `details[].description` | Path of the offending field in comma notation, followed by `is invalid`. |
| `details[].description_detail` | Reason the value was rejected, with the field path in dot notation. |

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.

```json
{
  "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](#market-specific-requirements).

## Related resources

* [Create a Single-Step Card Payment](/en/global-api/sep-api/payment-guides-api/card-payments/single-step-payment)
* [Create Combined Card Payments](/en/global-api/sep-api/payment-guides-api/card-payments/create-combined-payments)
* [Create a Staged Digital Wallet Operator Payment](/en/global-api/sep-api/payment-guides-api/card-payments/create-sdwo-payment)
* [Payments endpoint reference](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/payments)
* [Errors reference](/en/global-api/reference-global/errors)