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

Integração Ecommerce 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.

#2. Configuração do Gspayments

Importante: Configuração no canal tem prioridade sobre as demais!

#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.

  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ções de API

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

#📌 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

#🔹 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