Integração GSPayments Pix

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.

2. 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:

Acesse o portal SC3 pelo link:

   https://portal.homolog.gsurfnet.com/gsurf/login

Nota: substitua "gsurf" pelo nome da sua empresa na URL.

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

3. Configuração das Rotas de API

Acesse Rotas de API.
Localize Gateway de Pagamentos Gsurf (Gspayments).
Selecione todos os endpoints disponíveis.
Clique em Salvar.
Após salvar, copie e armazene com segurança os seguintes dados:
Client Secret (visível apenas na tela de criação).
Client ID (visível posteriormente).

4. Criar Pagamentos por Pix

Este endpoint permite criar um pagamento por Pix.

É possível enviar um número de parcelas, no qual o Pix será dividido, gerando múltiplos QR Codes para o pagamento, conforme o vencimento base informado.

📌 Requisição

🛠 Método: POST
🔗 URL:

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

Método para criar um pagamento por Pix. É possível enviar um número de parcelas, no qual o Pix será dividido, gerando múltiplos QR Codes para o pagamento, conforme o vencimento base informado.

Autenticação: OAuth2 via GMAC

Authorization Code OAuth Flow
Client Credentials OAuth Flow

📌 Request

🏷 Body

📄 Formato: application/json

{
  "sale_data": {
    "amount": 1000,
    "merchant_correlation_id": "026b0627-83dc-42a0-bacc-a06f0da1227f",
    "order_id": "12345678",
    "installments": 1
  },
  "submerchant_id": "12312312387",
  "pix_data": {
    "due_date": "2021-12-12",
    "payer": {
      "document": "45028435049",
      "name": "Jhon Snow",
      "trade_name": "string",
      "address": "The wall avenue",
      "neighborhood": "The Wall",
      "city": "Garopaba",
      "state": "SC",
      "zip_code": "88495000"
    },
    "payer_information_requested": "Avalie sua compra",
    "allows_amount_change": false,
    "additional_data": [
      { "key": "Loja", "value": "Gsurf Store" }
    ],
    "days_between_due_dates": 15
  },
  "hook_data": {
    "url": "gsurfnet.com/payment/notification",
    "credentials_id": "d6f5a1d5-cadd-4d65-a136-c92614f45c40"
  },
  "split_data": [
    {
      "submerchant_id": "123123212387",
      "amount": 500,
      "fee_division": 5000
    }
  ],
  "dynamic_data": [
    {
      "key": "chave1",
      "value": "valor1"
    }
  ]
}

🔍 Parâmetros Importantes

🏷 Parâmetro	📌 Tipo	✅ Obrigatório	📝 Descrição
`amount`	integer	✅	Valor da venda sem separador decimal (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 (padrão: 1).
`submerchant_id`	string	✅	Identificador da loja para liquidação.
`due_date`	string	✅	Data de expiração do Pix (YYYY-MM-DD).
`payer_information_requested`	string	❌	Texto a ser apresentado ao pagador.
`allows_amount_change`	boolean	❌	Define se o pagador pode alterar o valor antes do pagamento (padrão: false).
`hook_data.url`	string	✅	URL de notificação por webhook.
`hook_data.credentials_id`	string	✅	ID da credencial cadastrada.
`split_data`	array	❌	Dados de divisão do pagamento entre submercantes.
`dynamic_data`	array	❌	Informações adicionais para relatórios.

✅ Responses

🎯 201 - Created

{
  "batch_id": "079ccb68-82e2-4cd8-a897-209fe749ad51",
  "amount": 1000,
  "installments": 2,
  "pix_list": [
    {
      "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",
        "confirm_time": null,
        "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.

5. Criar Pagamentos por Pix Instantâneo

Este endpoint permite criar um pagamento por Pix instantâneo com vencimento de até uma hora.

📌 Requisição

🛠 Método: POST
🔗 URL:

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

Autenticação: OAuth2 via GMAC

Authorization Code OAuth Flow
Client Credentials OAuth Flow

📌 Request

🏷 Body

📄 Formato: application/json

{
  "sale_data": {
    "amount": 1000,
    "merchant_correlation_id": "026b0627-83dc-42a0-bacc-a06f0da1227f",
    "order_id": "12345678"
  },
  "submerchant_id": "12312312387",
  "pix_data": {
    "expiration_time": 600,
    "payer": {
      "document": "45028435049",
      "name": "Jhon Snow",
      "trade_name": "string",
      "address": "The wall avenue",
      "neighborhood": "The Wall",
      "city": "Garopaba",
      "state": "SC",
      "zip_code": "88495000"
    },
    "payer_information_requested": "Avalie sua compra",
    "allows_amount_change": false,
    "additional_data": [
      { "key": "Loja", "value": "Gsurf Store" }
    ]
  },
  "hook_data": {
    "url": "gsurfnet.com/payment/notification",
    "credentials_id": "d6f5a1d5-cadd-4d65-a136-c92614f45c40"
  },
  "split_data": [
    {
      "submerchant_id": "123123212387",
      "amount": 500,
      "fee_division": 5000
    }
  ],
  "dynamic_data": [
    {
      "key": "chave1",
      "value": "valor1"
    }
  ]
}

🔍 Parâmetros Importantes

🏷 Parâmetro	📌 Tipo	✅ Obrigatório	📝 Descrição
`amount`	integer	✅	Valor da venda sem separador decimal (1000 = R$ 10,00).
`merchant_correlation_id`	string	✅	Identificador único para referência da loja.
`order_id`	string	✅	Número do pedido da loja.
`submerchant_id`	string	✅	Identificador da loja para liquidação.
`expiration_time`	integer	✅	Tempo de expiração do Pix em minutos (mínimo: 300, máximo: 3600).
`payer_information_requested`	string	❌	Texto a ser apresentado ao pagador.
`allows_amount_change`	boolean	❌	Define se o pagador pode alterar o valor antes do pagamento (padrão: false).
`hook_data.url`	string	✅	URL de notificação por webhook.
`hook_data.credentials_id`	string	✅	ID da credencial cadastrada.
`split_data`	array	❌	Dados de divisão do pagamento entre submercantes.
`dynamic_data`	array	❌	Informações adicionais para relatórios.

✅ Responses

🎯 201 - Created

{
  "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",
  "pix_data": {
    "provider_creation_time": "2021-12-12T11:05:00Z",
    "due_date": "2021-12-12T11:10:00",
    "due_date_type": "DIRECT",
    "qr_code_image": "https://api-dev.gsurfnet.com/gs-payment-v1/payments/pix/img/example.png",
    "qr_code_base64": "https://api-dev.gsurfnet.com/gs-payment-v1/payments/pix/img/example_base64.png"
  }
}

❌ 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.
422	Erro de validação de campos enviados na requisição.
500	Erro interno no servidor.

🔹 6. Consultar um Pix

Este endpoint permite consultar um determinado Pix através do GTI (identificador único da transação GSurf).

📌 Requisição

🛠 Método: GET
🔗 URL:

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

Autenticação: OAuth2 via GMAC

Authorization Code OAuth Flow
Client Credentials OAuth Flow

📌 Request

🏷 Path Parameters

🏷 Parâmetro	📌 Tipo	✅ Obrigatório	📝 Descrição
`gti`	string	✅	Identificador único da transação GSurf (36 caracteres).

📄 Exemplo: edf832cd-2360-4ebd-9f14-d290ddf9177c

✅ Responses

🎯 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"
  },
  "pix_data": {
    "provider_creation_time": "2021-12-12T11:05:00Z",
    "due_date": "2021-12-12",
    "due_date_type": "NORMAL",
    "qr_code_image": "https://api-dev.gsurfnet.com/gs-payment-v1/payments/pix/img/example.png",
    "qr_code_base64": "https://api-dev.gsurfnet.com/gs-payment-v1/payments/pix/img/example_base64.png"
  }
}

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