Modelo de Aplicações

Visão Geral

O modelo de aplicações do PagSeguro permite que sua aplicação crie checkouts, receba notificações de pagamento entre outras funções em nome do cliente sem a necessidade de configurar tokens, URL de retorno e outras informações na conta PagSeguro que você estiver utilizando.

Assim, o seu cliente pode se cadastrar em sua plataforma, autorizá-la e começar a vender sem a necessidade de inserir informações ou entrar na conta PagSeguro para efetuar configurações.

O modelo de aplicações do PagSeguro está disponível para contas do tipo Vendedor e Empresarial.

Etapas da Integração

1. Aplicações

Crie e gerencie uma aplicação.

2. Autorizações

Obtenha a permissão do seu cliente para criar checkouts, efetuar consultas entre outras ações.

3. Notificações

Receba notificações informando o status da autorização e das cobranças.

4. Consulta

Faça consultas ao PagSeguro para acompanhar a qualquer momento as suas transações.

É importante seguir os passos acima para o correto entendimento da ferramenta.

Aplicações

Para utilizar o modelo de aplicações do PagSeguro é necessário que você crie uma aplicação. Esta aplicação será responsável por centralizar as autorizações concedidas pelos seus clientes.

Atenção: Como o modelo de aplicações é uma ferramenta liberada apenas para alguns parceiros, o acesso a esta é feito através de algumas URLs diretas que você verá no decorrer da documentação.

Para criar uma nova aplicação, logue em sua conta do PagSeguro, após isso, acesse o link https://pagseguro.uol.com.br/aplicacao/listagem.jhtml e clique em “criar suas aplicações” conforme apresentado na Imagem 1:

Imagem 1

Você também pode acessar diretamente a página de cadastro através do link https://pagseguro.uol.com.br/aplicacao/cadastro.jhtml.

Na página de criação, você deve preencher os dados solicitados que são:

PARÂMETRO DESCRIÇÃO
Nome da aplicação Esse nome irá aparecer para você e para os outros clientes que usarão sua aplicação.
ID da Aplicação O ID da aplicação será o código que identifica esta aplicação no PagSeguro.

Obs.: O PagSeguro irá sugerir um ID a partir do nome que você escolheu no campo anterior.
Descrição da aplicação Escreva a descrição que irá aparecer para os usuários em sua aplicação. Procure ser objetivo e explicar resumidamente a sua função.
URL da aplicação Digite a url em que a sua aplicação estará disponível para acesso na internet
Logomarca Informe o endereço (URL) da sua logomarca ou faça upload do arquivo de imagem.

Obs.: Máximo de 500kbytes, Formatos aceitos: JPG, GIF, PNG, BMP. Sua logomarca poderá ser reduzida para as proporções máximas de 150 x 55 pixels.
URL de notificação Digite a url em que você receberá as notificações feitas em sua aplicação.
URL de redirecionamento Digite a url que o usuário irá ser levado após a finalização do pagamento.

Também é possível habilitar o redirecionamento com o código de transação. Com a opção habilitada, o PagSeguro irá enviar como parâmetro, via GET, o código da autorização que foi gerado. Sua aplicação poderá utilizar esse código para exibir informações da autorização ao cliente.

Caso habilite esta opção, você poderá escolher o nome do parâmetro GET que será utilizado conforme a Imagem 2.

Imagem 2

Após criar a sua aplicação será apresentado um resumo com os dados da aplicação, inclusive a chave da sua aplicação (ou appKey) como apresentado na Imagem 3.

Imagem 3

Atenção: Guarde bem a sua chave de aplicação, pois ela é essencial para que você possa efetuar as iterações com as APIs de Pagamento e Assinatura.

Após guardar bem a sua chave da aplicação, você pode clicar em “Ir para Minhas Aplicações” para visualizar a listagem de aplicações. A listagem é apresentada conforme a Imagem 4.

Imagem 4

Você pode editar as informações da sua aplicação, inclusive gerar uma nova appKey a qualquer momento clicando em Editar aplicação > Gerar nova chave. Com exceção do ID da aplicação, todos os campos da aplicação são editáveis.

Também é possível excluir uma aplicação. Ao excluir uma aplicação, todas as permissões concedidas a ela são perdidas, ou seja:

  • Ela não poderá mais criar checkouts
  • Ela não poderá mais receber pagamentos a partir de checkouts criados antes da remoção
  • Ela poderá continuar recebendo notificações
  • Ela não será exibida mais na listagem de aplicações do integrador
  • Ela não será mais exibida na listagem de autorizações concedidas

Autorização

Após criar uma aplicação você poderá pedir a autorização do seu cliente para criar checkout, criar assinaturas, efetuar consultas entre outras ações.

O fluxo de autorização é exemplificado na Imagem 5:

Imagem 5

Informando os dados da requisição

A requisição à API de Autorizações é feita informando os dados de autorização via XML em conjunto com os parâmetros de autenticação da sua aplicação (appId e appKey) utilizando o método POST.

URL da API de Autorizações do PagSeguro: POST https://ws.pagseguro.uol.com.br/v2/authorizations/request?appId={appId}&appKey={appKey}

Parâmetros de autenticação

PARÂMETRO DESCRIÇÃO
appId ID da Aplicação.
Presença: Obrigatória.
Tipo: Texto.
Formato: Uma sequência de até 60 caracteres.
appKey Especifica o token correspondente à aplicação PagSeguro que está realizando a requisição.
Presença: Obrigatória.
Tipo: Texto.
Formato: Uma sequência de 32 caracteres.

Veja abaixo os cabeçalhos HTTP necessários para fazer uma requisição à API de autorização do PagSeguro informando os dados no formato XML.

O cabeçalho Content-Type deve ser informado como no exemplo abaixo:

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.

Veja no link abaixo exemplo de XML estruturado para representar os dados de uma requisição:

Veja na Referência da API:

Dados do cliente e sugestão para cadastro

Ao criar uma autorização você também pode encaminhar os dados do cliente. Assim, caso o e-mail do vendedor enviado via API já esteja cadastrado na base, será sugerido o login com este e-mail. Caso ele não tenha conta, os dados serão utilizados como sugestão para o cadastro e assim facilitando o cadastro do cliente.

Atenção: quantos mais dados corretos forem informados, maior a chance de conversão do vendedor não cadastrado nesse fluxo.

É possível encaminhar os dados tanto de um cliente Vendedor (utilizando CPF) quanto para um cliente Empresarial (Utilizando o CNPJ).

Veja no link abaixo o exemplo de XML estruturado para representar os dados de uma autorização com a sugestão de uma conta Vendedor:

Veja na Referência da API:

Veja no link abaixo o exemplo de XML estruturado para representar os dados de uma autorização com a sugestão de uma conta Empresarial:

Veja na Referência da API:

Resposta da API de Autorização

A resposta é dada em formato XML. O exemplo do link abaixo mostra uma resposta de sucesso a uma chamada à API de autorização:

Veja na Referência da API:

Caso ocorra algum erro na chamada à API de Autorização uma resposta de erro será retornada, como no link de exemplo abaixo. Ela indicará todos os erros identificados na chamada:

Veja na Referência da API:

Direcionando o vendedor para o fluxo de autorização

Após realizar uma chamada com sucesso à API, você deve direcionar o vendedor para o fluxo de autorização, usando o código de requisição retornado. O exemplo abaixo mostra uma URL montada para que o usuário inicie um fluxo de autorização.

https://pagseguro.uol.com.br/v2/authorization/request.jhtml?code={resquestCode}

Fluxo de autorização

Ao realizar a chamada com sucesso à API de autorização e redirecionar o cliente ao PagSeguro, será exibido uma tela com base nas informações que você encaminhou na chamada.

Se você não encaminhou nenhum dado do cliente ou encaminhou os dados e o PagSeguro verificou que este cliente não possui uma conta no PagSeguro, será apresentado uma tela propondo a criação de uma conta primariamente e abaixo a opção de efetuar o login no PagSeguro conforme a Imagem 6 abaixo:

Imagem 6

Se você encaminhou os dados e o PagSeguro verificou que este cliente possui uma conta no PagSeguro, será apresentado os campos para que ele possa efetuar o login no PagSeguro primariamente e abaixo a opção propondo a criação de uma conta conforme a Imagem 7 abaixo:

Imagem 7

Após ter criado a conta ou ter entrado com sua senha, será apresentado uma tela informando ao cliente que a sua aplicação deseja ter acesso às permissões enviadas na chamada de autorização. É apresentada também ao cliente a explicação de cada uma das permissões e a opção de autorizar ou não a aplicação conforme a Imagem 8 abaixo:

Imagem 8

Após a decisão do cliente, clicando em Autorizar ou Não autorizar, ele será redirecionado para a sua URL de retorno. Neste retorno o PagSeguro encaminha via GET o código de notificação da autorização para que você possa consultar na hora o resultado desta autorização.

O retorno será feito como o exemplo a seguir:

GET http://www.seusite.com.br/retorno?notificationCode={notificationCode}

Além disso, o PagSeguro envia uma notificação para o seu site via POST.

Notificações

Após o comprador autorizar a aplicação, o PagSeguro enviará via POST uma notificação ao seu sistema com o status da autorização.

A Imagem 9 ilustra o funcionamento da notificação. Note que é o PagSeguro que inicia o processo de notificação ao enviar um código para seu sistema.

Imagem 9

Configurando o recebimento de notificações

Para utilizar a API de Notificações você deve primeiramente ter criado uma aplicação. O endereço (URL) de notificação é configurado no momento da criação da aplicação, porém pode ser passado também como parâmetro na chamada como vimos anteriormente.

A visualização ou alteração desta URL em uma aplicação já existente pode ser feito através da página de listagem de aplicações no endereço https://pagseguro.uol.com.br/aplicacao/listagem.jhtml, clicando no botão Editar aplicação.

Recebendo uma notificação de autorização

Uma vez configurado o endereço para onde o PagSeguro irá enviar notificações, o próximo passo é preparar seu sistema para receber o código de notificação. O PagSeguro envia as notificações para a URL que você configurou usando o protocolo HTTP, pelo método POST.

Veja abaixo um exemplo de notificação enviada pelo PagSeguro (as linhas foram quebradas para facilitar a leitura):

POST http://lojamodelo.com.br/notificacao HTTP/1.1
Host:pagseguro.uol.com.br
Content-Length:85
Content-Type:application/x-www-form-urlencoded
notificationCode=766B9C-AD4B044B04DA-77742F5FA653-E1AB24
&notificationType=applicationAuthorization

Note que a notificação não possui nenhuma informação sobre a autorização. Portanto, assim que seu sistema recebe uma notificação, ele deve consulta-la para obter os dados, como descrito adiante. Lembre-se que, enquanto seu sistema não consultar uma notificação enviada, o PagSeguro irá envia-la novamente a cada 2 horas, até um máximo de 5 tentativas. Se seu sistema ficou indisponível por um período maior que este e não recebeu nenhum dos envios da notificação, ainda assim é possível obter os dados de suas autorizações usando a Consulta de Autorizações.

Consultas

O PagSeguro conta com uma API de Consultas para que você possa obter os dados de suas autorizações de forma fácil, rápida e segura.

Veja abaixo como efetuar uma consulta:

Consultando uma autorização pelo código de notificação

Esta consulta deve ser utilizada para consultar uma notificação recebida através do POST encaminhado pelo PagSeguro ou através do parâmetro GET (notificationCode) encaminhado através do redirect da página de autorização do PagSeguro a fim de obter os dados da autorização. A chamada deve ser efetuada utilizando o método GET.

URL de consulta: https://ws.pagseguro.uol.com.br/v2/authorizations/notifications/{notificationCode}?appId={appId}&appKey={appKey}

Consultando uma autorização pelo seu código

Esta consulta possibilita o acesso a todos os dados de uma autorização a partir de seu código identificador. A chamada deve ser efetuada utilizando o método GET.

URL de consulta: https://ws.pagseguro.uol.com.br/v2/authorizations/{authorizationCode}?appId={appId}&appKey={appKey}

Consulta de autorizações da aplicação por data

Através desta consulta você poderá verificar todas as autorizações atreladas a sua aplicação dentro de um determinado período. Para isso deve ser informado as credenciais, além do range de data da consulta com o intervalo máximo de 90 dias.

URL de consulta (As linhas foram quebradas para melhor visualização):

GET https://ws.pagseguro.uol.com.br/v2/authorizations
?appId={appId}
&appKey={appKey}
&initialDate=2014-11-01T00:00&finalDate=2014-11-28T00:00

O resultado é apresentado em XML conforme o exemplo do link abaixo:

Veja na Referência da API:

Caso ocorra algum erro na chamada à API de Consultas, seja algum erro nos parâmetros informados ou alguma falha técnica no sistema, uma resposta de erro será retornada, como no link de exemplo abaixo. Ela indicará todos os erros identificados na chamada:

Veja na Referência da API:

Utilizando as APIs do PagSeguro

Após obter a autorização, sua aplicação possui a possibilidade de utilizar os serviços do PagSeguro em nome do vendedor.

Para utilizar as API’s do PagSeguro utilizando a autorização concedida pelo cliente, basta que você substitua as credenciais email e token pelas credenciais appId, appKey e pelo authorizationCode gerado pela aplicação.

Veja abaixo como utilizar as API’s disponíveis no PagSeguro com o Modelo de Aplicação:

API de Pagamentos

Sem a utilização do Modelo de Aplicações, a chamada para o PagSeguro é feita utilizando o e-mail e token do cliente. Veja abaixo um exemplo da chamada sem o Modelo de Aplicações para a API de Pagamentos (as linhas foram quebradas para facilitar a leitura):

curl https://ws.pagseguro.uol.com.br/v2/checkout/ -d\
"email=suporte@lojamodelo.com.br\
&token=95112EE828D94278BD394E91C4388F20\
&currency=BRL\
&itemId1=0001\
&itemDescription1=Produto PagSeguroI\
&itemAmount1=99999.99\
&itemQuantity1=1\
&itemWeight1=1000\
&reference=REF1234\
&senderName=Jose Comprador\
&senderAreaCode=99\
&senderPhone=99999999\
&senderEmail=comprador@uol.com.br\
&shippingType=1\
&shippingAddressStreet=Av. PagSeguro\
&shippingAddressNumber=9999\
&shippingAddressComplement=99o andar\
&shippingAddressDistrict=Jardim Internet\
&shippingAddressPostalCode=99999999\
&shippingAddressCity=Cidade Exemplo\
&shippingAddressState=SP\
&shippingAddressCountry=ATA"

Com a utilização do Modelo de Aplicações, a chamada para o PagSeguro é feita utilizando o appId, o appKey e o authorizationCode do cliente. Veja abaixo um exemplo da mesma chamada utilizando o Modelo de Aplicações (as linhas foram quebradas para facilitar a leitura):

curl https://ws.pagseguro.uol.com.br/v2/checkout/ -d\
"appId=lojamodelo\
&appKey=CAD9C79F4141DF222401CF940D6F0682\
&authorizationCode=D8DD848AC9C98D9EE44C5FB3A1E53913\
&currency=BRL\
&itemId1=0001\
&itemDescription1=Produto PagSeguroI\
&itemAmount1=99999.99\
&itemQuantity1=1\
&itemWeight1=1000\
&reference=REF1234\
&senderName=Jose Comprador\
&senderAreaCode=99\
&senderPhone=99999999\
&senderEmail=comprador@uol.com.br\
&shippingType=1\
&shippingAddressStreet=Av. PagSeguro\
&shippingAddressNumber=9999\
&shippingAddressComplement=99o andar\
&shippingAddressDistrict=Jardim Internet\
&shippingAddressPostalCode=99999999\
&shippingAddressCity=Cidade Exemplo\
&shippingAddressState=SP\
&shippingAddressCountry=ATA"

API de Notificações

A API de Notificações é a única API onde não é necessário o authorizationCode. Veja abaixo um exemplo da chamada para esta API sem o Modelo de (as linhas foram quebradas para facilitar a leitura):

https://ws.pagseguro.uol.com.br/v2/transactions/notifications
/9E884542-81B3-4419-9A75-BCC6FB495EF1
?email=suporte@lojamodelo.com.br
&token=95112EE828D94278BD394E91C4388F20

Utilizando o modelo de aplicações basta que você passe, ao invés do e-mail e token do cliente, o appId e appKey da sua aplicação conforme abaixo (as linhas foram quebradas para facilitar a leitura):

https://ws.pagseguro.uol.com.br/v2/transactions/notifications
/9E884542-81B3-4419-9A75-BCC6FB495EF1
?appId=lojamodelo
&appKey=D8DD848AC9C98D9EE44C5FB3A1E53913

API de Consultas

Veja abaixo um exemplo da chamada para esta API de Consulta de Transações sem o Modelo de (as linhas foram quebradas para facilitar a leitura):

https://ws.pagseguro.uol.com.br/v2/transactions
/9E884542-81B3-4419-9A75-BCC6FB495EF1
?email=suporte@lojamodelo.com.br
&token=95112EE828D94278BD394E91C4388F20

Utilizando o modelo de aplicações basta que você passe, ao invés do e-mail e token do cliente, o appId, appKey e o authorizationCode conforme abaixo (as linhas foram quebradas para facilitar a leitura):

https://ws.pagseguro.uol.com.br/v2/transactions
/9E884542-81B3-4419-9A75-BCC6FB495EF1
?appId=lojamodelo
&appKey=D8DD848AC9C98D9EE44C5FB3A1E53913
&authorizationCode=D8DD848AC9C98D9EE44C5FB3A1E53913

O mesmo processo pode ser aplicado para as consultas de Histórico de transações e para a consulta de Transações abandonadas.

Criação de Assinaturas

Veja abaixo um exemplo da chamada para esta API de Assinaturas (as linhas foram quebradas para facilitar a leitura):

curl -k https://ws.pagseguro.uol.com.br/v2/pre-approvals/request -d\
"email=suporte@lojamodelo.com.br\
&token=95112EE828D94278BD394E91C4388F20\
&reference=REF1234\
&redirectURL=http://www.sualoja.com.br/retorno.php\
&reviewURL=http://www.sualoja.com.br/revisao.php\
&preApprovalCharge=manual\
&preApprovalName=Seguro contra roubo do Produto PagSeguroI\
&preApprovalDetails=Seguro contra roubo do Produto PagSeguroI.\
&preApprovalAmountPerPayment=100.00\
&preApprovalPeriod=Monthly\
&preApprovalDayOfMonth=28\
&preApprovalMaxPaymentsPerPeriod=1\
&preApprovalMaxAmountPerPeriod=100.00\
&preApprovalInitialDate=2013-09-01T00:00:000-03:00\
&preApprovalFinalDate=2013-12-01T00:00:000-03:00\
&preApprovalMaxTotalAmount=400.00”

Com a utilização do Modelo de Aplicações, a chamada para o PagSeguro é feita utilizando o appId, o appKey e o authorizationCode do cliente. Veja abaixo um exemplo da mesma chamada utilizando o Modelo de Aplicações (as linhas foram quebradas para facilitar a leitura):

curl -k https://ws.pagseguro.uol.com.br/v2/pre-approvals/request -d\
"appId=lojamodelo\
&appKey=CAD9C79F4141DF222401CF940D6F0682\
&authorizationCode=D8DD848AC9C98D9EE44C5FB3A1E53913\
&reference=REF1234\
&redirectURL=http://www.sualoja.com.br/retorno.php\
&reviewURL=http://www.sualoja.com.br/revisao.php\
&preApprovalCharge=manual\
&preApprovalName=Seguro contra roubo do Produto PagSeguroI\
&preApprovalDetails=Seguro contra roubo do Produto PagSeguroI.\
&preApprovalAmountPerPayment=100.00\
&preApprovalPeriod=Monthly\
&preApprovalDayOfMonth=28\
&preApprovalMaxPaymentsPerPeriod=1\
&preApprovalMaxAmountPerPeriod=100.00\
&preApprovalInitialDate=2013-09-01T00:00:000-03:00\
&preApprovalFinalDate=2013-12-01T00:00:000-03:00\
&preApprovalMaxTotalAmount=400.00”

Outras APIs seguem o mesmo processo.

Revogação de autorização

O seu cliente pode revogar a qualquer momento a autorização concedida para a aplicação. Para isso, ele deve se logar na conta PagSeguro e acessar o link a seguir, selecionar a aplicação desejada e clicar em Remover autorização conforme a Imagem 10.

Link: https://pagseguro.uol.com.br/aplicacao/listarAutorizacoes.jhtml

Imagem 10

Tabela de Erros

Caso sua aplicação informe algum dado incorreto ou fora do padrão esperado pela aplicação, será retornado uma mensagem informando o problema. Confira abaixo os erros que podem ser retornados:

HTTP 401 - Unauthorized Ocorre quando sua aplicação encaminhou uma credencial (e-mail ou token) invalida ou inexistente.

HTTP 405 – Method Not Allowed Ocorre quando sua aplicação efetuou a chamada utilizando um método não esperado. Neste caso verifique se o método da chamada é GET ou POST.

HTTP 415 – Cannot consume content type Ocorre quando não é encaminhado o Content-Type na chamada.

HTTP 400 – Bad Request Ocorre quando um ou mais dados foram encaminhados de forma incorreta ou fora do padrão. Este retorno possui um XML no corpo na mensagem que identifica quais os erros presentes na chamada. O XML possui o seguinte formato:

PARÂMETRO DESCRIÇÃO
12001 appId is required.
12002 appKey is required.
12003 permissions is required.
12004 redirectURL is required.
12005 appId invalid length: {0}
12006 appKey invalid length: {0}
12007 reference invalid length: {0}
12008 permissions invalid length: {0}
12009 redirectURL must have the same domain as application URL.
12010 permissions invalid: {0}
12011 inactive application: {0}
12012 redirectURL invalid length: {0}
12013 redirectURL invalid value: {0}
50110 Date must be like yyyy-MM-dd
50128 The telephone does not respect the 8 or 9 digit pattern
50129 The telephone area code must have 2 digits
50130 The postal code must have 8 digits
50132 The CPF must have 11 digits
50133 The CNPJ must have 14 digits
50134 Seller must be over 18 years old
50135 Partner must be over 18 years old
50136 Invalid e-mail
50137 Invalid user type
50140 Email too big. Maximum = 60 characters
50141 Name too big. Maximum = 50 characters
50142 Address too big. Maximum = 80 characters
50143 Address Number too big. Maximum = 20 characters
50144 Address Complement too big. Maximum = 40 characters
50145 Address District too big. Maximum = 60 characters
50146 Company Name too big. Maximum = 50 characters
50147 Display Name too big. Maximum = 50 characters
50148 Website URL too big. Maximum = 256 characters