Pagamento Padrão

Visão Geral

Para iniciar uma requisição de pagamento, você precisa fazer uma chamada à API de Pagamentos do PagSeguro informando os dados do pagamento. Esta requisição cria um código identificador e, com este código, você pode direcionar o comprador para o site do PagSeguro, onde ele realizará o pagamento.

Ao chamar a API de Pagamentos, você pode informar os dados do pagamento de duas formas diferentes: em parâmetros HTTP ou em formato XML.

Pagamento Comum e Pagamento QR Code

O PagSeguro oferece duas formas para criar o Pagamento Padrão: O Pagamento Comum e o Pagamento QR Code. Ao efetuar o Pagamento QR Code, teremos incluído na resposta um QR Code que poderá ser usado por alguns aplicativos específicos para finalizar o fluxo de pagamento através dele. Todas as URLs e Respostas apresentadas aqui serão exibidas com as duas variações. Não há necessidade de se preocupar com os parâmetros, pois são os mesmos. A maior diferença entre ambos os modos é que o Pagamento QR Code não aceita parâmetros via parâmetros HTTP.

Informando os dados em parâmetros HTTP

Uma forma de fazer a requisição à API de Pagamentos é informar os dados do pagamento diretamente em parâmetros HTTP utilizando o método POST. Esta forma é bastante similar ao Pagamento via HTML, com a diferença que a chamada é feita à API de Pagamentos e não ao formulário de pagamento. Essa forma é apenas liberada para o Pagamento Comum.

Veja abaixo a URL da API de Pagamentos do PagSeguro:

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

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

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

Header:

Content-Type: application/x-www-form-urlencoded; charset=ISO-8859-1

Atençã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.

Veja abaixo um exemplo completo de uma requisição para a API de Pagamentos do PagSeguro informando os dados do pagamento em parâmetros HTTP (as linhas foram quebradas para facilitar a leitura).

Exemplo em Sandbox:

curl https://ws.sandbox.pagseguro.uol.com.br/v2/checkout/ -d\
  "email=suporte@lojamodelo.com.br\
&token=57BE455F4EC148E5A54D9BB91C5AC12C\
&currency=BRL\
&itemId1=0001\
&itemDescription1=Produto PagSeguroI\
&itemAmount1=99999.99\
&itemQuantity1=1\
&itemWeight1=1000\
&itemId2=0002\
&itemDescription2=Produto PagSeguroII\
&itemAmount2=99999.98\
&itemQuantity2=2\
&itemWeight2=750\
&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"

Informando os dados em formato XML

Uma forma de fazer a requisição à API de Pagamentos é informar os dados do pagamento no formato XML, esta forma pode ser mais interessante se você já trabalha com XML em seu sistema e prefere estruturar os dados do pagamento neste formato.

Nesse formato você informa o conteúdo XML que representa os dados do pagamento em um único parâmetro HTTP.

Uma vantagem de utilizar o formato XML é informar os itens do pagamento de forma mais estruturada, cada item é informado dentro de uma tag .

Veja abaixo a URL da API de Pagamentos do PagSeguro:

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

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

URL QR Code em Produção: POST https://ws.pagseguro.uol.com.br/v2/checkouts-qrcode

URL QR Code em Sandbox: POST https://ws.sandbox.pagseguro.uol.com.br/v2/checkouts-qrcode

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

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

Header:

Content-Type: application/xml; charset=ISO-8859-1

Atençã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.

Ao fazer a requisição é necessário informar o e-mail e o token da conta de sua loja ou aplicação no PagSeguro como parâmetros na QueryString da URL.

Exemplo de URL Comum em Sandbox com E-mail e Token: POST https://ws.sandbox.pagseguro.uol.com.br/v2/checkout/?email=suporte@lojamodelo.com.br&token=57BE455F4EC148E5A54D9BB91C5AC12C

Veja no link abaixo o exemplo de XML estruturado para representar os dados de um pagamento (os parâmetros são os mesmos tanto para o Pagamento Comum quanto para o Pagamento QR Code:

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_checkout_xml

Resposta da API de Pagamentos

A resposta da API de Pagamentos é dada em formato XML. O exemplo no link abaixo mostra uma resposta de sucesso a uma chamada à API de pagamentos.

Retorno Comum:

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_checkout_xml

Retorno QR Code:

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_checkout_xml

Caso ocorra algum erro na chamada à API de Pagamentos, seja algum erro nos parâmetros informados ou alguma falha técnica no sistema, uma resposta de erro será retornada, como no exemplo do link abaixo. Ela indicará todos os erros identificados na chamada (A listagem também se encontra na Tabela A).

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_checkout_xml

Finalização do Pagamento

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

URL de direcionamento em Produção: GET https://pagseguro.uol.com.br/v2/checkout/payment.html?code=(insira o código da resposta da API de Pagamentos aqui)

URL de direcionamento em Sandbox: GET https://sandbox.pagseguro.uol.com.br/v2/checkout/payment.html?code=(insira o código da resposta da API de Pagamentos aqui)

Exemplo de direcionamento em Sandbox:

https://sandbox.pagseguro.uol.com.br/v2/checkout/payment.html?code=8CF4BE7DCECEF0F004A6DFA0A8243412

Atenção: Para mais detalhes de como finalizar um pagamento, recomendamos a leitura da nossa documentação no link a seguir: /documentacao/pagamentos/configuracoes/redirecionando-apos-pagamento

Tabela A - Listagem de erros

Erros gerais de chamadas às APIs

Código de erro Mensagem
10001 Email is required.
10002 Token is required.
10003 Email invalid value.

Pagamentos via API

Código de erro Mensagem
11001 receiverEmail is required.
11002 receiverEmail invalid length: {0}
11003 receiverEmail invalid value.
11004 Currency is required.
11005 Currency invalid value: {0}
11006 redirectURL invalid length: {0}
11007 redirectURL invalid value: {0}
11008 reference invalid length: {0}
11009 senderEmail invalid length: {0}
11010 senderEmail invalid value: {0}
11011 senderName invalid length: {0}
11012 senderName invalid value: {0}
11013 senderAreaCode invalid value: {0}
11014 senderPhone invalid value: {0}
11015 shippingType is required.
11016 shippingType invalid type: {0}
11017 shippingPostalCode invalid Value: {0}
11018 shippingAddressStreet invalid length: {0}
11019 shippingAddressNumber invalid length: {0}
11020 shippingAddressComplement invalid length: {0}
11021 shippingAddressDistrict invalid length: {0}
11022 shippingAddressCity invalid length: {0}
11023 shippingAddressState invalid value: {0}, must fit the pattern: \w{2} (e. g. "SP")
11024 Itens invalid quantity.
11025 Item Id is required.
11026 Item quantity is required.
11027 Item quantity out of range: {0}
11028 Item amount is required. (e.g. "12.00")
11029 Item amount invalid pattern: {0}. Must fit the patern: \d+.\d{2}
11030 Item amount out of range: {0}
11031 Item shippingCost invalid pattern: {0}. Must fit the patern: \d+.\d{2}
11032 Item shippingCost out of range: {0}
11033 Item description is required.
11034 Item description invalid length: {0}
11035 Item weight invalid Value: {0}
11036 Extra amount invalid pattern: {0}. Must fit the patern: -?\d+.\d{2}
11037 Extra amount out of range: {0}
11038 Invalid receiver for checkout: {0}, verify receiver's account status.
11039 Malformed request XML: {0}.
11040 MaxAge invalid pattern: {0}. Must fit the patern: \d+
11041 MaxAge out of range: {0}
11042 MaxUses invalid pattern: {0}. Must fit the patern: \d+
11043 MaxUses out of range.
11044 InitialDate is required.
11045 InitialDate must be lower than allowed limit.
11046 InitialDate must not be older than 6 months.
11047 InitialDate must be lower than or equal finalDate.
11048 search interval must be lower than or equal 30 days.
11049 finalDate must be lower than allowed limit.
11050 InitialDate invalid format, use 'yyyy-MM-ddTHH:mm' (eg. 2010-01-27T17:25).
11051 finalDate invalid format, use 'yyyy-MM-ddTHH:mm' (eg. 2010-01-27T17:25).
11052 page invalid value.
11053 MaxPageResults invalid value (must be between 1 and 1000).
11157 senderCPF invalid value: {0}