logo ← MANUAIS DE UTILIZAÇÃO / Integração GSPayments Link

Integração GSPayments Link

Integração GSPayments Link

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: Configuração no canal tem prioridade sobre as demais! \
Canal tem prioridade sobre Parceiro.

2.1 Configuração no Parceiro (CANAL GENÉRICO)

  1. Acesse Configurações > Gateway > Configurações do Parceiro.
  2. Acesse Credenciais para cadastrar uma credencial de provedor de cartão, Pix ou boleto.
  3. Selecione os provedores disponíveis e cadastre a credencial com o adquirente/banco utilizando as credenciais fornecidas por eles. (Faça isso para outros provedores como antifraude, por exemplo).
  4. Após esse cadastro, acesse Canais Genéricos, selecione PAYMENT_LINK e siga para Integrações e salve o provedor com a credencial criada.
  5. Em seguida, acesse Roteamento para configurar um roteamento default ou específico, caso haja mais de um.
  6. 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.

2.2 Configuração no Canal PAYMENT_LINK

  1. Acesse Acessar uma Loja > Config. Gateway > Canal > PAYMENT_LINK.
  2. Acesse Credenciais para cadastrar uma credencial de provedor de cartão, Pix ou boleto.
  3. Selecione os provedores disponíveis e cadastre a credencial com o adquirente/banco utilizando as credenciais fornecidas por eles. (Faça isso para outros provedores como antifraude, por exemplo).
  4. Após esse cadastro, acesse Integrações e salve o provedor com a credencial criada.
  5. Em seguida, acesse Roteamento para configurar um roteamento default ou específico, caso haja mais de um.
  6. 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.

Passos para criar um App Client:

  1. Acesse uma loja.
  2. Dentro da loja, vá em Menu > Controle de Acesso > Cadastrar App Client.

4. Configuração das Rotas de API

  1. Em Configurações do Módulo selecionar channel (obrigatório ter um canal)
  2. Acesse Rotas de API.
  3. Localize Gateway de Pagamentos Gsurf (Gspayments).
  4. Selecione todos os endpoints disponíveis.
  5. Clique em Salvar.
  6. Após salvar, copie e armazene com segurança os seguintes dados:
  7. Client Secret (visível apenas na tela de criação).
  8. Client ID (visível posteriormente).

📌 Requisição Token

🛠 Método: POST
🔗 URL: 

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

Autenticação: Basic Auth

Resultado: Obtenção do access_token

🔹 5. Criar Link de Pagamento

Este endpoint permite criar um link de pagamento.

📌 Requisição

🛠 Método: POST
🔗 URL: 

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

5.1 Estrutura da Requisição

Headers:

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

Body (Exemplo JSON):

{
  "payment_link_data": {
    "unique_payment": true,
    "allowed_payment_types": ["CARD", "SLIP", "PIX"],
    "card_payment_params": {},
    "recurrence_params": {},
    "description": "Pagamento da compra XYZ",
    "expiration": 86400,
    "split_data": [],
    "sale_data": {
      "amount": 1000,
      "merchant_correlation_id": "06f087a6-6e50-4b76-b71a-ee0ea9de961e",
      "order_id": "e44a1288ea1e4410bb8c",
      "submerchant_id": "05643319000159",
      "merchant_document": "00037736558"
    }
  }
}

5.2 Parâmetros Importantes

Parâmetro Tipo Obrigatório Descrição
unique_payment boolean ✅ Indica se o link é de pagamento único.
allowed_payment_types array ✅ Tipos de pagamento permitidos (CARD, SLIP, PIX).
description string ❌ Descrição do link de pagamento (máx. 99 caracteres).
expiration integer ❌ Expiração do link em segundos (máx. 172800, padrão: 86400).
amount integer ✅ Valor da venda sem separador decimal (ex: 1000 = R$ 10,00).
merchant_correlation_id string ❌ Identificador único para referência da loja (máx. 36 caracteres).
order_id string ❌ Número do pedido da loja (máx. 20 caracteres).
submerchant_id string ❌ Identificador da loja cadastrada no Gspayments (máx. 20 caracteres).
merchant_document string ❌ Documento da loja que o link será criado.

5.3 Respostas Possíveis

🟢 201 - Sucesso

{
  "url": "https://pagamento.gsurfnet.com/link/123456"
}

🔴 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. Pagamento do Link por Pix

Este endpoint permite realizar o pagamento de um link via Pix.

📌 Requisição

🛠 Método: POST
🔗 URL: 

https://api-hml.gsurfnet.com/gs-payment-ecommerce/v1/payments/link/{link_code}/pix

6.1 Estrutura da Requisição

Path Parameters:

Parâmetro Tipo Obrigatório Descrição
link_code string ✅ Código base64 contendo o identificador do link e do parceiro.

Headers:

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

Body (Exemplo JSON):

{
  "pix_data": {
    "payer": {
      "name": "Nome do Pagador",
      "document": "12345678900"
    }
  }
}

6.2 Parâmetros Importantes

Parâmetro Tipo Obrigatório Descrição
pix_data object ✅ Objeto contendo os dados do pagamento por Pix.
payer object ✅ Objeto contendo os dados do pagador.

6.3 Respostas Possíveis

🟢 201 - Sucesso

{
  "pix_data": {
    "emv": "00020101021126950014BR.GOV.BCB.PIX2573spi.hom.cloud.itau.com.br/documentos/f2bc596c-5ad6-4b8b-9a01-6d11cfcf3d015204000053039865409999900.005802BR5910Neymar CPF6009SAO PAULO626005228rxZbFrWS4uaAW0Rz889AQ50300017BR.GOV.BCB.BRCODE01051.0.06304CF12",
    "expiration": 300
  },
  "payment_data": {
    "gti": "ec8cb6ea-265d-463e-8f89-21c632989c2d",
    "status": "AUTHORIZED",
    "amount": 2000
  }
}

🔴 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. Pagamento do Link por Cartão

Este endpoint permite realizar o pagamento de um link via Cartão.

📌 Requisição

🛠 Método: POST
🔗 URL: 

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

7.1 Estrutura da Requisição

Path Parameters:

Parâmetro Tipo Obrigatório Descrição
link_code string ✅ Código base64 contendo o identificador do link e do parceiro.

Headers:

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

Body (Exemplo JSON):

{
  "transaction_data": {
    "payer": {
      "name": "Loja Gsurf",
      "document": "05643319000159"
    },
    "card": {
      "installments": 12
    },
    "session_id": "4e84ef0f-ae16-483c-999a-5a42be35219c"
  }
}

7.2 Parâmetros Importantes

Parâmetro Tipo Obrigatório Descrição
transaction_data object ✅ Objeto contendo os dados do pagamento por cartão.
payer object ✅ Objeto contendo os dados do pagador.
card.installments integer ✅ Quantidade de parcelas da transação.
session_id string ✅ Identificador da sessão (mín. 36 caracteres).

7.3 Respostas Possíveis

🟢 201 - Sucesso

{
  "transaction_data": {
    "masked_card": "544828******0007",
    "installments": 1,
    "authorization_code": "123",
    "authorization_time": "2024-07-12T12:00:00Z",
    "provider_usn": "123123123123123",
    "payer": {
      "name": "Loja Gsurf",
      "document": "05643319000159"
    }
  },
  "payment_data": {
    "gti": "8d561c7d-0dda-4185-bc86-5a78a070b2ca",
    "amount": "1000",
    "status": "AUTHORIZED"
  }
}

🔴 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 Link de Pagamento para Pagar

Este endpoint permite consultar um link para realizar o pagamento.

📌 Requisição

🛠 Método: GET
🔗 URL: 

https://api-hml.gsurfnet.com/gs-payment-ecommerce/v1/payments/link/{link_code}/to-pay

8.1 Estrutura da Requisição

Path Parameters:

Parâmetro Tipo Obrigatório Descrição
link_code string ✅ Código base64 contendo o identificador do link e do parceiro.

Headers:

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

8.2 Respostas Possíveis

🟢 200 - Sucesso

{
  "id": "9873217",
  "unique_payment": true,
  "allowed_payment_types": ["PIX"],
  "status": "ACTIVE",
  "creation_time": "2024-07-12T12:00:00Z",
  "update_time": "2024-07-12T12:00:00Z",
  "card_payment_params": {
    "max_installments": 6,
    "initial_installment_fees": 0,
    "installment_plans": [
      {
        "installment_value": 21,
        "installments": 10,
        "final_value": 210,
        "has_fee": true
      }
    ]
  },
  "recurrence_params": {
    "time_interval": 1,
    "time_unit_interval": "MOUNTH",
    "recurrence_times": 12
  },
  "description": "Pagamento do pedido X",
  "expiration": 86400,
  "payment_count": 1,
  "sale_data": {
    "amount": 1000,
    "merchant_correlation_id": "06f087a6-6e50-4b76-b71a-ee0ea9de961e",
    "order_id": "e44a1288ea1e4410bb8c",
    "submerchant_id": "05643319000159"
  },
  "hook_data": {
    "url": "gsurfnet.com/payment/notification",
    "credentials_id": "d6f5a1d5-cadd-4d65-a136-c92614f45c40"
  },
  "split_data": [],
  "session_id": "7939c4eb-012d-41a9-8dfc-161a98bc4d6c"
}

🔴 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. Cancelar Link de Pagamento

Este endpoint permite cancelar um link de pagamento.

📌 Requisição

🛠 Método: PUT
🔗 URL: 

https://api-hml.gsurfnet.com/gs-payment-ecommerce/v1/payments/link/{link_id}/cancel

9.1 Estrutura da Requisição

Path Parameters:

Parâmetro Tipo Obrigatório Descrição
link_id string ✅ Identificador do link (36 a 38 caracteres).

Headers:

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

9.2 Respostas Possíveis

🟢 200 - Sucesso

{
  "id": "9873217",
  "unique_payment": true,
  "allowed_payment_types": ["PIX"],
  "status": "ACTIVE",
  "creation_time": "2024-07-12T12:00:00Z",
  "update_time": "2024-07-12T12:00:00Z",
  "card_payment_params": {
    "max_installments": 6,
    "initial_installment_fees": 0,
    "installment_plans": [
      {
        "installment_value": 21,
        "installments": 10,
        "final_value": 210,
        "has_fee": true
      }
    ]
  },
  "recurrence_params": {
    "time_interval": 1,
    "time_unit_interval": "MOUNTH",
    "recurrence_times": 12
  },
  "description": "Pagamento do pedido X",
  "expiration": 300,
  "payment_count": 1,
  "sale_data": {
    "amount": 1000,
    "merchant_correlation_id": "06f087a6-6e50-4b76-b71a-ee0ea9de961e",
    "order_id": "e44a1288ea1e4410bb8c",
    "submerchant_id": "05643319000159"
  }
}

🔴 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. Criação de Link via Portal Lojista

gerar_link.jpg

link_gerado.jpg