logo ← gs-payment-ecommerce / Integração Ecommerce Cartão

Integração Ecommerce Cartão

#🔹 1. Introdução

Este documento tem como objetivo guiar terceiros na integração com o Gspayments, explicando o processo de obtenção de credenciais, autenticação e consumo das APIs disponíveis.

Acesse o Portal SC3.

#🔹 2. Configuração do Gspayments

Importante: O Gateway Gspayment opera com um sistema de escopos hierárquicos que define a prioridade das configurações aplicadas durante o fluxo transacional. Esse sistema segue uma estrutura em formato de funil, onde os escopos são avaliados em ordem de prioridade:

  • CANAL (maior prioridade)

  • LOJISTA (prioridade intermediária)

  • PARCEIRO (menor prioridade)

Esse mecanismo garante que, no momento da transação, o gateway percorra os escopos de cima para baixo até encontrar uma configuração válida. Por exemplo:

Se uma configuração de roteamento estiver ausente no escopo CANAL, o gateway continuará a busca no próximo nível.

Ao encontrar uma configuração válida no escopo LOJISTA, essa será acatada imediatamente, ignorando o escopo PARCEIRO, mesmo que este também possua parametrizações.

Esse modelo de escopo é aplicado universalmente dentro do gateway, impactando todos os tipos de configuração: roteamento, antifraude, adquirente, entre outros.

Portanto, ao parametrizar regras dentro do Gspayment, é essencial considerar a hierarquia dos escopos, garantindo que as configurações sejam aplicadas conforme a prioridade desejada no ambiente transacional.

#2.1 - Configuração no Escopo Parceiro

  1. Acesse Configurações > Gateway > Configurações do Parceiro.
    Este é o ponto inicial onde todas as parametrizações específicas do parceiro serão realizadas no gateway.

  2. Acesse a aba Credenciais.
    Esta seção é responsável por armazenar as informações de autenticação e integração com os provedores (como adquirentes, bancos ou serviços de antifraude).

  3. Selecione o tipo de provedor que deseja configurar — como Cartão, Pix, Boleto ou Antifraude — e cadastre as credenciais fornecidas pelo respectivo provedor.

  4. Essas credenciais normalmente incluem chaves de API, tokens, merchant IDs ou senhas.

  5. É possível repetir o processo para diferentes provedores, conforme a necessidade do parceiro.

  6. Acesse a aba Integrações, selecione o provedor correspondente e vincule a credencial cadastrada.
    Essa ação garante que o gateway saiba qual credencial utilizar durante o fluxo transacional.

  7. Vá até a aba Roteamento para definir como as transações serão direcionadas.

  8. Você pode criar um roteamento padrão, aplicável a todas as transações do parceiro, ou um roteamento específico, com regras baseadas em condições principalmente das bandeiras ou números de parcelas.

  9. O sistema seguirá sempre a prioridade de escopos: Canal > Lojista > Parceiro.

  10. Configure os hooks (eventos de notificação).

  11. Primeiro, é necessário criar uma credencial de hook, que define a URL de destino e as chaves de autenticação do receptor. Esse processo é semelhante as informações passadas no passo 2.

  12. Depois, selecione os eventos que o sistema deve enviar ao parceiro, como: AUTHORIZATION, CONFIRMATION, REFUNDED, entre outros.

  13. Essa configuração garante que o parceiro receba atualizações em tempo real do fluxo de transações.

⚠️ Importante: Caso exista uma configuração válida em escopos superiores (Canal ou Lojista), ela terá prioridade sobre o escopo Parceiro. Sempre revise os escopos ativos para evitar conflitos de roteamento e integrações.

#2.2 - Configuração no Escopo Lojista

  1. Acesse Acessar uma Loja > Config. Gateway > Configurações.
    Esta seção permite configurar integrações e regras de transação específicas para uma loja individual dentro do ambiente do gateway.

  2. Acesse a aba Credenciais.
    Aqui você poderá cadastrar as credenciais de autenticação para integração com provedores como adquirentes, bancos e sistemas de antifraude.

  3. Selecione o provedor que deseja integrar (ex: Cartão, Pix, Boleto, Antifraude) e cadastre as credenciais fornecidas pelo respectivo provedor.

  4. As credenciais podem incluir dados como Merchant ID, API Key, Client Secret ou outras informações específicas de autenticação.

  5. Repita o processo para todos os provedores que a loja utilizará nas transações.

  6. Vá até a aba Integrações, selecione o provedor desejado e vincule a credencial cadastrada.
    Esse passo garante que, no momento da transação, o gateway saiba exatamente qual configuração utilizar para comunicação com o provedor.

  7. Acesse a aba Roteamento e defina a regra de roteamento para a loja.

  8. Você pode criar um roteamento padrão, aplicável a todas as transações do parceiro, ou um roteamento específico, com regras baseadas em condições principalmente das bandeiras ou números de parcelas.

  9. Essa configuração será usada caso não exista uma definição em escopo superior (Canal).

  10. Configure os hooks para garantir a comunicação de eventos da plataforma com a loja.

  11. Antes de selecionar os eventos, é necessário criar uma credencial de hook contendo a URL e o método de autenticação que será utilizado para receber os eventos. Esse processo é semelhante as informações passadas no passo 2.

  12. Depois, defina os eventos relevantes como AUTHORIZATION, CONFIRMATION, REFUNDED, entre outros.

  13. Essa etapa garante que a loja receba notificações em tempo real sobre o status das transações.

🔁 Importante: Caso exista configuração válida no escopo Canal, ela terá prioridade sobre o escopo da Loja. O gateway sempre respeita a hierarquia: Canal > Lojista > Parceiro.

#2.3 - Configuração no Escopo Canal

  1. Acesse Acessar uma Loja > Config. Gateway > Canal.
    O escopo de Canal é o nível mais alto de configuração no gateway, com prioridade máxima sobre Lojista e Parceiro. Ideal para parametrizações individuais que serão herdadas pelas lojas vinculadas.

  2. Crie o canal, informando o MCC (Merchant Category Code) e o Soft Descriptor.

  3. O MCC identifica o tipo de atividade comercial da empresa.

  4. O Soft Descriptor é o texto que aparece na fatura do cliente, sendo obrigatório para personalização da experiência de cobrança. Essa mesma informação pode ser passada posteriormente na requisição de criação de transação.

  5. Acesse a aba Credenciais para cadastrar os dados de autenticação dos provedores.

  6. As credenciais são necessárias para estabelecer comunicação com adquirentes, bancos e serviços auxiliares como antifraude.

  7. Selecione os provedores disponíveis (Cartão, Pix, Boleto, Antifraude, etc.) e cadastre a credencial utilizando as informações fornecidas por cada provedor.

  8. Dados comuns incluem: merchantId, chave secreta, client ID, e endpoint de autenticação.

  9. Repita o processo para cada provedor que será utilizado nesse canal.

  10. Acesse a aba Integrações e vincule cada provedor à respectiva credencial cadastrada.
    Esse vínculo permite ao gateway utilizar automaticamente as credenciais corretas durante as transações de todas as lojas associadas ao canal.

  11. Vá para a aba Roteamento e configure as regras de roteamento padrão ou específicas.

  12. Você pode criar um roteamento padrão, aplicável a todas as transações do parceiro, ou um roteamento específico, com regras baseadas em condições principalmente das bandeiras ou números de parcelas.

  13. A configuração feita aqui prevalecerá sobre qualquer outra realizada em escopos inferiores (Lojista ou Parceiro).

roteamento_gspayments.jpg

⚠️ Importante: O escopo de Canal tem prioridade máxima no sistema de hierarquia do gateway. Se existir uma configuração válida aqui, ela será usada em detrimento das definições nos escopos de Lojista e Parceiro.

  1. Configure os hooks a serem recebidos (necessário criar uma credencial de hook antes), definindo quais eventos são relevantes para garantir o fluxo correto da operação.

#🔹 3. Acesso às APIs

Antes de iniciar a integração, é necessário criar um App Client no portal SC3 para obter credenciais de acesso e manipular as API do gateway GsPayment

#3.1 - Passos iniciais para criar um App Client:

  1. Acesse uma loja cadastrada no portal.

  2. Dentro da loja, localize o menu lateral e clique em Menu > Controle de Acesso > Cadastrar App Client.

#3.2 - Configuração das Rotas de API

  1. Acesse a aba Configurações do Módulo.

  2. Selecione o canal desejado (⚠️ é obrigatório que exista ao menos um canal configurado).

  3. Vá até a seção Rotas de API.

  4. Localize a rota Gateway de Pagamentos Gsurf (Gspayments).

  5. Marque todos os endpoints disponíveis para essa rota.

  6. Clique em Salvar.

  7. Após salvar, copie e armazene com segurança as seguintes informações:

  8. Client Secret (visível somente no momento da criação).

  9. Client ID (visível após a criação do App Client).

Por fim, com o famigerado AppClient em mãos vamos realizar uma requisição para gerar um token de Por fim, com o App Client criado e as credenciais em mãos, será necessário realizar uma requisição para gerar um token de acesso.

Esse token é obrigatório para autenticar todas as demais requisições feitas ao Gateway de Pagamentos.
A requisição deve ser feita para o Gmac, que é a API responsável pela autenticação.

O token gerado tem validade de 2 horas e deve ser incluído no cabeçalho (Authorization) das chamadas subsequentes às APIs do Gateway.

Observação: Remover o -hml das URLs caso seja produção

#3.3 📌Requisição Token

🛠 Método: POST
🔗 URL:

https://api-hml.gsurfnet.com/gmac-v1/oauth2/token

#Autenticação: Basic Auth

  • Username = clientId

  • Password = clientSecret

Resultado: Obtenção do access_token

#🔹 4. Criar uma Transação de Cartão

Este endpoint permite criar uma transação de pagamento com cartão.

#📌 Requisição

🛠 Método: POST
🔗 URL:

https://api-hml.gsurfnet.com/gs-payment-ecommerce/v1/payments/card

#4.1 Estrutura da Requisição

#Headers:

Content-Type: application/json
Authorization: Bearer {access_token}

#Body (Exemplo JSON):

{
    "sale_data": {
        "order_id": "HIDQV4ISHO",
        "amount": 98722,
        "merchant_correlation_id": "OZZ9V73SCV",
        "installments": 1
    },
    "additional_data": {
        "auto_capture": true,
        "use_anti_fraud": true,
        "use_data_only": true,
        "transaction_type": "CREDIT"
    },
    "split_data": [
        {
            "submerchant_id": "71673990000177",
            "amount": 4341,
            "fee_division": 15,
            "sub_order_id": "E7EH0O3N7M"
        },
        {
            "submerchant_id": "71673990000176",
            "amount": 4341,
            "fee_division": 20,
            "sub_order_id": "E7EH0O3N7M"
        },
        {
            "submerchant_id": "71673990000178",
            "amount": 4341,
            "fee_division": 20,
            "sub_order_id": "E7EH0O3N7M"
        }
    ],
    "hook_data": {
        "url": "http://gsurfnet.com/payment/notification",
        "credentials_id": "a95eb53d-82cc-4f84-ae2c-56898652340a"
    }
}

#4.2 Parâmetros da Requisição

Parâmetro

Tipo

Obrigatório

Descrição

amount

integer

✅

Valor da venda sem separador decimal (ex: 1000 = R$ 10,00).

merchant_correlation_id

string

❌

Identificador único para referência da loja.

order_id

string

❌

Número do pedido da loja.

installments

integer

❌

Número de parcelas (para Débito, sempre 1).

submerchant_id

string

❌

Identificador da loja cadastrada no Gspayments.

auto_capture

boolean

❌

Define se a transação deve ser capturada automaticamente. Caso não seja enviado o parametro, o mesmo automaticamente será atribuido como "false"

use_anti_fraud

boolean

❌

Habilita o uso de anti-fraude se configurado. Caso o mesmo não seja passado será ignorado no fluxo transacional

transaction_type

string

❌

Tipo da transação (CREDIT, DEBIT, PRE_PAID). Caso o mesmo não seja passado a transação será atribuida automaticamente como CREDIT

installment_type

string

❌

Tipo de parcelamento (BY_ISSUER ou BY_MERCHANT).

use_data_only

string

❌

Habilita o modelo de autenticação DataOnly 3DS no fluxo transação (Atualmente funcional somente para Rede)*.

hook_data.url

string

✅

URL para notificações por webhook.

hook_data.credentials_id

string

✅

ID da credencial cadastrada.

split_data

array

❌

Dados de divisão de pagamento entre submercantes.

dynamic_data

array

❌

Informações adicionais para relatórios.

#4.3 Respostas Possíveis

#🟢 201 - Sucesso

{
    "sale_data": {
        "amount": 98722,
        "merchant_correlation_id": "OZZ9V73SCV",
        "order_id": "HIDQV4ISHO",
        "installments": 1,
        "submerchant_id": "31705060000133"
    },
    "payment_data": {
        "gti": "beab65d1-7521-48a4-baeb-96eb4f6bc0c8",
        "status": "NEW",
        "amount_paid": 0,
        "channel": "TesteGabriel",
        "terminal_id": "7b5096ad-08b2-461b-8729-9e445d5689a3",
        "creation_time": "2025-06-11T14:39:15.375713",
        "update_time": "2025-06-11T14:39:15.392995",
        "subacquirer_document": "05643319000159",
        "effective_time": null,
        "confirm_time": null,
        "authorize_time": null,
        "capture_time": null
    },
    "hook_data": {
        "url": "http://gsurfnet.com/payment/notification",
        "credentials_id": "a95eb53d-82cc-4f84-ae2c-56898652340a"
    },
    "split_data": [
        {
            "submerchant_id": "71673990000177",
            "amount": 4341,
            "fee_division": 15,
            "sub_order_id": "E7EH0O3N7M"
        },
        {
            "submerchant_id": "71673990000176",
            "amount": 4341,
            "fee_division": 20,
            "sub_order_id": "E7EH0O3N7M"
        },
        {
            "submerchant_id": "71673990000178",
            "amount": 4341,
            "fee_division": 20,
            "sub_order_id": "E7EH0O3N7M"
        }
    ]
}

#🔴 Erros Comuns

Código

Motivo

400

Requisição inválida (parâmetros ausentes ou incorretos).

401

Token de autenticação inválido ou expirado.

403

Permissão negada para a ação solicitada.

404

Recurso não encontrado.

500

Erro interno no servidor.

#🔹 5. Efetivar uma Transação de Cartão

Este endpoint permite efetivar uma transação de cartão.

#📌 Requisição

🛠 Método: POST
🔗 URL:

https://api-hml.gsurfnet.com/gs-payment-ecommerce/v1/payments/card/{gti}

#5.1 Estrutura da Requisição

#Headers:

Content-Type: application/json
Authorization: Bearer {access_token}

#Path Parameters:

Parâmetro

Tipo

Obrigatório

Descrição

gti

string

✅

Identificador único da transação Gsurf (36 caracteres).

#Body (Exemplo JSON):

{
    "transaction_data": {
        "card": {
            "number": "5448280000000007", 
            "expiry_date": "0128",
            "security_code": "123"
        },
        "anti_fraud_data": {
            "client_reference_information": {
                "code": "12345678"
            },
            "buyer_information": {
                "merchant_customer_id": "12312312387"
            },
            "device_information": {
                "finger_print_session_id": "98d3n9d823hd89n23x8932nd8",
                "ip_address": "fe80::986d:5ac4:6ec0:8b26%21"
            },
            "order_information": {
                "bill_to": {
                    "email": "teste@teste.com",
                    "first_name": "Gabriel",
                    "last_name": "Aprova",
                    "phone_number_type": 1,
                    "phone_number": "48987654321",
                    "address": "Rua José Antônio Lobo",
                    "address_number": "200",
                    "neighborhood": "Bairro Ferraz",
                    "city": "Garopaba",
                    "state": "SC",
                    "country": "BR",
                    "zip_code": "88495000"
                },
                "ship_to": {
                    "email": "teste@teste.com",
                    "first_name": "Gabriel",
                    "last_name": "Marques",
                    "phone_number_type": 1,
                    "phone_number": "48987654321",
                    "address": "Rua José Antônio Lobo",
                    "address_number": "200",
                    "neighborhood": "Bairro Ferraz",
                    "city": "Garopaba",
                    "state": "SC",
                    "country": "BR",
                    "zip_code": "88495000"
                },
                "line_items": [
                    {
                        "unit_price": 100,
                        "quantity": 1,
                        "product_code": "87654321",
                        "product_name": "Produto de Teste1",
                        "product_SKU": "87654321"
                    },
                    {
                        "unit_price": 50,
                        "quantity": 5,
                        "product_code": "12345678",
                        "product_name": "Produto de Teste2",
                        "product_SKU": "12345678"
                    },
                    {
                        "unit_price": 20,
                        "quantity": 10,
                        "product_code": "38474837",
                        "product_name": "Produto de Teste3",
                        "product_SKU": "38474837"
                    }
                ]
            },
            "merchant_defined_information": [
                {
                    "key": "MDD10",
                    "value": "GSURF"
                },
                {
                    "key": "CARTAO",
                    "value": "5448 2800 0000 0007"
                },
                {
                    "key": "MDD11",
                    "value": "GABRIEL MARQUES"
                }
            ]
        }
    },
    "acquirer_additional_data": {
        "card_extra_info": {
            "card_holder_name": "Gabriel Marques de Campos"
        },
        "submerchant": {
            "document": "09583156981",
            "name": "Gabriel !- Teste -",
            "trade_name": "Gabriel Teste",
            "address": "The wall avenue",
            "neighborhood": "The Wall",
            "city": "Garopaba",
            "state": "SC",
            "zip_code": "88495000"
        },
        "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": "Gabriel Marques",
                "email": "gabriel.marques@gsurfnet.com",
                "phone_number": "48991282027"
            }
        },
        "description_on_invoice": "GSURF - GABRIEL BANK LTDA"
    },
    "hook_data": {
        "url": "gsurfnet.com/payment/notification",
        "credentials_id": "a95eb53d-82cc-4f84-ae2c-56898652340a"
    }
}

#5.2 Parâmetros Importantes

Parâmetro

Tipo

Obrigatório

Descrição

number

string

✅

Numero do cartão

token

string

❌

Token do cartão tokenizado

expiry_date

string

✅

Expiração do cartão

security_code

string

✅

Código de segurança do cartão.

client_reference_information

string

❌

Código de referência do cliente para antifraude. Obrigatório somente se for utilizado antifraude

buyer_information

object

❌

Dados do cliente para antifraude. Obrigatório somente se for utilizado antifraude

device_information

object

❌

Dados do dispositivo para antifraude. Obrigatório somente se for utilizado antifraude

order_information

object

❌

Dados de cobrança, envio e itens do pedido.

merchant_defined_information

array

❌

Informações customizadas definidas pelo lojista (antifraude).

card_extra_infoe

object

❌

Dados adicionais do cartão

submerchant

object

❌

Dados da loja

description_on_invoice

string

❌

Descrição na fatura do comprador.

data_only_information.device_information

object

❌

Informações técnicas do dispositivo (ex: resolução, IP, etc).

data_only_information.billing_information

object

❌

Informações de cobrança adicionais do comprador.

hook_data.url

string

✅

URL para recebimento do webhook de resposta da transação.

hook_data.credentials_id

string

✅

ID das credenciais associadas ao webhook.

Importante resslatar que deve ser escolhido uma das duas opções de pagamento, cartão ou token

#5.3 Respostas Possíveis

#🟢 200 - Sucesso

{
    "sale_data": {
        "amount": 52297,
        "merchant_correlation_id": "TFKVOYL88V",
        "order_id": "HQFW7V3RDM",
        "installments": 1,
        "submerchant_id": "31705060000133"
    },
    "payment_data": {
        "gti": "d4ee96c5-39d7-4985-aef5-e363418c0898",
        "status": "AUTHENTICATION_IN_PROGRESS",
        "amount_paid": 0,
        "channel": "TesteGabriel",
        "terminal_id": "7b5096ad-08b2-461b-8729-9e445d5689a3",
        "creation_time": "2025-06-11T15:08:57",
        "update_time": "2025-06-11T15:08:57",
        "subacquirer_document": "05643319000159",
        "effective_time": "2025-06-11T15:09:04",
        "confirm_time": null,
        "authorize_time": null,
        "capture_time": null
    },
    "hook_data": {
        "url": "gsurfnet.com/payment/notification",
        "credentials_id": "a95eb53d-82cc-4f84-ae2c-56898652340a"
    },
    "split_data": [
        {
            "submerchant_id": "71673990000177",
            "amount": 8394,
            "fee_division": 15,
            "sub_order_id": "XXY4VIK4JQ"
        },
        {
            "submerchant_id": "71673990000176",
            "amount": 8394,
            "fee_division": 20,
            "sub_order_id": "XXY4VIK4JQ"
        },
        {
            "submerchant_id": "71673990000178",
            "amount": 8394,
            "fee_division": 20,
            "sub_order_id": "XXY4VIK4JQ"
        }
    ],
    "transaction_data": {
        "gsurf_usn": "250611200025",
        "entry_mode": "TOKEN",
        "transaction_type": "CREDIT",
        "installment_type": "BY_MERCHANT",
        "anti_fraud_analysis_data": {
            "status": "PENDING",
            "code": null,
            "message": null,
            "provider_data": {
                "provider_id": "7316ae1b-c9a0-4060-896f-383a7dd33347",
                "provider_name": "cyber",
                "authorization_response": null,
                "review_response": null
            }
        },
        "data_only_information": {
            "status": "PENDING",
            "code": null,
            "message": null
        },
        "provider_data": {
            "provider_name": "rede",
            "provider_id": "16380c7b-f478-407f-9c2b-a4e0531cef9e",
            "gsurf_correlation_id": null,
            "acquirer_authorization_usn": null,
            "acquirer_confirmation_usn": null,
            "provider_usn": null,
            "authorization_code": null,
            "acquirer_name": null,
            "response_code": null,
            "response_message": null,
            "acquirer_response_code": null,
            "acquirer_response_message": null
        },
        "card_data": {
            "masked_card": "544828******0007",
            "card_brand": {
                "description": "Mastercard",
                "gsurf_code": 55
            }
        },
        "maintenance_request_times": 0
    }
}

#🔴 Erros Comuns

Código

Motivo

400

Requisição inválida (parâmetros ausentes ou incorretos).

401

Token de autenticação inválido ou expirado.

403

Permissão negada para a ação solicitada.

404

Recurso não encontrado.

500

Erro interno no servidor.

#🔹 6. Confirmar uma Transação (Captura Manual)

Caso a transação tenha sido criada com auto_capture = false, será necessário capturá-la manualmente com este endpoint.

#📌 Requisição

🛠 Método: PUT
🔗 URL:

https://api-hml.gsurfnet.com/gs-payment-ecommerce/v1/payments/card/{gti}/capture

#6.1 Estrutura da Requisição

#Headers:

Content-Type: application/json
Authorization: Bearer {access_token}

#Path Parameters:

Parâmetro

Tipo

Obrigatório

Descrição

gti

string

✅

Identificador único da transação Gsurf (36 caracteres).

#Body (Exemplo JSON):

{
  "confirm": true
}

#6.2 Parâmetros Importantes

Parâmetro

Tipo

Obrigatório

Descrição

confirm

boolean

✅

Indica se a transação deve ser confirmada (true) ou desfeita (false).

#6.3 Respostas Possíveis

#🟢 200 - Sucesso

{
  "payment_data": {
    "gti": "8d561c7d-0dda-4185-bc86-5a78a070b2ca",
    "status": "CONFIRMED",
    "amount_paid": 1000,
    "channel": "ECOMMERCE",
    "creation_time": "2021-07-12T12:00:00Z",
    "update_time": "2021-07-12T12:00:00Z",
    "subacquirer_document": "1231231000112"
  }
}

#🔴 Erros Comuns

Código

Motivo

400

Requisição inválida (parâmetros ausentes ou incorretos).

401

Token de autenticação inválido ou expirado.

403

Permissão negada para a ação solicitada.

404

Recurso não encontrado.

500

Erro interno no servidor.

#🔹 7. Tokenizar um Cartão

A tokenização de cartão permite armazenar cartões de crédito para uso posterior sem a necessidade de solicitar novamente os dados ao comprador. O código de segurança (CVV) não é armazenado.

#7.1 Criar Armazenamento de Cartão

Este endpoint cria os dados de acesso para armazenar um cartão e retorna um card_id e store_token, que serão usados na próxima etapa.

#📌 Requisição

🛠 Método: POST
🔗 URL:

https://api-hml.gsurfnet.com/gs-payment-ecommerce/v1/card-storage/access-token

#Headers:

Content-Type: application/json
Authorization: Bearer {access_token}

#Body (Exemplo JSON):

{
  "merchant_correlation_id": "026b0627-83dc-42a0-bacc-a06f0da1227f",
  "customer_id": "12312312387"
}

#7.1.2 Parâmetros Importantes

Parâmetro

Tipo

Obrigatório

Descrição

merchant_correlation_id

string

❌

Identificador único da loja para referência.

customer_id

string

✅

Identificação única do comprador para armazenamento do cartão.

#7.1.3 Respostas Possíveis

#🟢 201 - Sucesso

{
  "card_id": "e9e3ce5d-7bb6-47b5-9aa3-3e633d63f9e4",
  "store_token": "qB5iz9vf2OGWqnL8DOcwhTgk0xyYYByqmK8T5QV9jJNVXTWnuv8jhPAdgdYf9VI3",
  "merchant_correlation_id": "026b0627-83dc-42a0-bacc-a06f0da1227f",
  "customer_id": "12312312387"
}

#🔴 Erros Comuns

Código

Motivo

400

Requisição inválida (parâmetros ausentes ou incorretos).

401

Token de autenticação inválido ou expirado.

403

Permissão negada para a ação solicitada.

404

Recurso não encontrado.

500

Erro interno no servidor.

#7.2 Efetuar Armazenamento do Cartão

Após a criação dos dados de acesso (store_token e card_id), este método permite realizar a tokenização do cartão diretamente do front-end da loja, sem necessidade de passar pelo backend.

#📌 Requisição

🛠 Método: POST
🔗 URL:

https://api-hml.gsurfnet.com/gs-payment-ecommerce/v1/card-storage

#Headers:

Content-Type: application/json
Store-Token: {store_token}
Authorization: Bearer {access_token}

#Body (Exemplo JSON):

{
  "card": {
    "number": "1234123412341234",
    "expiry_date": "1225"
  }
}

#7.2.2 Parâmetros Importantes

Parâmetro

Tipo

Obrigatório

Descrição

store_token

string

✅

Token de segurança gerado na requisição anterior. Válido por 5 minutos.

number

string

✅

Número do cartão.

expiry_date

string

✅

Mês e ano de validade do cartão no formato MMYY.

#7.2.3 Respostas Possíveis

#🟢 201 - Sucesso

{
  "card_id": "e9e3ce5d-7bb6-47b5-9aa3-3e633d63f9e4",
  "card_bin": "123456",
  "card_end": "1234",
  "merchant_correlation_id": "026b0627-83dc-42a0-bacc-a06f0da1227f",
  "customer_id": "12312312387"
}

#🔴 Erros Comuns

Código

Motivo

400

Requisição inválida (parâmetros ausentes ou incorretos).

401

Token de autenticação inválido ou expirado.

403

Permissão negada para a ação solicitada.

404

Recurso não encontrado.

500

Erro interno no servidor.

#7.2.4 Erros Comuns

Código

Motivo

400

Requisição inválida (parâmetros ausentes ou incorretos).

401

Token de autenticação inválido ou expirado.

403

Permissão negada para a ação solicitada.

404

Recurso não encontrado.

500

Erro interno no servidor.

#🔹 8. Consultar uma Transação de Cartão

Este endpoint permite consultar os detalhes de uma transação de cartão específica a partir do gti.

#📌 Requisição

🛠 Método: GET
🔗 URL:

https://api-hml.gsurfnet.com/gs-payment-ecommerce/v1/payments/card/{gti}

#8.1 Estrutura da Requisição

#Headers:

Content-Type: application/json
Authorization: Bearer {access_token}

#Path Parameters:

Parâmetro

Tipo

Obrigatório

Descrição

gti

string

✅

Identificador único da transação Gsurf (36 caracteres).

#8.2 Respostas Possíveis

#🟢 200 - Sucesso

{
  "sale_data": {
    "amount": 1000,
    "merchant_correlation_id": "026b0627-83dc-42a0-bacc-a06f0da1227f",
    "order_id": "12345678",
    "installments": 1,
    "submerchant_id": "12312312387"
  },
  "payment_data": {
    "gti": "8d561c7d-0dda-4185-bc86-5a78a070b2ca",
    "status": "AUTHORIZED",
    "amount_paid": 1000,
    "channel": "ECOMMERCE",
    "creation_time": "2021-07-12T12:00:00Z",
    "update_time": "2021-07-12T12:00:00Z",
    "effective_time": "2021-07-12T12:00:00Z",
    "confirm_time": null,
    "subacquirer_document": "12312312000198"
  }
}

#8.3 Erros Comuns

Código

Motivo

400

Requisição inválida (parâmetros ausentes ou incorretos).

401

Token de autenticação inválido ou expirado.

403

Permissão negada para a ação solicitada.

404

Transação não encontrada.

500

Erro interno no servidor.

#🔹 9. Realizar uma Transação Zero Dollar (0Auth)

Este endpoint permite validar previamente se os dados do cartão e do portador estão corretos antes do processamento da transação.

#📌 Requisição

🛠 Método: POST
🔗 URL:

https://api-hml.gsurfnet.com/gs-payment-ecommerce/v1/payments/card/0dollar

#9.1 Estrutura da Requisição

#Headers:

Content-Type: application/json
Authorization: Bearer {access_token}

#Body (Exemplo JSON):

{
  "card_data": {
    "holder_name": "JHON SNOW",
    "number": "1234123412341234",
    "expiry_date": "1124",
    "security_code": "123"
  },
  "sale_data": {
    "installments": 1,
    "merchant_correlation_id": "026b0627-83dc-42a0-bacc-a06f0da1227f",
    "order_id": "12345678"
  }
}

#9.2 Parâmetros Importantes

Parâmetro

Tipo

Obrigatório

Descrição

holder_name

string

✅

Nome do portador do cartão.

number

string

✅

Número do cartão (obrigatório se não utilizar um token).

expiry_date

string

✅

Data de validade do cartão no formato MMYY.

security_code

string

✅

Código de segurança do cartão.

installments

integer

✅

Número de parcelas (padrão: 1).

merchant_correlation_id

string

❌

Identificador único da loja para referência.

order_id

string

❌

Número do pedido da loja.

#9.3 Respostas Possíveis

#🟢 201 - Sucesso

{
  "payment_data": {
    "gti": "8d561c7d-0dda-4185-bc86-5a78a070b2ca",
    "status": "AUTHORIZED",
    "amount_paid": 0,
    "channel": "ECOMMERCE",
    "creation_time": "2021-07-12T12:00:00Z",
    "update_time": "2021-07-12T12:00:00Z",
    "effective_time": "2021-07-12T12:00:00Z",
    "subacquirer_document": "1231231000112"
  }
}

#9.4 Erros Comuns

Código

Motivo

400

Requisição inválida (parâmetros ausentes ou incorretos).

401

Token de autenticação inválido ou expirado.

403

Permissão negada para a ação solicitada.

404

Recurso não encontrado.

500

Erro interno no servidor.

#🔹 10. Manutenção de Pendências

Este endpoint permite confirmar ou desfazer uma transação com erro. Se o status for CONFIRMATION_ERROR, uma nova tentativa de confirmação será realizada. Se for UNDOING_ERROR, uma nova tentativa de desfazimento será feita.

#📌 Requisição

🛠 Método: PUT
🔗 URL:

https://api-hml.gsurfnet.com/gs-payment-ecommerce/v1/payments/card/{gti}/maintenance

#10.1 Estrutura da Requisição

#Path Parameters:

Parâmetro

Tipo

Obrigatório

Descrição

gti

string

✅

Identificador único da transação Gsurf. Deve ter exatamente 36 caracteres.

#Headers:

Content-Type: application/json
Authorization: Bearer {access_token}

#Body (Exemplo JSON):

{
  "action": "CONFIRMATION"
}

#10.2 Parâmetros Importantes

Parâmetro

Tipo

Obrigatório

Descrição

action

string

✅

Ação a ser realizada na transação (CONFIRMATION, UNDOING).

#10.3 Respostas Possíveis

#🟢 200 - Sucesso

{
  "sale_data": {
    "amount": 1000,
    "merchant_correlation_id": "026b0627-83dc-42a0-bacc-a06f0da1227f",
    "order_id": "12345678",
    "installments": 1
  },
  "payment_data": {
    "gti": "8d561c7d-0dda-4185-bc86-5a78a070b2ca",
    "status": "AUTHORIZED",
    "amount_paid": 1000,
    "channel": "ECOMMERCE",
    "creation_time": "2021-07-12T12:00:00Z",
    "update_time": "2021-07-12T12:00:00Z",
    "effective_time": "2021-07-12T12:00:00Z",
    "subacquirer_document": "1231231000112"
  },
  "hook_data": {
    "url": "gsurfnet.com/payment/notification",
    "credentials_id": "d6f5a1d5-cadd-4d65-a136-c92614f45c40"
  },
  "transaction_data": {
    "gsurf_usn": "220419000026",
    "card_data": {
      "masked_card": "544828******0007",
      "card_brand": {
        "description": "Mastercard",
        "gsurf_code": 55
      }
    },
    "entry_mode": "virtual",
    "transaction_type": "CREDIT",
    "installment_type": "BY_MERCHANT",
    "anti_fraud_analysis_data": {
      "status": "ACCEPTED",
      "code": 100
    },
    "provider_data": {
      "response_message": "Success",
      "response_code": "00",
      "authorization_code": "877270",
      "acquirer_name": "rede",
      "provider_name": "e-sitef",
      "provider_id": "a29902a0-698b-437f-8d22-d7372375c729",
      "gsurf_correlation_id": "10012107201416187794",
      "acquirer_authorization_usn": "248530199",
      "acquirer_confirmation_usn": "960048487",
      "provider_usn": "248530199"
    }
  }
}

#🔴 Erros Comuns

Código

Motivo

400

Requisição inválida (parâmetros ausentes ou incorretos).

401

Token de autenticação inválido ou expirado.

403

Permissão negada para a ação solicitada.

404

Recurso não encontrado.

500

Erro interno no servidor.