Plug API [versão beta] (0.1)

Download OpenAPI specification:Download

Introdução

Documentação das APIs de acesso aos serviços da Plug Pagamentos

A Plug é uma plataforma de serviços de pagamentos totalmente gerenciada através de API, através da qual você consegue acessar de maneira simples e rápida dezenas de provedores de pagamentos com uma única integração.

O motor de autorização da Plug garante segurança e resiliência aos seus pagamentos. Com nosso motor de autorização multi-provedor nós conseguimos aumentar a conversão das suas vendas usando diferentes regras de roteamento para retentar transações que seriam negadas em uma primeira tentativa ou perdidas por falha na comunicação com os provedores. Nosso motor inteligente garante ganho de receita com aumento do número de vendas e melhorias das taxas de conversão.

Com nosso serviço de proteção e armazenamento seguro de dados de cartão, você consegue tokenizar cartões e dados dos seus compradores de maneira segura para compras futuras. Nosso Vault de cartões está em conformidade com as melhores práticas de segurança do PCI. Ao tokenizar seus cartões os dados ficam armazenados em um ambiente seguro sendo gerenciado por você, sendo possível realizar transações com qualquer um dos provedores homologados a funcionar pela Plug. Você tokeniza uma vez com a Plug e pode usar o cartão onde quiser.

Com o serviço de tokenização da Plug você não precisa se preocupar em estar aderente às normas e políticas do PCI, a Plug se preocupa com isso para que você possa focar no seu serviço e nos seus clientes.

Através das APIs da Plug você têm acesso aos seguintes serviços:

  • Gestão de Cartões

    • Tokenização segura de cartão
    • Gestão de dados comprador
    • Listagem de cartões por comprador (Wallet)
  • Pagamentos Digitais

    • Cartão de crédito
    • Débito online 3DES (em desenvolvimento)
    • Boleto (em desenvolvimento)
    • PIX (em desenvolvimento)
  • Gestão de pagamentos

    • Listagem de pagamentos
    • Captura de pagamentos pré-autorizados
    • Estorno e cancelamento parcial de pagamentos
    • Consulta de taxa de aprovação e taxa de desconto por pagamento
  • Gestão de sub-contas

    • Listagem de sub-contas
    • Configuração de acesso aos provedores por sub-conta
  • Webhooks e API Keys

    • Gestão de webhooks para notificação assíncrona
    • Gestão de chaves de acesso a API

Get started

Um overview rápido de integração ponta a ponta com o serviço de pagamentos da Plug

Configure uma conta Plug

A configuração da sua conta de cliente na Plug é uma etapa fundamental para utilização dos serviços. Com a criação da sua conta você terá acesso às credenciais client-id e api-key necessárias para utilização dos serviços.

Durante o setup é feita também a configuração dos provedores de pagamento que estarão disponíveis para autorização na sua conta.

Estamos em beta e nossos serviços estão com acesso limitado neste momento. Entre em contato conosco em contato@plugpagamentos.com solicitando acesso.

Ambientes

Antes de ir para produção com seu serviço, teste sua integração com a Plug no nosso ambiente de sandbox. Neste ambiente o retorno das chamadas é mockado, sendo possível validar diferentes cenários.

Ambiente API
Teste sandbox-api.plugpagamentos.com
Produção api.plugpagamentos.com

Criar chave de acesso para o cliente

Você deve fazer uma chamada no Serviço de Autenticação a partir de sua chave secreta, solicitando a criação de uma chave pública com escopo limitado.

  curl --location --request POST 'https://api.plugpagamentos.com/v1/auth' \
    --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
    --header 'X-Api-Key: <YOUR_SECRET_KEY>' \
    --data '{"scope":["tokens"], "expires": 31104000"}' 

  {
    "clientId":"<YOUR_CLIENT_ID>",
    "publicKey":"<YOUR_PUBLIC_KEY>",
    "scope": ["tokens"],
    "expires": 31104000,
    "createdAt": "20200110 00:00:00"
  }

Criar token de cartão

Realize o processo de tokenização dos dados sensíveis do cartão diretamente no lado do cliente usando o Serviço de Tokens, e envie para seu backend o identificador do token gerado.

  curl --location --request POST 'https://api.plugpagamentos.com/v1/tokens' \
    --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
    --header 'X-Api-Key: <YOUR_PUBLIC_KEY>' \
    --data '{"cardHolderName": "JOSE DAS NEVES", "cardNumber": "4019598346009339", "cardCvv": "123", "cardExpirationMonth": "12", "cardExpirationYear": "26"}' 

  {
    "id": "82aba896-9e37-45b6-aa90-d510c9050596",
    "clientId": "cc0b1e41-2936-45c5-947f-93995ffcdc00",
    "createdAt": "2012-06-30 23:59:59 +0000"
  }

Salvar cartão para compra recorrente

Cria um cartão a partir do token gerado usando o Serviço de Cards, recebendo um cardId que pode ser armazenado no seu sistema para futuras compras.

  curl --location --request POST 'https://api.plugpagamentos.com/v1/cards' \
    --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
    --header 'X-Api-Key: <YOUR_PUBLIC_KEY>' \
    --data '{"tokenId": "82aba896-9e37-45b6-aa90-d510c9050596"}' 

  {
    "id": "148d5db0-f1c3-439f-902d-f1f268086e1d",
    "customerId": "82aba896-9e37-45b6-aa90-d510c9050596",
    "clientId": "cc0b1e41-2936-45c5-947f-93995ffcdc00",
    "expirationMonth": "12",
    "expirationYear": "26",
    "brand": "visa",
    "cvvChecked": true,
    "fingerprint": "cbd4a441-c63c-4dee-ac6b-bfa7fa1df818",
    "first6digits": "401959",
    "last4digits": "9339",
    "createdAt": "2012-06-30 23:59:59 +0000"
  }

Criar cobrança com cartão tokenizado

Realize uma cobrança a partir dos dados do cartão de crédito tokenizado usando o Serviço de Charges.

  curl --location --request POST 'https://api.plugpagamentos.com/v1/charges' \
    --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
    --header 'X-Api-Key: <YOUR_PUBLIC_KEY>' \
    --data '{"merchantId": "7f8870a2-71c9-4ef0-a531-82000e00b7e1","amount": 150,"statementDescriptor": "Pedido #231 loja joão",
      "paymentMethod": {"paymentType": "credit","installments": 1},
      "paymentSource": {"sourceType": "card","cardId": "148d5db0-f1c3-439f-902d-f1f268086e1d"}
    }'

  {
    "merchantId": "7f8870a2-71c9-4ef0-a531-82000e00b7e1",
    "amount": 150,
    "statementDescriptor": "Pedido #231 loja joão",
    "capture": false,
    "paymentMethod": {
      "paymentType": "credit",
      "installments": 1
    },
    "paymentSource": {
      "sourceType": "card",
      "cardId": "148d5db0-f1c3-439f-902d-f1f268086e1d"
    }
}

Testando sua integração

Os números de cartões a serem utilizados no teste podem ser gerados a partir de qualquer site gerador de cartões, devendo o comportamento seguir a seguinte regra:

Cartão Autorizado? Status
Final 4 ou 6 SIM Aprovado
Final 2 NÃO Não autorizado
Final 3 NÃO Cartão expirado
Final 5 NÃO Cartão bloqueado
Final 6 NÃO Timeout
Final 7 NÃO Cartão cancelado
Final 8 Aleatório SIM/NÃO Aprovado / Timeout

Transações no ambiente de sandbox envolvendo tokenização funcionam normalmente com base em cartões de teste. Cada cartão salvo na tokenização é tratado como um cartão normal, podendo ser usado no processo de simulação.

As informações de Cód.Segurança (CVV) e validade podem ser aleatórias, mantendo o formato - CVV (3 dígitos) Validade (MM/YY).

Se você conseguiu inserir os dados de cartão na sua aplicação cliente, criar um token, enviar os dados para o seu servidor e criar uma cobrança, então sua integração está finalizada.

Parabéns! Você completou sua integração básica com o serviço de cobrança. Descubra como manter o status das cobranças atualizadas no seu servidor através de notificações feitas pelo nosso serviço de webhooks.

Autenticação

Os serviços de API da Plug são protegidos através de chaves de acesso. Você pode gerenciar suas chaves de acesso através do seu dashboard.

É importante armazenar suas chaves de maneira privada e segura uma vez que elas possuem privilégios de alteração na sua conta. Não compartilhe suas chaves, não deixe elas fixadas no seu código e nem armazene elas no seu servidor de controle de versão. Recomendamos utilizar variáveis de ambiente secretas para deixar a chave disponível para sua aplicação.

A Autenticação para todos os chamadas da API é feita através de headers HTTP, sendo necessário informar seu identificador de cliente na Plug e a chave secreta de acesso.

  curl --location --request GET 'https://api.plugpagamentos.com/v1/' \
    --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
    --header 'X-Api-Key: <YOUR_SECRET_KEY>'

Client Token

É possível criar chaves públicas de acesso temporária a API com escopo e tempo de expiração limitados.

Recomendamos o uso deste tipo de chave quando você tiver que expor a chave em uma aplicação client side.

Neste caso, você deve fazer uma chamada no serviço de /auth a partir de sua chave secreta, solicitando a criação de uma chave pública com escopo limitado.

  curl --location --request POST 'https://api.plugpagamentos.com/v1/auth' \
    --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
    --header 'X-Api-Key: <YOUR_SECRET_KEY>' \
    --data '{"scope":"[tokens]", "expires": 31104000"}' 

  {
    "clientId":"<YOUR_CLIENT_ID>",
    "publicKey":"<YOUR_PUBLIC_KEY>",
    "scope":"[tokens]",
    "expires": 31104000,
    "createdAt": "20200110 00:00:00"
  }

A sua chave pública criada pode ser usada normalmente como se fosse a chave secreta da sua conta, porém com a restrição imposta pelo escopo e sendo invalidada após a expiração.

  curl --location --request GET 'https://api.plugpagamentos.com/v1/' \
    --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
    --header 'X-Api-Key: <YOUR_PUBLIC_KEY>'

Detalhe dos parâmetros da chamada de criação da chave pública:

scope
string
Enum: "tokens" "charges" "webhooks"

determina o escopo de endpoints que a chave terá acesso

expires
number
Default: 0

prazo de validade da chave em segundos a partir da criação, zero para não expirar

{
  • "scope": "tokens",
  • "expires": 0
}

Retorno da chamada de criação da chave pública:

scope
string
Enum: "tokens" "charges" "cards" "webhooks"

determina o escopo de endpoints que a chave terá acesso

expires
number

prazo de validade da chave em segundos a partir da criação, zero para não expirar

clientId
string

identificador do cliente na Plug

publicKey
string

chave pública criada

{
  • "scope": "tokens",
  • "expires": 0,
  • "clientId": "string",
  • "publicKey": "string"
}

Erro

A Plug disponibiliza uma lista de códigos de erro bem definida para facilitar a identificação dos diferentes tipos de problema que podem acontecer na integração.

Através desta especificação de erros é possível identificar os erros que acontecem quando uma requisição é processada com falha na autorizaçao, ou quando a é rejeitada por erro funcional. As categorias de erro HTTP possíveis são:

  • (2xx) não autorizado;
  • (4xx) problema no conteúdo da requisição;
  • (5xx) erro interno;
  • falha na comunicação ou timeout;

Definição do objeto de erro retornado pela API:

object
{
  • "error": {
    }
}

Código de retorno

Para transações não autorizadas que são recusadas pelo emissor a Plug fornece uma padronização dos código de retorno e uma recomendação de como você deve proceder com as principais falhas.

Tipos de erro possíveis para o declined_code

Código de retorno Descrição O que fazer
expired_card Cartão de crédito expirado/vencido Verifique os dados do cartão
invalid_cvv CVV inválido Verifique os dados do cartão
insufficient_funds Saldo insuficiente Saldo insuficiente
invalid_number Verifique os dados do cartão Número de cartão inválido ou não pertence ao emissor
fraud_suspect Suspeita de fraude Contate a central do seu cartão
fraud_confirmed Fraude confirmada Contate a central do seu cartão
generic Ocorreu um erro inesperado Contate a central do seu cartão

Idempotência

A API da Plug suporta chaves de idempotência para evitar duplicidade no processamento de requisições no caso de retentativas de uma mesma operação. Este recurso é útil quando uma requisição falha por erro na comunicação e você não recebeu uma resposta conclusiva. Se você receber um erro de conexão em uma determinada chamada você pode simplesmente retentar uma nova requisição usando a mesma chave de idempotência, dessa forma nossa API consegue garantir que a segunda chamada não será processada em duplicidade.

Para realizar chamadas com idempotência basta enviar um header adicional X-Idempotency-Key.

  curl --location --request POST 'https://api.plugpagamentos.com/v1/charges' \
    --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
    --header 'X-Api-Key: <YOUR_PUBLIC_KEY>' \
    --header 'X-Idempotency-Key: <IDEMPOTENCY_KEY>'

Nosso serviço salva a chave de Idempotency-Key e o Body enviado no seu request dado um request, independente de falha ou sucesso no processamento. Salvamos o resultado do processamento, e quando uma segunda requisição é feita com a mesma chave de idempotência nosso serviço retorna o mesmo conteúdo retornado na primeira chamada, incluindo os erros.

A chave de idempotência precisa ser única, gerada no lado do cliente, sendo necessário garantir do seu lado que as chaves não colidam. Sugerimos usar V4 UUID ou outro algoritmo similar que garanta hashes únicos.

O resultado só é armazenado no lado da Plug, caso tenha sido iniciado o processamento do primeiro request. Se existir alguma falha na validação dos campos, ou se outra chave estiver em processamento simultaneamente, nenhuma resposta de idempotência é dada.

Todas as chamadas de POST aceitam chave de idempotência.

Status da Transação

Os status possíveis para uma transação na Plug são:

Status Descrição
pending Transação criada porém não concluiu processamento
pre_authorized Transação pré autorizada com sucesso pendente a captura
authorized Transação autorizada e capturada com sucesso
failed Transação não autorizada, verifique o erro para identificar o motivo
canceled Transação estornada após aprovada porém não capturada
voided Transação estornada após aprovada e capturada
charged_back Transação foi contestada por fraude, não reconhecimento da compra ou devolução da mercadoria

Tokens

A Plug criou este serviço de tokenização para permitir que os dados sensíveis de cartão sejam processados de maneira segura.

Através da API de tokenização é possível garantir que os dados sensíveis do cartão (holder name, pan, cvv) não passem pelo seu backend e possam ser enviados para os servidores da Plug diretamente da sua aplicação cliente.

Um token representa dados sensíveis de cartão armazenados de maneira segura na Plug, seguindo as melhores práticas do PCI, sendo os dados enviados direto do seu frontend para os servidores da Plug.

É extremamente recomendado que você realize o processo de tokenização diretamente no lado do cliente, coletando os dados sensíveis de cartão na sua interface e enviando diretamente para a api de tokens, a partir de um client token criado para essa funcionalidade, enviando para seu backend o identificador do token gerado que não guarda dados sensíveis e pode ser trafegado normalmente pelos seus servidores.

Os Tokens são invalidados após o primeiro uso, não sendo possível armazenar o token gerado para uso futuro em compras recorrentes. Caso queira salvar os dados de um cartão para uso futuro, você deve realizar a criação de um token e na sequência solicitar a criação de um cartão a partir do token criado, dessa forma o cartão ficará armazenado em definitivo no nosso vault, servidor de armazenamento seguro de cartões, bastando enviar somente o card id gerado nas transações futuras.

Fluxo de criação de token

cardHolderName
required
string

Nome do portador do cartão

cardNumber
required
string

Número do cartão

cardCvv
required
string

Código de verificação

cardExpirationMonth
required
string

Mês de validade no formato MM

cardExpirationYear
required
string

Ano de validade no formato YY

{
  • "cardHolderName": "JOSE DAS NEVES",
  • "cardNumber": "4019598346009339",
  • "cardCvv": "123",
  • "cardExpirationMonth": "12",
  • "cardExpirationYear": "26"
}

Criar novo token de cartão

Request Body schema: application/json

Tokenize credit card

cardHolderName
required
string

Nome do portador do cartão

cardNumber
required
string

Número do cartão

cardCvv
required
string

Código de verificação

cardExpirationMonth
required
string

Mês de validade no formato MM

cardExpirationYear
required
string

Ano de validade no formato YY

Responses

Request samples

Content type
application/json
{
  • "cardHolderName": "JOSE DAS NEVES",
  • "cardNumber": "4019598346009339",
  • "cardCvv": "123",
  • "cardExpirationMonth": "12",
  • "cardExpirationYear": "26"
}

Response samples

Content type
application/json
{
  • "id": "82aba896-9e37-45b6-aa90-d510c9050596",
  • "clientId": "cc0b1e41-2936-45c5-947f-93995ffcdc00",
  • "createdAt": "2012-06-30 23:59:59 +0000"
}

Cards

Você pode criar cartões a partir de tokens gerados, sendo possível associar múltiplos cartões a um mesmo comprador, de maneira a possibilitar cobrança futura.

Uma vez criado um cartão é gerado um identificador único cardId que pode ser armazenado no seu sistema, já que não contém dados sensíveis de cartão, somente um identificador de um cartão salvo de maneira segura no vault da Plug.

A partir de um cardId gerado é possível realizar cobranças recorrentes, bastando enviar esse identificador no momento da criação do charge.

O código de segurança (cvv) do cartão, que foi enviado na tokenização, é validado através de um transação de valor zero junto ao emissor do cartão, dessa maneira a Plug consegue validar se os dados tokenizados do cartão são válidos sem que seja necessário realizar uma cobrança efetiva. Após a validação com sucesso dos dados do cartão, o mesmo fica disponível para compras futuras, caso contrário, o cartão ficará invalidado, devendo ser gerado um novo token e um novo cartão.

tokenId
required
string

Identificador do token gerado

customerId
string

Identificador do comprador portador do cartão (opcional)

{
  • "tokenId": "string",
  • "customerId": "string"
}

Bandeiras aceitas

As bandeiras aceitas para transações na plataforma da Plug são:

Bandeira Crédito Débito Voucher
visa SIM NÃO NÃO
master SIM NÃO NÃO
amex SIM NÃO NÃO
elo SIM NÃO NÃO
diners SIM NÃO NÃO
discover SIM NÃO NÃO
jcb SIM NÃO NÃO

Criar novo cartão a partir de token

Request Body schema: application/json

Create credit card

tokenId
required
string

Identificador do token gerado