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

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

  1. Acesse uma loja.

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

#3. Configuração das Rotas de API

  1. Acesse Rotas de API.

  2. Localize Gateway de Pagamentos Gsurf (Gspayments).

  3. Selecione todos os endpoints disponíveis.

  4. Clique em Salvar.

  5. Após salvar, copie e armazene com segurança os seguintes dados:

  6. Client Secret (visível apenas na tela de criação).

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

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

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

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

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

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