Visão Geral

A OPA (Open Payments API) é a API pública de extensibilidade de pagamentos da Linx Commerce, permitindo que parceiros de pagamento integrem seus serviços financeiros diretamente à plataforma de e-commerce.

Por meio da OPA, um parceiro pode cadastrar seus providers, definir métodos de pagamento, configurar propriedades técnicas e disponibilizar esses meios no checkout da Linx Commerce, de forma segura e padronizada.

Esta documentação representa a versão pública inicial (V1) da OPA. Novas funcionalidades e evoluções poderão ser incorporadas em versões futuras.
Recomenda-se consultar este espaço regularmente para acessar as novidades e garantir o uso mais atualizado da integração.A partir do momento em que a API estiver disponível, o processo de obtenção de credenciais acontecerá mediante a criação do usuário e o fornecimento das informações necessárias pelo time Linx Commerce. Todas as instruções e dados de acesso serão enviados diretamente aos parceiros pela equipe responsável, garantindo o controle e a segurança do uso dos serviços.
Em caso de dúvida ou solicitação de credenciais, nos contate via: parcerias.linxcommerce@linx.com.br

Acesso

🔗Url para acesso:

https://api.linxcommerce.io/external-payment/scalar/

Collection para Postman:

Collection_external-payments-api-opa_linx_commerce.json

Status HTTP

📥 Status HTTP

200 OK – Sucesso.
201 Created – Recurso criado.
204 No Content – Operação sem retorno.
400 Bad Request – Dados inválidos.
401 Unauthorized – Token ausente ou inválido.
403 Forbidden – Acesso negado.
404 Not Found – Recurso inexistente.
500 Internal Server Error – Erro interno.

Autenticação

🔒 Autenticação

A autenticação é realizada via JWT (Bearer Token).

POST {{baseUrl}}/external-payments/v1.0/login

Exemplo de Request:

{
	"username": "partner_user",
	"password": "senha_segura"
}

Response 200 OK:

[
	{
		"token": "jwt_token",
		"expiration": "2025-01-01T00:00:00Z"
	}
]

Utilize o token retornado no header:

Authorization: Bearer {token}

Estrutura de Endpoints

📂 Estrutura de Endpoints

Conceitos Principais

Provider de Pagamento: Representa o parceiro de pagamento integrado à Linx Commerce.
Método de Pagamento: Forma de pagamento oferecida pelo provider (ex: cartão, pix, boleto).
Tipo de Pagamento: Classificação do método (CreditCard, Pix, Boleto, etc).
Configuration Property: Parâmetros de configuração necessários para o funcionamento do provider.
Payment Method Alias: Alias visual e funcional utilizado para mapear métodos de pagamento no checkout.

Fluxo de Integração – Visão Geral

A integração via OPA segue, de forma geral, o fluxo abaixo:

Autenticação na API
Criação do Provider de Pagamento
Configuração das Properties do Provider
Criação dos Métodos de Pagamento
Associação de Alias de Método
Disponibilização do meio de pagamento no checkout

Provedores de Pagamento:

O Provider de Pagamento representa o parceiro dentro da Linx Commerce. Todo o restante da integração depende da existência de um provider previamente cadastrado.

Listar os provedores/providers de pagamento.

GET /external-payments/v1.0/providers

Exemplo de Request:

GET {{baseUrl}}/external-payments/v1.0/providers?pageNumber=1&pageSize=10&tenantId=5

Response 200 OK:

{
	"data": [
	{
	"providerId": 10,
	"storeName": "loja_exemplo",
	"displayName": "Provedor de Pagamento Exemplo",
	"methods": [],
	"configurationProperties": []
	}
],
	"totalItems": 1,
	"pageSize": 10,
	"currentPage": 1
}

Parâmetros Query (opcionais):

pageNumber: inteiro (número da página)
pageSize: inteiro (tamanho da página)
tenantId: inteiro (filtra por tenant)

Response 200 OK:

{
   "data":[
      {
         "providerId":1,
         "storeName":"loja_exemplo",
         "displayName":"Provedor A",
         "methods":[
            
         ],
         "configurationProperties":[
            
         ]
      }
   ],
   "totalItems":1,
   "pageSize":10,
   "currentPage":1
}

Criar Provider

POST /external-payments/v1.0/providers

Exemplo de Request:

{
	"storeName": "loja_exemplo",
	"displayName": "Provedor de Pagamento Exemplo",
	"methods": [],
	"configurationProperties": []
}

Response 201:

{
	"providerId": 10,
	"storeName": "loja_exemplo",
	"displayName": "Provedor de Pagamento Exemplo",
	"methods": [],
	"configurationProperties": []
}

Buscar Provider por ID

GET /external-payments/v1.0/providers/{id}

Exemplo de Request:

GET {{baseUrl}}/external-payments/v1.0/providers/10

Response 200 OK:

{
	"providerId": 10,
	"storeName": "loja_exemplo",
	"displayName": "Provedor de Pagamento Exemplo",
	"methods": [],
	"configurationProperties": []
}

Atualizar Provider (por ID)

PUT /external-payments/v1.0/providers/{id}

Exemplo de Request:

{
	"storeName": "loja_exemplo",
	"displayName": "Provedor Atualizado",
	"methods": [],
	"configurationProperties": []
}

Response 200 OK:

{
	"providerId": 10,
	"storeName": "loja_exemplo",
	"displayName": "Provedor Atualizado",
	"methods": [],
	"configurationProperties": []
}

Remover Provider (por ID)

DELETE /external-payments/v1.0/providers/{id}

Exemplo de Request:

DELETE {{baseUrl}}/external-payments/v1.0/providers/10

Response 200 OK:

{
  "status": "success",
  "message": "Provedor removido com sucesso",
  "providerId": 10
}

Configuration Properties

As Configuration Properties são utilizadas para parametrizar o provider.

Criar Configuration Property

POST /external-payments/v1.0/configurationproperties

Exemplo de request:

{
	"providerId": 10,
	"displayName": "API Key",
	"hint": "Chave fornecida pelo parceiro",
	"isRequired": true,
	"inputDataType": 1,
	"isSecret": true,
}

Response – 200 OK

{
	"configurationPropertyId": 100,
	"providerId": 10,
	"displayName": "API Key",
	"hint": "Chave fornecida pelo provedor",
	"isRequired": true,
	"inputDataType": 1,
	"isSecret": true
}

Buscar Configuration Property por ID

GET /external-payments/v1.0/configurationproperties/{id}

Response – 200 OK

{
	"configurationPropertyId": 100,
	"providerId": 10,
	"displayName": "API Key",
	"isRequired": true,
	"inputDataType": 1,
	"isSecret": true
}

Atualizar Configuration Property

PUT /external-payments/v1.0/configurationproperties/{id}

Exemplo de Request:

{
	"displayName": "API Key Atualizada"
}

Remover Configuration Property

DELETE /external-payments/v1.0/configurationproperties/{id}

Buscar por ID

GET /external-payments/v1.0/configurationproperties/{id}

Atualizar

PUT /external-payments/v1.0/configurationproperties/{id}

Remover

DELETE /external-payments/v1.0/configurationproperties/{id}

Métodos de Pagamento

Os Métodos de Pagamento definem quais formas de pagamento o provider disponibilizará no checkout.

Criar Método

POST /external-payments/v1.0/methods

Exemplo de Request:

{
	"providerId": 10,
	"paymentTypeId": 2,
	"paymentMethodAliasId": 5
}

Response – 201 criado. Ok:

{
	"methodId": 50,
	"providerId": 10,
	"paymentTypeId": 2,
	"paymentMethodAliasId": 5
}

Buscar Método por ID

GET /external-payments/v1.0/paymenttypes

Exemplo de request:

GET {{baseUrl}}/external-payments/v1.0/paymenttypes

Response 200 OK:

[
  "CreditCard",
  "DebitCard",
  "Pix",
  "Boleto"
]

Atualizar Método

PUT /external-payments/v1.0/methods/{id}

Exemplo de request:

{
	"paymentMethodAliasId": 3
}

Remover Método

DELETE /external-payments/v1.0/methods/{id}

Buscar Método por ID

GET /external-payments/v1.0/method/{id}

Response 200 OK:

{
	"methodId": 50,
	"providerId": 10,
	"paymentTypeId": 2,
	"paymentMethodAliasId": 5
}

Atualizar Método

PUT /external-payments/v1.0/methods/{id}

Remover Método

DELETE /external-payments/v1.0/methods/{id}

Tipos de Pagamento

Listar Tipos de Pagamento

GET /external-payments/v1.0/paymenttypes

Response – 200 OK

[
  {
	"paymentTypeId": 1,
	"name": "CreditCard",
	"displayName": "Cartão de Crédito"
},
  {
	"paymentTypeId": 2,
	"name": "Pix",
	"displayName": "Pix"
  }
]

Payment Method Alias

O Payment Method Alias define a representação do método no checkout.

Listar Alias

GET /external-payments/v1.0/paymentmethodaliases

Response – 200 OK

[
 {
	"paymentMethodAliasId": 2,
	"name": "Cartão de Crédito"
 }
]

Criar Alias

POST /external-payments/v1.0/paymentmethodaliases

Exemplo de Request:

{
	"methodAlias": "Pix",
	"description": "Pagamento via Pix",
	"imageUrl": "https://cdn.exemplo.com/pix.png"
}

Response – 201 OK

{
	"methodAlias": "Pix",
	"description": "Pagamento via Pix",
	"imageUrl": "https://cdn.exemplo.com/pix.png"
}

Atualizar Alias

PUT /external-payments/v1.0/paymentmethodaliases/{paymentMethodAliasId}

Response – 200 OK

{
	"name": "Pix Atualizado"
}

Remover Alias

DELETE /external-payments/v1.0/paymentmethodaliases/{paymentMethodAliasId}

Criar

POST /external-payments/v1.0/paymentmethodaliases

Atualizar

PUT /external-payments/v1.0/paymentmethodaliases/{paymentMethodAliasId}

Remover

DELETE /external-payments/v1.0/paymentmethodaliases/{paymentMethodAliasId}

As seguintes funcionalidades não estão disponíveis nesta primeira versão (V1) da OPA:

Split de Pagamento
Recorrência de Pagamento
Pagamento com múltiplos cartões

Árvore de páginas

02 - Integração via Extensibilidade de Pagamento (OPA) - V1

🔗Url para acesso:

Collection para Postman:

📥 Status HTTP

🔒 Autenticação

Login:

📂 Estrutura de Endpoints

Conceitos Principais

Fluxo de Integração – Visão Geral

Provedores de Pagamento:

Listar os provedores/providers de pagamento.

Criar Provider

Buscar Provider por ID

Atualizar Provider (por ID)

Remover Provider (por ID)

Configuration Properties

Criar Configuration Property

Buscar Configuration Property por ID

Atualizar Configuration Property

Remover Configuration Property

Buscar por ID

Atualizar

Remover

Métodos de Pagamento

Criar Método

Buscar Método por ID

Atualizar Método

Remover Método

Buscar Método por ID

Atualizar Método

Remover Método

Tipos de Pagamento

Listar Tipos de Pagamento

Payment Method Alias

Listar Alias

Criar Alias

Atualizar Alias

Remover Alias

Criar

Atualizar

Remover