Documentação para desenvolvedores

Usando o PagCoin, é simples incluir a opção de pagamentos com bitcoin em seu site. Oferecemos uma api simples para criar ordens de pagamento e receber notificações de pagamentos confirmados, exigindo poucos conhecimentos de programação. Entenda como funciona o processo de compra com bitcoins usando o PagCoin:

Visão Geral

1. O comprador escolhe os produtos ou serviços que deseja comprar em sua loja, e decide pagar com bitcoins.

2. O PagCoin recebe de seu sistema os dados da compra e retorna o endereço da ordem de pagamento.

3. Sua loja redireciona o comprador para o endereço da ordem de pagamento gerada pelo PagCoin.

4. No site do PagCoin, o comprador efetua o pagamento. Quando a transferência for confirmada, seu site será notificado.

Solicitando a criação de uma ordem de pagamento

Para criar uma ordem de pagamento, deve ser enviada ao PagCoin uma requisiçao HTTP usando método POST, com o conteúdo em formato Json. A URL para criação de ordens de pagamento é a seguinte:

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

O conteúdo desta requisição deve ser um objeto com os valores necessários para a criação da ordem de pagamento, enviado em formato Json. O objeto esperado deve possuir o formato do seguinte exemplo:

{
	"apiKey":"ffff1111ffff00eedd21111112a2b4ff",
	"valorEmMoedaOriginal":123.45,
	"nomeProduto":"Nome do produto ou serviço vendido",
	"idInterna":"109856482",
	"email":"emailDoComprador@dominio.com",
	"redirectURL":"http://www.sitedesualoja.com/URL/Para/Redirecionar/?usuario=aposACompra"
}

Todos os campos devem constar no objeto enviado. Caso o campo seja opcional, deve ser enviado com valor vazio. Segue a descrição dos campos:

  • apiKey (obrigatório, string, 32 caracteres): Chave de API informada em seu painel. Lembre-se que esta chave deve ser mantida em segredo.
  • valorEmMoedaOriginal (obrigatório, decimal, casa decimal separada por "."): Valor do produto em Reais
  • nomeProduto (obrigatório, string, máx 255 caracteres): Nome do produto ou serviço sendo vendido. Em caso de múltiplos produtos, é aceitável nomes como "Compra realizada em NomeDoSeuSite"
  • idInterna (opcional, string, máx 36 caracteres): Id usada internamente em seu site para esta compra. Geralmente é usado o número do pedido ou o código do produto.
  • email (opcional, string, máx 255 caracteres): Email associado ao comprador
  • redirectURL (opcional, string, máx 255 caracteres): URL para onde o comprador será redirecionado após o pagamento ser recebido.

Caso os dados sejam válidos, o PagCoin irá responder a requisição com a URL para a qual você deve redirecionar o comprador para efetuar o pagamento (outra opção é carregar a URL em um iframe). Os últimos 32 caracteres desta resposta, em negrito no exemplo abaixo, são o identificador da ordem de pagamento no PagCoin. Segue um exemplo desta resposta:

https://pagcoin.com/Invoice/21ffff112b4ff00eed11ff1112adf11f

Implementações de Referência:

<?php
	$pagCoinUrl = "https://pagcoin.com/api/v1/CriarInvoice/";
	
	$request = array(
		"apiKey" => "ffff1111ffff00eedd21111112a2b4ff", 
		"valorEmMoedaOriginal" => 123.45, 
		"nomeProduto" => "Nome do produto ou serviço vendido", 
		"idInterna" => "109856482", 
		"email" => "emailDoComprador@dominio.com", 
		"redirectURL" => "http://www.sitedesualoja.com/URL/Para/Redirecionar/?usuario=aposACompra"
	);
	
	$jsonRequest = json_encode($request);
	
	$ch = curl_init($pagCoinUrl);
	
	curl_setopt( $ch, CURLOPT_POST, 1);
	curl_setopt( $ch, CURLOPT_POSTFIELDS, $jsonRequest);
	curl_setopt( $ch, CURLOPT_FOLLOWLOCATION, 1);
	curl_setopt( $ch, CURLOPT_HEADER, 0);
	curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1);
	
	$redirectUrl = curl_exec($ch);
	
	header('Location: '.$redirectUrl);
?>
public string RequisicaoPagCoin()
{
        var pagCoinUrl = "https://pagcoin.com/api/v1/CriarInvoice/";

	  var parameters = new
            {
                apiKey = "ffff1111ffff00eedd21111112a2b4ff",
                valorEmMoedaOriginal = 123.45,
                nomeProduto = "Nome do produto ou serviço vendido",
                idInterna = "109856482",
                email = "emailDoComprador@dominio.com",
                redirectURL = "http://www.sitedesualoja.com/URL/Para/Redirecionar/?usuario=aposACompra"
            };

            string jsonRequest = System.Web.Helpers.Json.Encode(parameters);

            HttpWebRequest objWebRequest = (HttpWebRequest)WebRequest.Create(pagCoinUrl);
            objWebRequest.Method = WebRequestMethods.Http.Post;
            objWebRequest.ContentType = "text/json";

            using (System.IO.StreamWriter sw = new System.IO.StreamWriter(objWebRequest.GetRequestStream()))
            {
                sw.Write(jsonRequest);
            }

            HttpWebResponse objHttpWebResponse = (HttpWebResponse)objWebRequest.GetResponse();
            using (System.IO.StreamReader sr = new System.IO.StreamReader(objHttpWebResponse.GetResponseStream()))
            {
                return sr.ReadToEnd();
            }
}
                
Em breve

Recebendo notificação de pagamento efetuado

Na seção de configuração de sua conta, você pode cadastrar uma URL de callback. Esta URL será chamada pelo PagCoin sempre que um pagamento efetuado for confirmado.

O PagCoin irá efetuar a requisição HTTP à URL informada usando método POST. O conteúdo da requisição enviada pelo PagCoin será um objeto formatado Json contendo os seguintes campos:

  • idPagCoin: Identificador da operação efetuada no PagCoin.
  • valorEmMoedaOriginal: Valor pago, em Reais
  • nomeProduto: Nome do produto ou serviço associado à ordem de pagamento
  • idInterna: Id usada internamente em seu site para identificar esta compra. Geralmente é usado o número do pedido ou o código do produto.
  • email: Email do comprador associado à ordem de pagamento
  • hora: Hora em que a ordem de pagamento foi criada
  • moedaOriginal: Código da moeda usada para converter o valor em bitcoins (BRL = Reais, por exemplo)
  • statusPagamento: Status do pagamento. Valores aceitáveis:
    • 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.
  • horaResposta: Hora de envio da mensagem de resposta

Esta requisição é enviada com dois campos de cabeçalhos para que seu sistema possa verificar a autenticidade da mensagem. Os campos são os seguintes:

EnderecoPagCoin: http://www.sualoja.com/URL/informada.para=Callback
AssinaturaPagCoin: 6adcc016448d707c1d16827459aee1f5c37621a9a747d3c5feb9f80877e3d495	

O campo AssinaturaPagCoin é calculado através do algoritmo HMAC-SHA256. A chave usada para gerar a assinatura é sua ApiKey, e o conteúdo é a concatenação do campo EnderecoPagCoin com o conteúdo da requisição. Desta forma, se você receber a seguinte requisição:

EnderecoPagCoin: http://www.sualoja.com/URL/informada.para=Callback
AssinaturaPagCoin: 6adcc016448d707c1d16827459aee1f5c37621a9a747d3c5feb9f80877e3d495

{
	"idPagCoin":"ffff1111ffff00eedd21111112a2b4ff",
	"valorEmMoedaOriginal":123.45,
	"nomeProduto":"Nome do produto ou serviço vendido",
	"idInterna":"109856482",
	"email":"emailDoComprador@dominio.com",
	"hora":499137600,
	"moedaOriginal":"BRL"
	"statusPagamento":"confirmado"
	"horaResposta":1445401740
}

Você deverá concatenar o campo de cabeçalho EndereçoPagCoin com o objeto Json e aplicar HMAC-SHA256 no resultado desta concatenação, usando sua ApiKey como chave. Caso o resultado da aplicação deste algoritmo não seja igual ao valor informado no campo AssinaturaPagCoin, você não deve aceitar a requisição.


 

Implementações de Referência:

<?php
	$headers = apache_request_headers();
	
	if(!isset($headers["EnderecoPagCoin"]) || !isset($headers["AssinaturaPagCoin"])){
		die("Cabeçalhos não encontrados.");
	}
	
	$postdata = file_get_contents("php://input");
	$fields = json_decode($postdata);
	
	// função para calculo do hmac   concatenação de cabeçalho + conteudo   sua ApiKey       
	$signature = hash_hmac('sha256', $headers["EnderecoPagCoin"].$postdata, "ffff1111ffff00eedd21111112a2b4ff")
	
	if($signature != $headers["AssinaturaPagCoin"]){
		die("Assinatura não confere");
	}
	
	/*
		Sua implementação própria para identificar o pagamento e liberar os produtos. 
		Para acessar os campos do objeto informado, use a seguinte sintaxe como exemplo:
		$fields["nomeProduto"];
		$fields["idInterna"];
		$fields["statusPagamento"];
	*/
?>
public void NotificacaoPagCoin()
{
        var enderecoPagCoin = HttpContext.Response.Headers["EnderecoPagCoin"];
        var assinaturaPagCoin = HttpContext.Response.Headers["AssinaturaPagCoin"];

        if (string.IsNullOrEmpty(enderecoPagCoin) || string.IsNullOrEmpty(assinaturaPagCoin))
        {
            throw new Exception("Cabeçalhos não encontrados.");
        }

        string postdata = String.Empty;
        HttpContext.Request.InputStream.Position = 0;
        using (var inputStream = new System.IO.StreamReader(HttpContext.Request.InputStream))
        {
            postdata = inputStream.ReadToEnd();
        }

        dynamic fields = System.Web.Helpers.Json.Decode(postdata);

        // função para calculo do hmac:  concatenação de cabeçalho + conteudo /  sua ApiKey       
        var signature = Hash_HMAC(enderecoPagCoin + postdata, "ffff1111ffff00eedd21111112a2b4ff");

        if (signature != assinaturaPagCoin)
        {
            throw new Exception("Assinatura não confere");
        }

        /*
            Sua implementação própria para identificar o pagamento e liberar os produtos. 
            Para acessar os campos do objeto informado, use a seguinte sintaxe como exemplo:
            fields.nomeProduto;
            fields.idInterna;
            fields.statusPagamento;
		
        */
}

private string Hash_HMAC(string message, string secret)
{
	var encoding = new System.Text.ASCIIEncoding();
	byte[] keyByte = encoding.GetBytes(secret);
	byte[] messageBytes = encoding.GetBytes(message);
	using (var hmacsha256 = new System.Security.Cryptography.HMACSHA256(keyByte))
	{
		byte[] hashmessage = hmacsha256.ComputeHash(messageBytes);
		return BitConverter.ToString(hashmessage).ToLower().Replace("-", "");
	}
}