#Adquirentes

#Prisma

Campos obrigatórios no additional_acquirer_data para o roteamento com Prisma:

• card_holder_name

#PagBank

Campos obrigatórios no additional_acquirer_data para o roteamento com PagBank:

• payer.document

• payer.email

• payer.name

---

#Payway

A Payway (Argentina, modelo agregador PCI) aceita transações em ARS e USD (outras moedas são convertidas para ARS).

Campos obrigatórios no acquirer_additional_data para o roteamento com Payway:

• Identificação do portador do cartão — obrigatória em toda autorização, por uma das duas formas:

  • payway_pci.card_holder_identification_type (dni ou cuil) + payway_pci.card_holder_identification_number; ou

  • card_extra_info.card_holder_document — o tipo é inferido pelo tamanho do número (após remover pontuação): 7 a 8 dígitos = dni, 11 dígitos = cuil. Outros tamanhos não resolvem a identificação e a transação é recusada antes do envio.

• submerchant.document — documento do comércio final, com 7, 8 ou 11 dígitos (DNI, CUIT ou CUIL). CNPJ de 14 dígitos é rejeitado, não truncado.

• submerchant.address — endereço do comércio final.

• submerchant.mcc — obrigatório caso não esteja no cadastro do canal.

• payway_pci.aggregator_name — obrigatório caso não esteja no cadastro (extra_data.payway_aggregator_name). Sem ele, a Payway ignora silenciosamente todo o bloco de dados do agregador (a transação é aprovada, mas sem os dados de agregador).

Campos recomendados no submerchant (alimentam o bloco de agregador enviado à Payway): id, name, phone_number, email, url, address_number, zip_code, city, state, country.

Quando enviado, customer.ip_address é repassado à Payway junto dos dados do cartão.

#Campos aceitos em payway_pci

#Fallbacks — de onde vem cada dado quando não enviado no request

O que vem no request sempre tem precedência. Quando um campo não é enviado, o sistema resolve nesta ordem:

O próprio submerchant também tem fallback do cadastro da loja: quando um campo não vem no request, é usado o dado cadastrado no gs-payment — document, name, phone_number, email, mcc e o endereço completo. Exceções sem fallback: url (só vem do request) e os campos exclusivos do payway_pci marcados "sem fallback" (ex.: product, sub_agrupator).

Exemplo — agregador PCI completo + identificação do portador:

{
  "transaction_data": {
    "card": {
      "number": "5115221334077040",
      "expiry_date": "0493",
      "security_code": "200",
      "holder_name": "JOSE SILVA"
    }
  },
  "acquirer_additional_data": {
    "card_extra_info": {
      "card_holder_document": "20123456789"
    },
    "submerchant": {
      "id": "1233333222",
      "mcc": "8931",
      "name": "Loja do ABS",
      "document": "30123456",
      "phone_number": "4899999999",
      "email": "contato@loja.gsurfnet.com",
      "url": "loja.gsurfnet.com",
      "address": "Rua Jose Antonio Lobo",
      "address_number": "890",
      "zip_code": "88495000",
      "city": "Garopaba",
      "state": "SC",
      "country": "BRA"
    },
    "customer": {
      "name": "Jose Silva",
      "email": "josesilva@gsurfnet.com",
      "ip_address": "200.201.202.203",
      "document": "51115672088"
    },
    "payway_pci": {
      "description": "Compra online",
      "aggregator_name": "GSURF",
      "product": "Remera XL",
      "sub_agrupator": "Sub Agregador X",
      "merchant_url": "https://loja.gsurfnet.com/checkout",
      "merchant_email": "comercio@loja.gsurfnet.com",
      "geographic_code": "88495",
      "origin_country": "032",
      "province": "B",
      "bill_to_pay": "000654",
      "bill_to_refund": "000655",
      "indicator_override": "1",
      "card_holder_identification_type": "cuil",
      "card_holder_identification_number": "20-12345678-9",
      "card_holder_birthday": "01011990",
      "card_holder_door_number": 890
    }
  }
}

Notas do exemplo:

• card.holder_name (no bloco transaction_data.card) alimenta o card_holder_name enviado à Payway — quando ausente, vai vazio.

• A identificação do portador foi enviada nas duas formas para ilustrar: payway_pci.card_holder_identification_* tem precedência; o card_extra_info.card_holder_document é o fallback (na prática, envie apenas uma).

• seller_id (só Amex) e gateway_id (só Mastercard, "solo gateways") foram omitidos por serem específicos de cenários que a maioria das integrações não usa.

Exemplo — network token (Mastercard tokenizado):

{
  "transaction_data": {
    "card": {
      "number": "5115221334077040",
      "expiry_date": "0493",
      "security_code": "200",
      "holder_name": "JOSE SILVA"
    }
  },
  "acquirer_additional_data": {
    "submerchant": {
      "mcc": "8931",
      "document": "30123456",
      "address": "Rua Jose Antonio Lobo",
      "zip_code": "88495000"
    },
    "payway_pci": {
      "aggregator_name": "GSURF",
      "card_holder_identification_type": "cuil",
      "card_holder_identification_number": "20-12345678-9",
      "network_payment_token": "5115221334077040",
      "network_token_eci": "05",
      "network_token_cryptogram": "AgAAAAAAAIR8CQrXcIhbQAAAAAA=",
      "token_expiration_month": "12",
      "token_expiration_year": "28",
      "token_requestor_id": "50110030273",
      "network_token_device_type": "2",
      "remote_commerce_acceptor_identifier": "merchant-rci-123"
    }
  }
}

Notas do exemplo:

• O bin enviado à Payway deve ser sempre o do cartão real (card.number), nunca o do token — por isso o number acompanha o request mesmo no fluxo tokenizado.

• network_token_device_type e remote_commerce_acceptor_identifier só são repassados para Mastercard.

• Em pagamento com network token, o envio ao antifraude (fraud_detection.send_to_cs) é forçado para false.

#Rede

Importante: A ausência de qualquer um dos campos obrigatórios pode resultar na rejeição da transação pela adquirente REDE.

Todos os campos listados abaixo devem ser obrigatóriamente enviados no payload quando o adquirente utilizado for a Rede para garantir o correto processamento da transação no fluxo Data Only.

#Campos obrigatórios para funcionamento do Data Only

• data_only_information.device_information.device_type

• data_only_information.device_information.color_depth

• data_only_information.device_information.java_enabled

• data_only_information.device_information.language

• data_only_information.device_information.screen_height

• data_only_information.device_information.screen_width

• data_only_information.device_information.time_zone_off_set

• data_only_information.device_information.user_agent

• data_only_information.device_information.ip_address

• data_only_information.billing_information.country

• data_only_information.billing_information.state

• data_only_information.billing_information.city

• data_only_information.billing_information.address

• data_only_information.billing_information.address_number

• data_only_information.billing_information.neighborhood

• data_only_information.billing_information.zip_code

• data_only_information.billing_information.name

• data_only_information.billing_information.email

• data_only_information.billing_information.phone_number

#Estrutura de dados adicionais para Rede

{
    "acquirer_additional_data": {
        "data_only_information": {
            "device_information": {
                "device_type": "BROWSER",
                "color_depth": "30",
                "java_enabled": "false",
                "language": "pt-BR",
                "screen_height": "937",
                "screen_width": "1920",
                "time_zone_off_set": "180",
                "user_agent": "2313ewqewqe21",
                "ip_address": "192.168.123.132"
            },
            "billing_information": {
                "country": "BRA",
                "state": "SC",
                "city": "Garopaba",
                "address": "Rua jose antonio lobo",
                "address_number": "890",
                "neighborhood": "Ferraz",
                "zip_code": "88495000",
                "name": "John Snow",
                "email": "carlos.sousa@gsurfnet.com",
                "phone_number": "40028922"
            }
        }
    }
}

#Especificação dos campos

#Bloco device_information

#Bloco billing_information

#Dados de contato do subestabelecimento (exigência Mastercard)

Vigência 01/08/2026: para transações de e-commerce (cartão não presente), a Mastercard passa a exigir os dados de contato do subestabelecimento (a loja) — site e telefone — no objeto acquirer_additional_data.submerchant. Estes campos são encaminhados à Rede.

Importante: os campos submerchant.url e submerchant.phone_number não são preenchidos pelo cadastro da loja na base gsurf — precisam ser enviados no payload. Em pagamentos avulsos, envie em cada requisição; em recorrência, envie na criação da recorrência (fica salvo e é reutilizado nas cobranças seguintes).

Valores fora do formato esperado são descartados silenciosamente — a transação segue, mas o dado não trafega ao adquirente. Valide o conteúdo antes de enviar.

#Estrutura do subestabelecimento (Rede)

{
    "acquirer_additional_data": {
        "submerchant": {
            "id": "12345",
            "mcc": "1234",
            "document": "12312312387",
            "phone_number": "4899999999",
            "url": "loja.gsurf.com.br"
        }
    }
}

#Adiq

Importante: A ausência de qualquer um dos campos obrigatórios pode resultar na rejeição da transação pela adquirente Adiq.

Todos os campos listados abaixo devem ser obrigatóriamente enviados no payload quando o adquirente utilizado for a Adiq para garantir o correto processamento da transação .

#Campos obrigatórios

• customer.address

• customer.address_number

• customer.neighborhood

• customer.city

• customer.state

• customer.country

• customer.document

• customer.name

• customer.email

• customer.phone_number

• customer.ip_address

• customer.zip_code

• card_holder_name

#Estrutura de dados adicionais para Adiq

{
    "acquirer_additional_data": {
        "customer": {
            "address": "Rua José Antonio Lobo",
            "address_number": "890",
            "neighborhood": "Ferraz",
            "city": "Garopaba",
            "state": "SC",
            "country": "BRA",
            "document": "12321321321",
            "name": "John Snow",
            "email": "johnsnow@gsurfnet.com",
            "phone_number": "48996420377",
            "ip_address": "1231321312",
            "zip_code": "88495000"
        },
        "card_holder_name": "John Snow"
    }
}

#Descrição dos Campos

customer

• customer.address: Logradouro do endereço do comprador.

• customer.address_number: Número do endereço do comprador.

• customer.neighborhood: Bairro do endereço do comprador.

• customer.city: Cidade do endereço do comprador.

• customer.state: Estado do endereço do comprador.

• customer.country: País do endereço do comprador.

• customer.zip_code: CEP do endereço do comprador.

• customer.document: Documento de identificação do comprador.

• customer.name: Nome completo do comprador.

• customer.email: Endereço de e-mail do comprador.

• customer.phone_number: Número de telefone do comprador.

• customer.ip_address: Endereço IP do dispositivo do comprador.

card_holder

• card_holder_name: Nome do titular do cartão utilizado na transação.

#Antifraude

#Clear

Campos obrigatórios no anti_fraud_data para o roteamento com a Clear Sale:

• order_information.bill_to.first_name

• order_information.bill_to.last_name

• order_information.bill_to.email

Campos obrigatórios no envio do endereço na Clear Sale, tanto para bill_to ou ship_to:

• order_information.bill_to.address

• order_information.bill_to.address_number

• order_information.bill_to.neighborhood

• order_information.bill_to.city

• order_information.bill_to.state

• order_information.bill_to.zip_code

Campos obrigatórios no envio do telefone na Clear Sale, tanto para bill_to ou ship_to:

• order_information.bill_to.phone_number_type

• order_information.bill_to.phone_number