Integração GSPayments 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 pelo link:
https://portal.homolog.gsurfnet.com/gsurf/login
Nota: substitua "gsurf" pelo nome da sua empresa na URL.
🔹 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
-
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. -
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). -
Selecione o tipo de provedor que deseja configurar — como Cartão, Pix, Boleto ou Antifraude — e cadastre as credenciais fornecidas pelo respectivo provedor.
- Essas credenciais normalmente incluem chaves de API, tokens, merchant IDs ou senhas.
-
É possível repetir o processo para diferentes provedores, conforme a necessidade do parceiro.
-
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. -
Vá até a aba Roteamento para definir como as transações serão direcionadas.
- 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.
-
O sistema seguirá sempre a prioridade de escopos: Canal > Lojista > Parceiro.
-
Configure os hooks (eventos de notificação).
- 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.
- Depois, selecione os eventos que o sistema deve enviar ao parceiro, como:
AUTHORIZATION,CONFIRMATION,REFUNDED, entre outros. - 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
-
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. -
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. -
Selecione o provedor que deseja integrar (ex: Cartão, Pix, Boleto, Antifraude) e cadastre as credenciais fornecidas pelo respectivo provedor.
- As credenciais podem incluir dados como Merchant ID, API Key, Client Secret ou outras informações específicas de autenticação.
-
Repita o processo para todos os provedores que a loja utilizará nas transações.
-
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. -
Acesse a aba Roteamento e defina a regra de roteamento para a loja.
- 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.
-
Essa configuração será usada caso não exista uma definição em escopo superior (Canal).
-
Configure os hooks para garantir a comunicação de eventos da plataforma com a loja.
- 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.
- Depois, defina os eventos relevantes como
AUTHORIZATION,CONFIRMATION,REFUNDED, entre outros. - 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
-
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. -
Crie o canal, informando o MCC (Merchant Category Code) e o Soft Descriptor.
- O MCC identifica o tipo de atividade comercial da empresa.
-
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.
-
Acesse a aba Credenciais para cadastrar os dados de autenticação dos provedores.
-
As credenciais são necessárias para estabelecer comunicação com adquirentes, bancos e serviços auxiliares como antifraude.
-
Selecione os provedores disponíveis (Cartão, Pix, Boleto, Antifraude, etc.) e cadastre a credencial utilizando as informações fornecidas por cada provedor.
- Dados comuns incluem: merchantId, chave secreta, client ID, e endpoint de autenticação.
-
Repita o processo para cada provedor que será utilizado nesse canal.
-
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. -
Vá para a aba Roteamento e configure as regras de roteamento padrão ou específicas.
- 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.
- A configuração feita aqui prevalecerá sobre qualquer outra realizada em escopos inferiores (Lojista ou Parceiro).
⚠️ 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.
- 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:
- Acesse uma loja cadastrada no portal.
- 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
- Acesse a aba Configurações do Módulo.
- Selecione o canal desejado (⚠️ é obrigatório que exista ao menos um canal configurado).
- Vá até a seção Rotas de API.
- Localize a rota Gateway de Pagamentos Gsurf (Gspayments).
- Marque todos os endpoints disponíveis para essa rota.
- Clique em Salvar.
- Após salvar, copie e armazene com segurança as seguintes informações:
- Client Secret (visível somente no momento da criação).
- 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.
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. |
🔹 7. 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
7.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
}
7.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). |
7.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. |
🔹 8. 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.
8.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"
}
8.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. |
8.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. |
8.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"
}
}
8.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. |
8.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. |
8.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. |
🔹 9. 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}
9.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). |
9.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"
}
}
9.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. |
🔹 10. 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
10.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"
}
}
10.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. |
10.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"
}
}
10.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. |
🔹 11. 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
11.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"
}
11.2 Parâmetros Importantes
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
action |
string | ✅ | Ação a ser realizada na transação (CONFIRMATION, UNDOING). |
11.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. |