Pagamento Transparente

Visão Geral

A API do Pagamento Transparente ou Checkout Transparente oferece maior controle e flexibilidade sobre o processo de pagamento. Com essa integração o cliente fica no ambiente do seu e-commerce ou site durante todo o processo de compra, sem necessidade de cadastro ou páginas intermediárias de pagamento. Com ele é possível disponibilizar em seu site os meios de pagamento Cartão de Crédito, Débito Online e Boleto.

O Checkout Transparente está disponível para contas do tipo Vendedor e Empresarial. As seções seguintes indicarão como é possível integrar seu sistema de pagamentos ao Checkout Transparente do PagSeguro.

fluxograma

Exemplo de loja virtual com checkout transparente

Integração

Para fazer a integração do Checkout Transparente, você precisa seguir os seguintes passos:

Iniciando uma sessão de pagamento (Todos os meios de pagamento)

Para iniciar um Checkout Transparente é necessário ter um ID de sessão válido. Este serviço retorna o ID de sessão que será usado nas chamadas JavaScript. A chamada deve ser efetuada para a URL abaixo utilizando o método POST.

URL em Produção: POST https://ws.pagseguro.uol.com.br/v2/sessions

URL em Sandbox: POST https://ws.sandbox.pagseguro.uol.com.br/v2/sessions

Exemplo em Sandbox:

curl https://ws.sandbox.pagseguro.uol.com.br/v2/sessions/ -d\
 "email=suporte@lojamodelo.com.br\
&token=57BE455F4EC148E5A54D9BB91C5AC12C"

Retorno:

Veja na Referência da API: https://dev.pagseguro.uol.com.br/referencia-da-api/api-de-pagamentos-pagseguro#!/ws_pagseguro_uol_com_br/v2_sessions_xml

Atenção: Para mais detalhes de como iniciar uma sessão de pagamento, recomendamos a leitura da nossa documentação no link a seguir: /referencia-da-api/api-de-pagamentos-pagseguro#!/ws_pagseguro_uol_com_br/v2_sessions_xml

Integrações no browser

A API do Checkout Transparente possui funções JavaScript para algumas operações que devem ser executadas no browser do cliente, funções que serão descritas mais adiante. Para essas funções uma API JavaScript deve ser importada no final da página dos meios de pagamento:

Em Produção:

<script type="text/javascript" src=
"https://stc.pagseguro.uol.com.br/pagseguro/api/v2/checkout/pagseguro.directpayment.js">
</script>

Em Sandbox:

<script type="text/javascript" src=
"https://stc.sandbox.pagseguro.uol.com.br/pagseguro/api/v2/checkout/pagseguro.directpayment.js">
</script>

Esse JavaScript possui um objeto chamado PagSeguroDirectPayment, que é a interface de acesso aos métodos. Após importar o arquivo, deve ser executado o método setSessionId com o ID de sessão gerado anteriormente.

<script type="text/javascript">
 PagSeguroDirectPayment.setSessionId('ID_DA_SESSÃO');
</script>

Nas funções abaixo os eventos de sucesso e erro ocorrem em chamadas callback no JavaScript que são passadas via JSON.

Para isso basta passar três funções JavaScript com nome ‘success’, ‘error’ e ‘complete’ via JSON na chamada dos métodos. A função ‘complete’ será chamada independente do retorno e as funções ‘success’ e ‘error’ serão chamadas dependendo do retorno, ou seja, se o retorno não possuir erro a função chamada será a ‘success’ e se possuir erro a função chamada será a ‘error’.

Obter identificação do comprador (Todos os meios de pagamento)

Para realizar o Checkout Transparente é necessário enviar um identifilcador do comprador gerado pelo JavaScript. Para isso você deve utilizar o método getSenderHash. Este método não possui parâmetros e retorna um identificador. O identificador é obrigatório para todos os meios de pagamento.

Sintaxe:

PagSeguroDirectPayment.getSenderHash();

Atenção: Este método possui algumas dependências e, por isso, recomendamos que o getSenderHash não seja executado no onLoad da página. Você pode executa-lo, por exemplo quando o cliente clicar no botão de conclusão de pagamento.

Obter os meios de pagamento (Todos os meios de pagamento)

Nesse processo você pode obter todos os meios de pagamento disponíveis em sua conta para exibição no checkout. Para isso você deverá utilizar o método getPaymentMethods. Esse método recebe opcionalmente o valor da transação e retorna um JSON que contém os meios de pagamentos disponíveis no PagSeguro, compatíveis com o valor informado. Caso não seja informado o valor, será retornado todos os meios de pagamento. O JSON possui informações como o nome utilizado na API, nome de exibição, status (Disponibilidade) e também o caminho para as imagens do meio de pagamento.

Veja abaixo um JSON de exemplo (o JSON foi reduzida para melhor visualização):

Sintaxe:

PagSeguroDirectPayment.getPaymentMethods({
    amount: /*{valor da transação}*/
    success: /*{função de callback para chamadas bem sucedidas}*/,
    error: /*{função de callback para chamadas que falharam}*/,
    complete: /*{função de callback para todas chamadas}*/
});

Exemplo:

PagSeguroDirectPayment.getPaymentMethods({
    amount: 500.00
    success: function(response) {
        //meios de pagamento disponíveis
    },
    error: function(response) {
        //tratamento do erro
    },
    complete: function(response) {
        //tratamento comum para todas chamadas
    }
});

Retorno

{
    "error":false,
    "paymentMethods":{
        "BOLETO":{
            "name":"BOLETO",
            "options":{
                "BOLETO":{
                    "name":"BOLETO",
                    "displayName":"Boleto",
                    "status":"AVAILABLE",
                    "code":202,
                    "images":{
                        "SMALL":{
                            "size":"SMALL",
                            "path":"/public/img/payment-methods-flags/42x20/booklet.png"
                        },
                        "MEDIUM":{
                            "size":"MEDIUM",
                            "path":"/public/img/payment-methods-flags/68x30/booklet.png"
                        }
                    }
                }
            },
            "code":2
        },
        "ONLINE_DEBIT":{
            "name":"ONLINE_DEBIT",
            "options":{
                "BANCO_BRASIL":{
                    "name":"BANCO_BRASIL",
                    "displayName":"Banco do Brasil",
                    "status":"AVAILABLE",
                    "code":304,
                    "images":{
                        "SMALL":{
                            "size":"SMALL",
                            "path":"/public/img/payment-methods-flags/42x20/bb.png"
                        },
                        "MEDIUM":{
                            "size":"MEDIUM",
                            "path":"/public/img/payment-methods-flags/68x30/bb.png"
                        }
                    }
                },
            },
            "code":3
        },
        "CREDIT_CARD":{
            "name":"CREDIT_CARD",
            "options":{
                "MASTERCARD":{
                    "name":"MASTERCARD",
                    "displayName":"MasterCard",
                    "status":"AVAILABLE",
                    "code":102,
                    "images":{
                        "SMALL":{
                            "size":"SMALL",
                            "path":"/public/img/payment-methods-flags/42x20/mastercard.png"
                        },
                        "MEDIUM":{
                            "size":"MEDIUM",
                            "path":"/public/img/payment-methods-flags/68x30/mastercard.png"
                        }
                    }
                },
            },
        "code":1
        }
    }
}

As imagens são disponibilizadas em dois tamanhos: 42x20 e 68x30 e podem ser obtidas através dos caminhos apresentados no JSON, bastando incluir a URL https://stc.pagseguro.uol.com.br.

Veja abaixo dois exemplos de imagens e suas URLs:

Imagem Pequena

https://stc.pagseguro.uol.com.br/public/img/payment-methods-flags/42x20/visa.png Visa

Imagem Grande

https://stc.pagseguro.uol.com.br/public/img/payment-methods-flags/68x30/visa.png Visa

Obter a bandeira do cartão de crédito (Apenas para Cartão de Crédito)

Esse processo é necessário somente para o meio de pagamento cartão de crédito. O método getBrand é utilizado para verificar qual a bandeira do cartão que está sendo digitado. Esse método recebe por parâmetro o BIN do cartão (seis primeiros dígitos do cartão) e retorna dados como qual a bandeira, o tamanho do CVV, se possui data de expiração e qual algoritmo de validação. A chamada desse serviço não é obrigatória.

Sintaxe:

PagSeguroDirectPayment.getBrand({
    cardBin: /*{BIN do número do cartão}*/,
    success: /*{função de callback para chamadas bem sucedidas}*/,
    error: /*{função de callback para chamadas que falharam}*/,
    complete: /*{função de callback para todas chamadas}*/
});

Exemplo:

PagSeguroDirectPayment.getBrand({
    cardBin: $("input#cartao").val(),
    success: function(response) {
        //bandeira encontrada
    },
    error: function(response) {
        //tratamento do erro
    },
    complete: function(response) {
        //tratamento comum para todas chamadas
    }
});

Retorno:

{
    "brand":{
        "name":"visa",
        "bin":411111,
        "cvvSize":3,
        "expirable":true,
        "validationAlgorithm":"LUHN"
    }
}

Obter o token do cartão de crédito (Apenas para Cartão de Crédito)

Esse processo é necessário somente para o meio de pagamento cartão de crédito. O método createCardToken é utilizado para gerar o token que representará o cartão de crédito na chamada para a API do Checkout Transparente. Este método recebe os seguintes dados: número do cartão (obrigatório), CVV (opcional para alguns cartões), data de expiração (opcional para alguns cartões) e a bandeira (obrigatório).

Sintaxe:

PagSeguroDirectPayment.createCardToken({
    cardNumber: NUMERO_DO_CARTAO,
    brand: BANDEIRA,
    cvv: CODIGO_DE_SEGURANCA,
    expirationMonth: MES_DE_EXPIRACAO,
    expirationYear: ANO_DE_EXPIRACAO,
    success: FUNCAO_DE_CALLBACK_PARA_SUCESSO,
    error: FUNCAO_DE_CALLBACK_PARA_FALHA,
    complete: FUNCAO_DE_CALLBACK_PARA_TODAS_AS_CHAMADAS
});

Exemplo:

var param = {
    cardNumber: $("input#cartao").val(),
    cvv: $("input#cvv").val(),
    expirationMonth: $("input#validadeMes").val(),
    expirationYear: $("input#validadeAno").val(),
    success: function(response) {
        //token gerado, esse deve ser usado na chamada da API do Checkout Transparente
    },
    error: function(response) {
        //tratamento do erro
    },
    complete: function(response) {
        //tratamento comum para todas chamadas
    }
}

//parâmetro opcional para qualquer chamada
if($("input#bandeira").val() != '') {
    param.brand = $("input#bandeira").val();
}

PagSeguroDirectPayment.createCardToken(param);

Retorno:

{
    "card": {
        "token":"653fe9044cf149f9b7db562431cb130d"
    }
}

Verificar as opções de parcelamento (Apenas para Cartão de Crédito)

Esse processo é necessário apenas para o meio de pagamento cartão de crédito. Caso queira mostrar as opções de parcelamento para o comprador, você deverá utilizar o método getInstallments. Esse método recebe o valor a ser parcelado (obrigatório), a quantidade de parcelas sem juros e a bandeira que se deseja obter o parcelamento, retornando as configurações de cada parcela sendo: valor total do pagamento (que deve ser enviado junto na API do Checkout Transparente), valor e quantidade da parcela (que também devem ser informados na API do Checkout Transparente) e um indicador se aquela parcela tem juros ou não (caso o vendedor tenha configurado uma promoção no PagSeguro).

Se não for informado uma bandeira como parâmetro na chamada, o método retornará os dados para todas bandeiras aceitas pelo PagSeguro.

Sintaxe:

PagSeguroDirectPayment.getInstallments({
    amount: /*{valor do pagamento}*/,
    maxInstallmentNoInterest: /*{quantidade de parcelas sem juros}*/,
    brand: /*{bandeira do cartão}*/,
    success: /*{função de callback para chamadas bem sucedidas}*/,
    error: /*{função de callback para chamadas que falharam}*/,
    complete: /*{função de callback para todas chamadas}*/
});

Exemplo:

PagSeguroDirectPayment.getInstallments({
    amount: $("input#valorPagto").val(),
    brand: $("input#bandeira").val(),
    maxInstallmentNoInterest: 2,
    success: function(response) {
        //opções de parcelamento disponível
    },
    error: function(response) {
        //tratamento do erro
    },
    complete: function(response) {
        //tratamento comum para todas chamadas
    }
});

Retorno:

{
    "error":false,
    "installments":{
        "visa":[
            {
                "quantity":1,
                "totalAmount":16,
                "installmentAmount":16,
                "interestFree":true
            },{
            "quantity":2,
            "totalAmount":16.48,
            "installmentAmount":8.24,
            "interestFree":false
            }
        ]
    }
}

Efetuar o pagamento utilizando a API do Checkout Transparente (Todos os meios de pagamento)

Após obter os dados de pagamento você deve efetuar a chamada para o serviço do checkout transparente enviando os dados do comprador e do pagamento para realizar a cobrança. A chamada deve ser efetuada utilizando o método POST.

URL em Produção: POST https://ws.pagseguro.uol.com.br/v2/transactions

URL em Sandbox: POST https://ws.sandbox.pagseguro.uol.com.br/v2/transactions

O cabeçalho Content-Type deve ser informado conforme o conteúdo da requisição:

Caso, o conteúdo seja enviado na url da requisição, o valor informado deve ser: Content-Type: application/x-www-form-urlencoded; charset=ISO-8859-1

Caso, o conteúdo seja um texto xml, o valor informado deve ser: Content-Type: application/xml; charset=ISO-8859-1

Observação: caso sua aplicação ou loja não utilize o conjunto de caracteres ISO-8859-1, p.e.(UTF-8), é necessário substituir o parâmetro charset do exemplo acima.

Cada pagamento pode conter um ou mais itens. Cada item representa um produto ou qualquer outro bem que está sendo comprado. Os parâmetros associados a itens têm seu nome terminando em um número.

Por exemplo: os parâmetros itemId1, itemDescription1, itemAmount1 e itemQuantity1 referem-se ao primeiro item do pagamento, enquanto que os parâmetros itemId2, itemDescription2, itemAmount2 e itemQuantity2 referem-se ao segundo item do pagamento.

Atenção: Para mais detalhes de como efetuar o pagamento, recomendamos a leitura da nossa documentação no link a seguir: /referencia-da-api/api-de-pagamentos-pagseguro#!/ws_pagseguro_uol_com_br/v2_transactions_xml

Abaixo apresentamos um exemplo dos parâmetros da chamada via http para cada um dos meios de pagamento. Os exemplos em XML serão apresentados no final da documentação devido ao tamanho dos XMLs.

Exemplo de chamada para Boleto

Em Sandbox:

curl https://ws.sandbox.pagseguro.uol.com.br/v2/transactions/ -d\
 "email=suporte@lojamodelo.com.br\
&token=57BE455F4EC148E5A54D9BB91C5AC12C\
&paymentMode=default\
&paymentMethod=boleto\
&receiverEmail=suporte@lojamodelo.com.br\
&currency=BRL\
&extraAmount=1.00\
&itemId1=0001\
&itemDescription1=Produto PagSeguroI\
&itemAmount1=99999.99\
&itemQuantity1=1\
&notificationURL=https://sualoja.com.br/notifica.html\
&reference=REF1234\
&senderName=Jose Comprador\
&senderCPF=11475714734\
&senderAreaCode=99\
&senderPhone=99999999\
&senderEmail=comprador@uol.com.br\
&shippingAddressStreet=Av. PagSeguro\
&shippingAddressNumber=9999\
&shippingAddressComplement=99o andar\
&shippingAddressDistrict=Jardim Internet\
&shippingAddressPostalCode=99999999\
&shippingAddressCity=Cidade Exemplo\
&shippingAddressState=SP\
&shippingAddressCountry=ATA\
&shippingType=1\
&shippingCost=1.00"

Em Sandbox com Content-Type: application/xml:

Veja na Referência da API: https://dev.pagseguro.uol.com.br/referencia-da-api/api-de-pagamentos-pagseguro#!/ws_pagseguro_uol_com_br/v2_transactions_xml

Exemplo de chamada para Débito

Em Sandbox:

curl https://ws.sandbox.pagseguro.uol.com.br/v2/transactions/ -d\
 "email=suporte@lojamodelo.com.br\
&token=57BE455F4EC148E5A54D9BB91C5AC12C\
&paymentMode=default\
&paymentMethod=eft\
&bankName=itau\
&receiverEmail=suporte@lojamodelo.com.br\
&currency=BRL\
&extraAmount=1.00\
&itemId1=0001\
&itemDescription1=Produto PagSeguroI\
&itemAmount1=99999.99\
&itemQuantity1=1\
&notificationURL=https://sualoja.com.br/notifica.html\
&reference=REF1234\
&senderName=Jose Comprador\
&senderCPF=11475714734\
&senderAreaCode=99\
&senderPhone=99999999\
&senderEmail=comprador@uol.com.br\
&shippingAddressStreet=Av. PagSeguro\
&shippingAddressNumber=9999\
&shippingAddressComplement=99o andar\
&shippingAddressDistrict=Jardim Internet\
&shippingAddressPostalCode=99999999\
&shippingAddressCity=Cidade Exemplo\
&shippingAddressState=SP\
&shippingAddressCountry=ATA\
&shippingType=1\
&shippingCost=1.00"

Em Sandbox com Content-Type: application/xml:

Veja na Referência da API: https://dev.pagseguro.uol.com.br/referencia-da-api/api-de-pagamentos-pagseguro#!/ws_pagseguro_uol_com_br/v2_transactions_xml

Exemplo de chamada para Cartão de Crédito

Em Sandbox:

curl https://ws.sandbox.pagseguro.uol.com.br/v2/transactions/ -d\
 "email=suporte@lojamodelo.com.br\
&token=57BE455F4EC148E5A54D9BB91C5AC12C\
&paymentMode=default\
&paymentMethod=creditCard\
&receiverEmail=suporte@lojamodelo.com.br\
&currency=BRL\
&extraAmount=1.00\
&itemId1=0001\
&itemDescription1=Produto PagSeguroI\
&itemAmount1=99999.99\
&itemQuantity1=1\
&itemId1=0002\
&itemDescription1=Produto PagSeguroII\
&itemAmount1=99999.98\
&itemQuantity1=2\
&notificationURL=https://sualoja.com.br/notifica.html\
&reference=REF1234\
&senderName=Jose Comprador\
&senderCPF=11475714734\
&senderAreaCode=99\
&senderPhone=99999999\
&senderEmail=comprador@uol.com.br\
&senderHash=52578d5d3336ec7a43ff1dae4794d0c5625feddcc8fbc0e80bcb0cb46c9947d4\
&shippingAddressStreet=Av. PagSeguro\
&shippingAddressNumber=9999\
&shippingAddressComplement=99o andar\
&shippingAddressDistrict=Jardim Internet\
&shippingAddressPostalCode=99999999\
&shippingAddressCity=Cidade Exemplo\
&shippingAddressState=SP\
&shippingAddressCountry=ATA\
&shippingType=1\
&shippingCost=21.50\
&creditCardToken=1e358d39e26448dc8a28d0f1815f08c5\
&installmentQuantity=1\
&installmentValue=300021.45\
&noInterestInstallmentQuantity=2\
&creditCardHolderName=Jose Comprador\
&creditCardHolderCPF=11475714734\
&creditCardHolderBirthDate=01/01/1900\
&creditCardHolderAreaCode=99\
&creditCardHolderPhone=99999999\
&billingAddressStreet=Av. PagSeguro\
&billingAddressNumber=9999\
&billingAddressComplement=99o andar\
&billingAddressDistrict=Jardim Internet\
&billingAddressPostalCode=99999999\
&billingAddressCity=Cidade Exemplo\
&billingAddressState=SP\
&billingAddressCountry=ATA"

Em Sandbox com Content-Type: application/xml:

Veja na Referência da API: https://dev.pagseguro.uol.com.br/referencia-da-api/api-de-pagamentos-pagseguro#!/ws_pagseguro_uol_com_br/v2_transactions_xml

Retorno da API do Checkout Transparente

Após a chamada para a API do Checkout Transparente, é retornado um XML com todos os dados da transação conforme o exemplo no link abaixo:

Veja na Referência da API: https://dev.pagseguro.uol.com.br/referencia-da-api/api-de-pagamentos-pagseguro#!/ws_pagseguro_uol_com_br/v2_transactions_xml

Caso ocorra algum erro na chamada por erro nos parâmetros informados um XML de erro será retornado. Ele indicará os erros identificados na chamada. Veja o exemplo no link abaixo:

Veja na Referência da API: https://dev.pagseguro.uol.com.br/referencia-da-api/api-de-pagamentos-pagseguro#!/ws_pagseguro_uol_com_br/v2_transactions_xml

No exemplo acima a chamada foi efetuada sem o parâmetro shipping address city, que é obrigatório.

Para os meios Boleto e Débito, o XML possui o item paymentLink que retorna um link acesso, respectivamente, a imagem do boleto e para a página de pagamento do banco selecionado.

Atenção: A página do banco não deve ser aberta em um IFrame.