Referência da API

Erros

Código Descrição
400 Bad Request A requisição foi enviada com um formato inválido. Verifique se todos os campos necessários estão corretos.
401 Forbidden Acesso não autorizado. Confira a seção Autenticação
404 Not Found Recurso não encontrado no servidor
500 Internal Error Erro do servidor executando sua requisição. A equipe técnica do PagCoin é informada imediatamente para agir numa correção. Se desejar mais informações ou acompanhar o problema, favor entrar em contato conosco informando a hora e detalhes da requisição.

Autenticação

Requests

Sua API Key, disponível em Configurações de API, deve ser mantida em segredo. A API Key não deve em hipótese alguma ser disponibilizada em locais públicos, ou trafegada em canais não-HTTPS.

A autenticação à API do PagCoin é realizada através de dois itens de cabeçalho HTTP:

EnderecoPagCoin: URL destino da requisição

AssinaturaPagCoin: Código HMAC-SHA256 da concatenação do campo EnderecoPagCoin com o conteúdo da requisição, assinado com a API Key.

Este modo de autenticação garante sua identidade, assim como a não alteração dos dados.

Responses

As respostas enviadas pelo PagCoin também recebem a assinatura para que seu sistema possa verificar que os dados são autênticos. A verificação do código deve ser realizada informando a concatenação dos campos de cabeçalho AssinaturaPagCoin e EnderecoPagCoin recebidos na resposta, usando a API Key como chave para gerar a assinatura.

Implementações de referência para cálculo da assinatura:

<?php
	$assinatura = hash_hmac('sha256', $endereco . $conteudoJsonPost, $apiKey);
?>
public string GerarAssinaturaString(string enderecoPagCoin, string conteudo)
    var toSignBytes = Encoding.UTF8.GetBytes(enderecoPagCoin + conteudo);
    var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(ApiKey));
    var digest = hmac.ComputeHash(toSignBytes);
    var assinatura = BitConverter.ToString(digest).Replace("-", string.Empty).ToLower();
    return assinatura;
}
                
Em breve

Objetos

OrdemPagamento

O objeto OrdemPagamento representa os dados de uma ordem de pagamento, assim como seu status de pagamento.

Campo Tipo Tamanho Máximo Descrição
idPagCoin string 32 Identificador da operação efetuada no PagCoin.
valorEmMoedaOriginal decimal n/a Valor pago, em Reais
nomeProduto string 255 Nome do produto ou serviço associado à ordem de pagamento
idInterna string 36 Id usada internamente em seu site para identificar esta compra. Geralmente é usado o número do pedido ou o código do produto.
email string 255 Email do comprador associado à ordem de pagamento.
hora long n/a Hora em que a ordem de pagamento foi criada. Valores relativos a data/hora são representados por uma Unix Timestamp de 64 bits.
moedaOriginal string 3 Código da moeda usada para converter o valor em bitcoins (BRL = Reais, por exemplo)
statusPagamento string n/a Status do pagamento. Valores aceitáveis:
  • aguardando: A ordem de pagamento foi criada e está aguardando a confirmação do pagamento.
  • confirmado: O pagamento foi efetuado com sucesso. Produtos e/ou serviços podem ser liberados para o comprador.
  • recusado: O comprador tentou efetuar uma transferência mas a mesma foi recusada. Produtos e/ou serviços NÃO DEVEM ser liberados para o comprador.
  • timeout: O comprador não realizou a transferência. Produtos e/ou serviços NÃO DEVEM ser liberados para o comprador.
codigoStatusPagamento int n/a Código do status do pagamento. Valores aceitáveis:
  • 1 - aguardando
  • 3 - confirmado
  • 6 - recusado
  • 8 - timeout
horaResposta long n/a Hora de envio da mensagem de resposta. Valores relativos a data/hora são representados por uma Unix Timestamp de 64 bits.

Métodos

Por segurança, todos os métodos da API PagCoin são acessíveis apenas por HTTPS.

A URL base possui o seguinte formato: https://pagcoin.com/api/v1, onde “1” indica a versão da API.

Todos os parâmetros devem ser enviados como objetos JSON. As respostas podem ser objetos JSON ou outros formatos especificados na documentação de cada método.

Criar uma ordem de pagamento

URL: POST https://pagcoin.com/api/v1/CriarInvoice

Parâmetros: Objeto OrdemPagamento.

Campos:

apiKey obrigatório
valorEmMoedaOriginal obrigatório
nomeProduto obrigatório
idInterna opcional
email opcional
redirectURL opcional

Outros campos serão desconsiderados.

Retorno:

  • Padrão: string com a URL relativa para o Invoice no PagCoin.
    Exemplo: /Invoice/143c304e1e8df62f9ed6ac47ba569efe
  • Alternativos (Para implementação de checkout transparente): Realizar a chamada para a URL deste método incluindo a querystring ?modo=MODO, onde MODO é um dos seguintes valores:
    • light : string com a URL relativa para o Invoice preparado para checkout transparente em páginas com cor de fundo clara.
      Exemplo: /Invoice/143c304e1e8df62f9ed6ac47ba569efe?bg=light
    • dark : string com a URL relativa para o Invoice preparado para checkout transparente em páginas com cor de fundo escuro.
      Exemplo: /Invoice/143c304e1e8df62f9ed6ac47ba569efe?bg=dark
    • json : Objeto OrdemPagamento serializado em JSON

Observações:

  • O campo idInterna, caso preenchido, deve ser usado com um valor único para cada pedido, como o código interno do pedido em seu sistema. Evite usar informações que podem se repetir em diferentes pedidos, como o email de seu cliente, como valor deste campo. A existência de multiplas ordens de pagamento com o mesmo valor de idInterna impossibilitará o uso do método VerificarTransacao caso você não armazene em seu sistema a id informada pelo PagCoinao criar a ordem de pagamento.
  • Checkout transparente
    • Para o uso adequado dos modos light ou dark, efetue a requisição e atribua o valor retornado para o atributo src de um elemento iframe em sua página de checkout.
    • A largura mínima recomendada para a área do iframe para o invoice nos modos light e dark é de 380px.
    • A altura deve ser de 70% da largura definida. Por exemplo, um iframe com 600px de largura deve ter 420px de altura para exibir corretamente o a ordem de pagamento.
    • Use o modo de retorno alternativo json para implementar checkout transparente com o layout totalmente sob seu controle. Para gerar o QR-Code com as informações de pagamento, inclua <img src="https://pagcoin.com/qr/{IdPagCoin}" /> em sua página, onde {IdPagCoin} é a propriedade idPagCoin do objeto recebido. Não esqueça de implementar um mecanismo para deixar de exibir os dados de pagamento após 15 minutos da criação do invoice. O modo json não é recomendado, e deve ser usado apenas em casos específicos. Entre em contato conosco caso você realmente necessite este modo e precise de nosso suporte para o uso correto do mesmo.

Consultar status de pagamento de uma ordem existente

URL: POST https://pagcoin.com/api/v1/VerificarTransacao

Parâmetros: Objeto OrdemPagamento.

Campos:

apiKey obrigatório
idPagCoin opcional*
idInterna opcional*

Outros campos serão desconsiderados. * Um dos dois campos deve ser informado.

Retorno: Objeto OrdemPagamento

Observações:

  • A requisição deve ser verificar a assinatura PagCoin.
  • Se o campo idPagCoin for informado, o campo idInterna será ignorado.
  • Se apenas o campo idInterna for informado, mas seu sistema cadastrou multiplas ordens com o mesmo dado neste campo, esta chamada irá retornar um erro 400 Bad Request.
  • NUNCA use a resposta deste método sem verificar a assinatura PagCoin. Se a assinatura recebida não confere com a assinatura gerada por seu sistema, você deve descartar a resposta.

IPN

Você pode receber uma notificação sempre que uma de suas ordem de pagamento tiver o recebimento confirmado pela rede Bitcoin.

Você pode escrever um método que servirá como listener para as chamadas realizadas pela IPN PagCoin. Você deve informar a URL do listener que será chamado ao recebermos uma confirmação de pagamento nas Configurações de API.

Especificação do listener:

  • O listener deverá aceitar requisições HTTP POST.
  • A chamada enviada pelo PagCoin irá conter um objeto OrdemPagamento com os dados da ordem de pagamento, inclusive seu status.
  • O listener deve obrigatoriamente verificar a assinatura da requisição recebida, para verificar a autenticidade da mensagem. O procedimento é igual ao descrito em Autenticação, sendo o valor do campo EnderecoPagCoin a URL informada nas Configurações de API.

Para maiores informações e exemplo de código, leia a seção Recebendo notificação de pagamento efetuado da Visão Geral da documentação para desenvolvedores.