Payment Facilitators
A payment facilitator sells through sub-merchants and settles their transactions under its own Getnet credential. To meet card-scheme, payment-arrangement, and regulatory requirements, a facilitator identifies 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 | - | ✅ | - |
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. |
/payments/capture | No |
/payments/cancel | No |
/payments/boleto | No |
/payments/qrcode and /payments/qrcode/pix | No |
Sub-merchant identification is independent of split-payment fields such as
data.additional_data.split. Those fields have their own integration requirements.The
sub_merchant object is not echoed in the payment response.
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,
"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"
}
}
}
}
JSON1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
"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,
"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.| 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 | Sub-merchant legal document type. Use one of CPF, CNPJ, PASSPORT_BR, DNI, CUIL, CUIT, PASSPORT_AR, RUT, CI, CURP, RFC. Example: "CNPJ" | Yes |
document_number | String | Sub-merchant legal document number. Minimum 5 and maximum 25 characters. Example: "77415914000148" | Yes |
address | String | Sub-merchant street or address. Maximum 60 characters. Example: "Dark Tower" | Yes |
city | String | Sub-merchant city. Maximum 40 characters. Example: "Sao Paulo" | Yes |
state | String | Sub-merchant state or region code. Maximum 3 characters. Example: "SP" | Yes |
Optional fields
| Attribute | Type | Description | Required |
|---|---|---|---|
gateway_id | String | Sub-merchant gateway identifier. Maximum 11 characters. Argentina, Brazil, and Mexico each derive this value differently. Example: "GW123456" | No |
postal_code | String | Sub-merchant postal code. Maximum 15 characters. Example: "90520000" | No |
district | String | Sub-merchant district or neighborhood. Maximum 60 characters. Example: "Centro" | No |
country_code | String | Sub-merchant ISO country code. Maximum 3 characters. Example: "BR" | No |
address_number | String | Sub-merchant address number. Maximum 6 characters. Example: "207" | No |
address_complement | String | Sub-merchant address complement. Maximum 60 characters. Example: "Floor 2" | No |
business_name | String | Sub-merchant business or company name. Maximum 80 characters. Accepts an empty or null value. 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). | No |
foreign_amount | Integer | Foreign-currency transaction amount in cents. Zero is accepted. Example: 0 | No |
phone_number | String | Sub-merchant phone number. Maximum 16 characters. Example: "5511999999999" | No |
iva_category | String | IVA/VAT tax category. Maximum 50 characters. Example: "1" | No |
Acceptor object
The optional
acceptor object holds contact information for the sub-merchant.| Attribute | Type | Description | Required |
|---|---|---|---|
acceptor.url_address | String | Sub-merchant website URL. Maximum 256 characters. Example: "https://site.getnet.com.br" | No |
acceptor.customer_service_phone_number | String | Sub-merchant customer-service phone number. Maximum 16 characters. Example: "551140041234" | No |
acceptor.phone_number | String | Sub-merchant phone number. Maximum 16 characters. Example: "5511999999999" | No |
acceptor.additional_contact | String | Additional contact information for the sub-merchant. Maximum 256 characters. Example: "contact@getnet.com.br" | No |
acceptor.tax_id | String | Sub-merchant tax identifier. Maximum 35 characters. Example: "77415914000148" | No |
Address format
The Global API uses a flat address shape. Send
address as a string, and send address_number, address_complement, district, city, state, postal_code, and country_code as sibling fields. Do not send address as a nested object.Country and card-brand requirements
Some markets and card brands add requirements on top of the six base fields.
| Country / brand | Field | Requirement |
|---|---|---|
| Argentina + Mastercard | iva_category | Required. |
| Visa or Mastercard | identification_code | Maximum 15 characters. |
| American Express | identification_code | Not subject to the 15-character limit. |
| Argentina, Brazil, Mexico | gateway_id | Derived by country-specific rules. |
Important: Additional local requirements may apply for some countries and merchants. Confirm with Integration Support which requirements apply to your market.
Validation errors
When a required field is missing, or a value exceeds the limits above, Getnet rejects the request with a validation error naming the offending
sub_merchant field.Country and card-brand rules are evaluated separately from the base contract. A request that satisfies the six required fields can still be declined when a market-specific field is absent — for example a Mastercard transaction in Argentina without
iva_category.For the error response format and the full list of payment error codes, see the Errors reference.
Related resources
On this page
Payment Facilitators