pagseguro-pagamento-direto-09-2013 (1)

GUIA DE INTEGRAO PAGAMENTO DIRETO 1

VERSO 1.0.2

Guia de Integrao Pagamento Direto


VERSO 1.0.2

Histrico de Verses

DATA DESCRIO

26/02/2013 Viso Geral

13/09/2013 Reviso

14/09/2013 Reviso

Copyright Todos os direitos reservados. O UOL uma marca comercial do UNIVERSO ONLINE S/A. O logotipo do UOL uma marca comercial do UNIVERSO ONLINE S/A. Outras marcas, nomes, logotipos e marcas so de propriedade de seus respectivos proprietrios. As informaes contidas neste documento pertencem ao UNIVERSO ONLINE S/A. Todos os direitos reservados. UNIVERSO ONLINE S/A. - Av. Faria Lima, 1384, 6 andar, So Paulo / SP, CEP 01452-002, Brasil. O servio PagSeguro no nem pretende ser comparvel a servios financeiros oferecidos por instituies financeiras ou administradoras de cartes de crdito, consistindo apenas em uma forma de facilitar e monitorar a execuo das transaes de comrcio eletrnico por meio da gesto de pagamentos. Qualquer transao efetuada via PagSeguro est sujeita e deve estar em conformidade com as leis da Repblica Federativa do Brasil. Aconselhamos que os termos e condies sejam lidos cuidadosamente.

Aviso Legal O UOL no oferece garantias de qualquer tipo (expressas, implcitas ou estatutrias) com relao s informaes nele contidas. O UOL no assume nenhuma responsabilidade por perdas e danos (diretos ou indiretos), causados por erros ou omisses, ou resultantes da utilizao deste documento ou a informao contida neste documento ou resultantes da aplicao ou uso do produto ou servio aqui descrito. O UOL reserva o direito de fazer qualquer tipo de alterao a quaisquer informaes aqui contidas sem aviso prvio.


VERSO 1.0.2

ndice

Histrico de Verses .......................................................................................... 2

Copyright ............................................................................................................ 2

Aviso Legal ......................................................................................................... 2

ndice .................................................................................................................. 3

Viso Geral......................................................................................................... 4

Autenticao nas APIs do PagSeguro ............................................................... 4

Autenticao Para Vendedores ................................................................................. 4

Autenticao Para Aplicaes ................................................................................... 4

Pagamento Direto .............................................................................................. 5

Integrao ................................................................................................................ 5

Iniciar sesso de pagamento ..................................................................................... 6

Integraes no browser ............................................................................................ 6

Obter identificao do comprador ........................................................................... 7

Obter bandeira do carto de crdito........................................................................ 7

Obter token do carto de crdito ............................................................................. 8

Obter opes de parcelamento ................................................................................ 9

API de Pagamento Direto ................................................................................. 10

Parmentros da API de Pagamento Direto .............................................................. 13

Retorno da API de Pagamento Direto .............................................................. 24

Parmetros de retorno da API de Pagamento Direto ............................................... 26


VERSO 1.0.2

Viso Geral Este documento descreve o processo de integrao com o pagamento direto do PagSeguro. Integrando seu sistema de comrcio eletrnico com o pagamento direto do PagSeguro voc pode oferecer toda a segurana e comodidade do PagSeguro para os seus clientes no momento da compra, sem precisar sair do seu site ou e-commerce. Com ele possvel disponibilizar em seu site os meios de pagamento Carto de Crdito, Dbito Online e Boleto, ou apenas um deles, fica a seu critrio. O Pagamento Direto do PagSeguro est disponvel para contas do tipo Vendedor e Empresarial. As sees seguintes indicaro como possvel integrar seu sistema de pagamentos ao pagamento direto do PagSeguro.

Autenticao nas APIs do PagSeguro Todas as chamadas s APIs do domnio ws.pagseguro.uol.com.br necessitam de autenticao. A autenticao pode ser feita tanto por um vendedor quanto por uma aplicao. Os seguintes parmetros HTTP devem ser passados em todas as chamadas dos servios do domnio citado.

Autenticao Para Vendedores Se voc est criando vendas para a sua prpria loja, ento deve utilizar esse tipo de autenticao.

PARMETRO HTTP DESCRIO

Email

E-mail do vendedor Presena: Obrigatrio. Tipo: Texto. Formato: Um e-mail vlido, com limite de 60 caracteres. O e-mail informado deve estar vinculado conta PagSeguro que est realizando a chamada API.

token

Token do Vendedor Presena: Obrigatrio. Tipo: Texto. Exemplo: 861D0B48DBA3485AB2E36675332F2812

Autenticao Para Aplicaes Se voc uma plataforma ou uma aplicao e est integrando vrias lojas com o Modelo de Aplicaes do PagSeguro, ento deve utilizar esse tipo de autenticao.


VERSO 1.0.2

PARMETRO HTTP DESCRIO

appId

ID da Aplicao. Presena: Obrigatria. Tipo: Texto. Formato: Uma sequncia de at 60 caracteres. Exemplo: pagseguro_uol

appKey

Especifica o token correspondente aplicao PagSeguro que est realizando a requisio. Presena: Obrigatria. Tipo: Texto. Formato: Uma sequncia de 32 caracteres. Exemplo: 861D0B48DBA3485AB2E36675332F2812

authorizationCode

Cdigo que autoriza a aplicao o em suas aes em nome do vendedor Presena: Obrigatrio. Tipo: Texto. Exemplo: 5A220D39B3B31E8BB4E3EFA4FCC4E6L5

Pagamento Direto A API de pagamento direto oferece maior controle e flexibilidade sobre o processo de pagamento. Com essa integrao o cliente fica no ambiente do seu e-commerce ou site durante todo o processo de compra, sem necessidade de cadastro ou pginas intermedirias de pagamento. Para fazer essa integrao o PagSeguro criou alguns servios que juntos possibilitam construir um checkout integrado, seguro e invisvel para o comprador.

Integrao Para fazer a integrao do Pagamento Direto, voc precisa seguir os seguintes passos:

Iniciar sesso de pagamento (Todos os meios de pagamento) Obter a bandeira do carto de crdito (Apenas para Carto de Crdito) Obter o token do carto de crdito (Apenas para Carto de Crdito) Verificar as opes de parcelamento (Apenas para Carto de Crdito) Obter identificao do comprador (Todos os meios de pagamento) Efetuar o pagamento utilizando a API de pagamento direto (Todos os meios de

pagamento)


VERSO 1.0.2

Iniciar sesso de pagamento Para iniciar um pagamento direto necessrio ter um ID de sesso vlido. Este servio retorna o ID de sesso que ser usado nas chamadas JavaScript. A explicao vlida tanto para a chamada por parmetros HTTP quanto para a chamada por formato XML. Esta API requer a autenticao descrita na pgina 4. URL: HttpMethod: POST https://ws.pagseguro.uol.com.br/v2/sessions

Retorno:

1.

2.

3. 620f99e348c24f07877c927b353e49d3

4.

Integraes no browser A API de pagamento direto possui algumas funes JavaScript para algumas operaes que devem ser executadas no browser do cliente, funes que sero descritas mais adiante. E para essas funes existe uma API JavaScript que deve ser importada no final da pgina dos meios de pagamento: PagSeguroDirectPayment.setSessionId('ID DE SESSO GERADO NA PGINA 5);

Esse JavaScript possui um objeto chamado PagSeguroDirectPayment, que a interface de acesso aos mtodos. Repare que logo depois de importar o arquivo, deve ser executado mtodo setSessionId com o ID de sesso descrito na pgina 5. Nas funes abaixo os eventos de sucesso e erro ocorrem em chamadas callback no JavaScript que so passadas via JSON. Para isso basta passar trs funes JavaScript com nome success, error e complete via JSON na chamada das funes. Sendo que a funo complete ser chamada independente do retorno e as funes success e error sero chamadas dependendo do retorno, ou seja, se o retorno no possuir erro a funo chamada ser a success e se possuir erro a funo chamada ser a error.


VERSO 1.0.2

Obter identificao do comprador Para realizar o pagamento direto, necessrio enviar um identificador do comprador gerado pelo JavaScript. um mtodo simples chamado getSenderHash que no possui parmetros e retorna esse identificador. Esse identificador obrigatrio mesmo para pagamento direto com boleto ou dbito online. Sintaxe: PagSeguroDirectPayment.getSenderHash();

Obter bandeira do carto de crdito Esse processo utilizado apenas para o meio de pagamento carto de crdito. Ele ser utilizado para verificar qual a bandeira do carto que est sendo digitado, existe o mtodo getBrand, esse mtodo recebe por parmetro o bin do carto (primeiros 6 dgitos) e retorna dados da bandeira para aquele BIN como qual a bandeira, o tamanho do cvv, se possui data de expirao e qual algoritmo de validao. A chamada desse servio no obrigatria. Sintaxe: PagSeguroDirectPayment.getBrand({ cardBin: {BIN do nmero do carto}, success: {funo de callback para chamadas bem sucedidas}, error: {funo de callback para chamadas que falharam}, complete: {funo 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" } }


VERSO 1.0.2

Obter token do carto de crdito Esse processo necessrio apenas para o meio de pagamento carto de crdito. Esse servio retorna o token que representa o carto que ser usado na API de pagamento direto. A chamada desse servio obrigatria para uso da API de pagamento com carto de crdito e o mtodo createCardToken. Ele recebe os dados do carto que so: nmero (obrigatrio), cvv (opcional para alguns cartes), data de expirao (opcional para alguns cartes) e a bandeira (opcional para qualquer chamada). Sintaxe: PagSeguroDirectPayment.createCardToken({ cardNumber: {nmero}, brand: {bandeira}, cvv: {cdigo de segurana}, expirationMonth: {ms de expirao}, expirationYear: {ano de expirao}, success: {funo de callback para chamadas bem sucedidas}, error: {funo de callback para chamadas que falharam}, complete: {funo de callback para todas 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 de pagamento direto }, error: function(response) { //tratamento do erro }, complete: function(response) { //tratamento comum para todas chamadas } } //parmetro opcional para qualquer chamada if($("input#bandeira").val() != '') { param.brand = $("input#bandeira").val(); } PagSeguroDirectPayment.createCardToken(param);

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


VERSO 1.0.2

Obter opes de parcelamento Esse processo utilizado apenas para o meio de pagamento carto de crdito. Caso voc queira mostrar opes de parcelamento para o comprador, existe o mtodo getInstallments. Esse servio recebe o valor a ser parcelado (obrigatrio) e a bandeira que se deseja obter o parcelamento (opcional, se no informada retorna os dados para todas bandeiras aceitas pelo PagSeguro). No retorno informado para cada bandeira, as configuraes de cada parcela: novo valor total do pagamento (que deve ser enviado junto na API de pagamento), valor e quantidade da parcela (que tambm devem ser informados na API de pagamento) e um indicador se aquela parcela tem juros ou no (para o caso do vendedor ter configurado promoo no PagSeguro) Sintaxe: PagSeguroDirectPayment.getInstallments({ amount: {valor do pagamento}, brand: {bandeira do carto}, success: {funo de callback para chamadas bem sucedidas}, error: {funo de callback para chamadas que falharam}, complete: {funo de callback para todas chamadas} });

Exemplo: PagSeguroDirectPayment.getInstallments({ amount: $("input#valorPagto").val(), brand: $("input#bandeira").val(), success: function(response) { //opes de parcelamento disponvel }, 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 },{ "quantity":3, "totalAmount":16.64, "installmentAmount":5.55, "interestFree":false } ] } }


VERSO 1.0.2

API de Pagamento Direto Por fim, este servio envia os dados do comprador e do pagamento para realizar a cobrana. URL: HttpMethod: POST https://ws.pagseguro.uol.com.br/v2/transactions

Cada pagamento pode conter um ou mais itens. Cada item representa um produto ou qualquer outro bem que est sendo comprado. Os parmetros associados a itens tm seu nome terminando em um nmero. Por exemplo: os parmetros itemId1, itemDescription1, itemAmount1 e itemQuantity1 referem-se ao primeiro item do pagamento, enquanto que os parmetros itemId2, itemDescription2, itemAmount2 e itemQuantity2 referem-se ao segundo item do pagamento. Veja abaixo um exemplo completo de uma requisio para a API de Pagamentos do PagSeguro informando os dados do pagamento em parmetros HTTP (as linhas foram quebradas para facilitar a leitura). curl https://ws.pagseguro.uol.com.br/v2/transactions/ -d\ "[email protected]\ &token=95112EE828D94278BD394E91C4388F20\ &paymentMode=default\ &paymentMethod=creditCard\ &[email protected]\ &currency=BRL\ &extraAmount=1.00 &itemId1=0001\ &itemDescription1=Notebook Prata\ &itemAmount1=24300.00\ &itemQuantity1=1\ &itemId2=0002\ &itemDescription2=Notebook Rosa\ &itemAmount2=25600.00\ &itemQuantity2=2\ &notificationURL=https://sualoja.com.br/notifica.html\ &reference=REF1234\ &senderName=Jose Comprador\ &senderCPF=22111944785\ &senderAreaCode=11\ &senderPhone=56273440\ &[email protected]\ &senderHash=abc123\ &shippingAddressStreet=Av. Brig. Faria Lima\ &shippingAddressNumber=1384\ &shippingAddressComplement=5o andar\ &shippingAddressDistrict=Jardim Paulistano\ &shippingAddressPostalCode=01452002\ &shippingAddressCity=Sao Paulo\ &shippingAddressState=SP\ &shippingAddressCountry=BRA &shippingType=1 &shippingCost=1.00 &creditCardToken=4as56d4a56d456as456dsa\ &installmentQuantity=5\ &installmentValue=125.22\


VERSO 1.0.2

&creditCardHolderName=Jose Comprador\ &creditCardHolderCPF=22111944785\ &creditCardHolderBirthDate=27/10/1987\ &creditCardHolderAreaCode=11\ &creditCardHolderPhone=56273440 &billingAddressStreet=Av. Brig. Faria Lima\ &billingAddressNumber=1384\ &billingAddressComplement=5o andar\ &billingAddressDistrict=Jardim Paulistano\ &billingAddressPostalCode=01452002\ &billingAddressCity=Sao Paulo\ &billingAddressState=SP\ &billingAddressCountry=BRA\"


VERSO 1.0.2

O exemplo abaixo mostra um exemplo em XML que faz um Pagamento Direto.

1.

2.

3. default

4. creditCard

5.

6. Fulano Silva

7. [email protected]

8.

9. 11

10. 30380000

11.

12.

13.

14. CPF

15. 11475714734

16.

17.

18. abc1234

19.

20. BRL

21. https://sualoja.com.br/notifica.html

22.

23.

24. 1

25. Descricao do item a ser vendido

26. 2

27. 1.00

28.

29.

30. 2

31. Descrio do item a ser vendido

32. 2

33. 1.00

34.

35.

36. 3

37. Descrio do item a ser vendido

38. 2

39. 1.00

40.

41.

42. 0.00

43. R123456

44.

45.

46. Av. Brigadeiro Faria Lima

47. 1384

48. 1 andar

49. Jardim Paulistano

50. Sao Paulo

51. SP

52. BRA

53. 01452002

54.


VERSO 1.0.2

55. 3

56. 0.00

57.

58.

59. 4a56sd456a4d54asd65as4d56a4sd564

60.

61. 2

62. 5.50

63.

64.

65. Nome impresso no cartao

66.

67.

68. CPF

69. 00722333665

70.

71.

72. 20/10/1980

73.

74. 11

75. 999991111

76.

77.

78.

79. Av. Brigadeiro Faria Lima

80. 1384

81. 1 andar


83. Sao Paulo

84. SP

85. BRA

86. 01452002

87.

88.

89.

90.

Parmentros da API de Pagamento Direto A tabela abaixo descreve os parmetros da API de Pagamento Direto. Para a integrao usando XML o elemento raiz o .

PARMETRO DESCRIO

Parmetro HTTP: receiverEmail Elemento XML:

Especifica o e-mail que deve vai receber o pagamento

Presena: Opcional. Tipo: Texto. Formato: Um e-mail vlido, com limite de 60 caracteres. O e-mail informado deve estar vinculado conta PagSeguro que est realizando a chamada API.


VERSO 1.0.2

Parmetro HTTP: notificationURL Elemento XML:

URL para envio de notificaes. Presena: Opcional Tipo: Texto Formato: Uma URL vlida, com limite de 255 caracteres.

Parmetro HTTP: currency Elemento XML:

Moeda utilizada.

Indica a moeda na qual o pagamento ser feito. No momento, a nica opo disponvel BRL (Real).

Presena: Obrigatria. Tipo: Texto. Formato: Somente o valor BRL aceito.

Parmetro HTTP: paymentMethod Elemento XML:

Meio de pagamento Presena: Obrigatria. Tipo: Texto. Formato: creditCard, boleto ou eft.

Parmetro HTTP: paymentMode

Elemento XML:

Modo do pagamento Presena: Opcional (se no informado, assume default). Tipo: Texto. Formato: default ou gateway.

Dados do produto

Parmetro HTTP: itemId1, itemId2, etc. Elemento XML:

Identificadores dos itens.

Identificam os itens sendo pagos. Voc pode escolher cdigos que tenham significado para seu sistema e inform-los nestes parmetros. O PagSeguro no realiza qualquer validao sobre esses identificadores, mas eles no podem se repetir em um mesmo pagamento.

Presena: Obrigatria. Tipo: Texto. Formato: Livre, com limite de 100 caracteres.

Parmetro HTTP: itemDescription1, itemDescription2, etc.

Descries dos itens.

Descrevem os itens sendo pagos. A descrio o texto que o


VERSO 1.0.2

Elemento XML:

PagSeguro mostra associado a cada item quando o comprador est finalizando o pagamento, portanto importante que ela seja clara e explicativa.

Presena: Obrigatria. Tipo: Texto. Formato: Livre, com limite de 100 caracteres.

Parmetro HTTP: itemAmount1, itemAmount2, etc. Elemento XML:

Valores unitrios dos itens.

Representam os preos unitrios de cada item sendo pago. Alm de poder conter vrios itens, o pagamento tambm pode conter vrias unidades do mesmo item. Este parmetro representa o valor de uma unidade do item, que ser multiplicado pela quantidade para obter o valor total dentro do pagamento.

Presena: Obrigatria. Tipo: Nmero. Formato: Decimal, com duas casas decimais separadas por ponto (p.e., 1234.56), maior que 0.00 e menor ou igual a 9999999.00.

Parmetro HTTP: itemQuantity1, itemQuantity2, etc. Elemento XML:

Quantidades dos itens.

Representam as quantidades de cada item sendo pago. Alm de poder conter vrios itens, o pagamento tambm pode conter vrias unidades do mesmo item. Este parmetro representa a quantidade de um item, que ser multiplicado pelo valor unitrio para obter o valor total dentro do pagamento.

Presena: Obrigatria. Tipo: Nmero. Formato: Um nmero inteiro maior ou igual a 1 e menor ou igual a 999.

Parmetro HTTP: reference Elemento XML:

Cdigo de referncia.

Define um cdigo para fazer referncia ao pagamento. Este cdigo fica associado transao criada pelo pagamento e til para vincular as transaes do PagSeguro s vendas registradas no seu sistema.

Presena: Opcional. Tipo: Texto. Formato: Livre, com o limite de 200 caracteres.

Parmetro HTTP: extraAmount Elemento XML:

Valores extras a serem cobrados Presena: Opcional. Tipo: Nmero. Formato: Decimal, com duas casas decimais separadas por ponto (p.e., 1234.56), maior que 0.00 e menor ou igual a 9999999.00.


VERSO 1.0.2

Elemento XML:

Dados do comprador.

Parmetro HTTP: senderEmail Elemento XML:

E-mail do comprador.

Especifica o e-mail do comprador que est realizando o pagamento.

Presena: Obrigatrio. Tipo: Texto. Formato: um e-mail vlido (p.e., [email protected]), com no mximo 60 caracteres.

Parmetro HTTP: senderName Elemento XML:

Nome completo do comprador.

Especifica o nome completo do comprador que est realizando o pagamento.

Presena: Obrigatrio. Tipo: Texto. Formato: No mnimo duas sequncias de caracteres, com o limite total de 50 caracteres.

Elemento XML:

Lista de documentos do comprador.

Elemento XML:

Representa um documento do comprador.

Elemento XML:

Tipo de documento do comprador.

Especifica o tipo de documento do comprador que est realizando o pagamento. Este campo opcional e voc pode envi-lo caso j tenha capturado os dados do comprador em seu sistema e queira evitar que ele preencha esses dados novamente no PagSeguro.

Presena: Obrigatrio. Tipo: Texto. Formato: Case sensitive. Somente o valor CPF aceito.


VERSO 1.0.2

Parmetro HTTP: senderCPF Elemento XML:

CPF do dono do comprador Presena: Obrigatrio. Tipo: Texto. Formato: Nmero.

Parmetro HTTP: senderAreaCode Elemento XML:

DDD do comprador.

Especifica o cdigo de rea (DDD) do comprador que est realizando o pagamento.

Presena: Obrigatrio. Tipo: Nmero. Formato: Um nmero de 2 dgitos correspondente a um DDD vlido.

Parmetro HTTP: senderPhone Elemento XML:

Nmero do telefone do comprador.

Especifica o nmero do telefone do comprador que est realizando o pagamento

Presena: Obrigatrio. Tipo: Nmero. Formato: Um nmero de 7 a 9 dgitos.

Parmetro HTTP: senderHash Elemento XML:

Identificador do vendedor.

Identificador gerado pela API JavaScript do PagSeguro que identifica o vendedor (fingerprint)

Presena: Obrigatrio. Tipo: Texto. Formato: Obtido a partir de uma chamada javascript PagseguroDirectPayment.getSenderHash()

Elemento XML:

Dados da Entrega

Parmetro HTTP: shippingType

Forma de envio do produto.


VERSO 1.0.2

Elemento XML:

Presena: Opcional. Tipo: Nmero. Formato: 1 PAC, 2 SEDEX, 3 - Desconhecido

Parmetro HTTP: shippingCost Elemento XML:

Valor do frete Presena: Opcional. Tipo: Nmero. Formato: Decimal, com duas casas decimais separadas por ponto (p.e., 1234.56), maior que 0.00 e menor ou igual a 9999999.00.

Elemento XML:

Dados do endereo de envio

Parmetro HTTP: shippingAddressCountry Elemento XML:

Pas do endereo de envio.

Informa o pas do endereo de envio do produto.

Presena: Obrigatrio. Tipo: Texto. Formato: No momento, apenas o valor BRA permitido.

Parmetro HTTP: shippingAddressState Elemento XML:

Estado do endereo de envio.

Informa o estado do endereo de envio do produto.

Presena: Obrigatrio. Tipo: Texto. Formato: Duas letras, representando a sigla do estado brasileiro correspondente.

Parmetro HTTP: shippingAddressCity Elemento XML:

Cidade do endereo de envio.

Informa a cidade do endereo de envio do produto.

Presena: Obrigatrio. Tipo: Texto.


VERSO 1.0.2

Formato: Livre. Deve ser um nome vlido de cidade do Brasil, com no mnimo 2 e no mximo 60 caracteres.

Parmetro HTTP: shippingAddressPostalCode Elemento XML:

CEP do endereo de envio.

Informa o CEP do endereo de envio do produto.

Presena: Obrigatrio. Tipo: Nmero. Formato: Um nmero de 8 dgitos.

Parmetro HTTP: shippingAddressDistrict Elemento XML:

Bairro do endereo de envio.

Informa o bairro do endereo de envio do produto.

Presena: Obrigatrio. Tipo: Texto. Formato: Livre, com limite de 60 caracteres.

Parmetro HTTP: shippingAddressStreet Elemento XML:

Nome da rua do endereo de envio.

Informa o nome da rua do endereo de envio do produto.

Presena: Obrigatrio. Tipo: Texto. Formato: Livre, com limite de 80 caracteres.

Parmetro HTTP: shippingAddressNumber Elemento XML:

Nmero do endereo de envio. Informa o nmero do endereo de envio do produto. Presena: Obrigatrio. Tipo: Texto. Formato: Livre, com limite de 20 caracteres.

Parmetro HTTP: shippingAddressComplement

Complemento do endereo de envio.


VERSO 1.0.2

Elemento XML:

Informa o complemento (bloco, apartamento, etc.) do endereo de envio do produto.

Presena: Opcional. Tipo: Texto. Formato: Livre, com limite de 40 caracteres.

Dados para Dbito Online

Elemento XML:

Dados do banco.

Parmetro HTTP: bankName Elemento XML:

Nome do Banco Nome de banco para qual vai ser gerado o link de redirecionamento Presena: Obrigatrio para Dbito Online. Tipo: Texto Formato: bradesco, itau, bancodobrasil, banrisul ou hsbc

Dados do carto

Parmetro HTTP: creditCardToken Elemento XML:

Token do Carto de Crdito Token retornado no servio descrito na Seo 0 Presena: Obrigatrio para Carto de Crdito Tipo: Texto Formato: No tem limite de caracteres

Parmetro HTTP: installmentQuantity Elemento XML:

Quantidade de parcelas Quantidade de parcelas obtidas no servio descrito na Seo 0 Presena: Obrigatrio para Carto de Crdito. Tipo: Inteiro Valores aceitos: [1, 18]

Parmetro HTTP: installmentValue Elemento XML:

Valor das parcelas Valor das parcelas obtidas no descrito na Seo 0 Presena: Obrigatrio para Carto de Crdito.


VERSO 1.0.2

Tipo: Nmero Formato: Numrico com 2 casas decimais e separado por ponto. Ex: 1111.11

Dados do dono do carto

Parmetro HTTP: creditCardHolderName Elemento XML:

Nome impresso no carto de crdito Presena: Obrigatrio para Carto de Crdito. Tipo: Texto Formato: min = 1, max = 50 caracteres

Parmetro HTTP: creditCardHolderBirthDate Elemento XML:

Data de nascimento do dono do carto de crdito Presena: Obrigatrio para Carto de Crdito. Tipo: dd/MM/yyyy Formato: 31/12/2013

Elemento XML:

Lista de documentos do dono do carto de crdito.

Elemento XML:

Representa um documento do dono do carto de crdito.

Elemento XML:

Tipo de documento do dono do carto de crdito. Especifica o tipo de documento do dono do carto de crdito que est sendo usado para realizar o pagamento. Presena: Obrigatrio para Carto de Crdito. Tipo: Texto. Formato: Case sensitive. Somente o valor CPF aceito.


VERSO 1.0.2

Parmetro HTTP: creditCardHolderCPF Elemento XML:

CPF do dono do carto de crdito Presena: Obrigatrio para Carto de Crdito. Tipo: Texto

Elemento XML:

Telefone do dono do carto de crdito.

Parmetro HTTP: creditCardHolderAreaCode Elemento XML:

Cdigo de rea Presena: Obrigatrio para Carto de Crdito. Tipo: Nmero Formato: Um nmero de 2 dgitos correspondente a um DDD vlido.

Parmetro HTTP: creditCardHolderPhone Elemento XML:

Telefone Presena: Obrigatrio para Carto de Crdito. Tipo: Nmero Formato: Um nmero entre 7 e 9 digitos.


VERSO 1.0.2

Dados de endereo de cobrana

Elemento XML:

Endereo de cobrana.

Parmetro HTTP: billingAddressPostalCode Elemento XML:

CEP do endereo de cobrana Presena: Obrigatrio para Carto de Crdito. Formato: Um nmero de 8 dgitos correspondente a um CEP vlido (p.e, 01452002).

Parmetro HTTP: billingAddressStreet Elemento XML:

Nome da Rua Presena: Obrigatrio para Carto de Crdito. Formato: Livre

Parmetro HTTP: billingAddressNumber Elemento XML:

Nmero Presena: Obrigatrio para Carto de Crdito. Formato: Livre

Parmetro HTTP: billingAddressComplement Elemento XML:

Complemento Presena: Opcional para Carto de Crdito. Formato: Livre


VERSO 1.0.2

Parmetro HTTP: billingAddressDistrict Elemento XML:

Bairro Presena: Obrigatrio para Carto de Crdito. Tipo: Texto. Formato: Livre, com limite de 60 caracteres.

Parmetro HTTP: billingAddressCity Elemento XML:

Cidade Presena: Obrigatrio para Carto de Crdito. Formato: Deve ser um nome vlido de cidade do Brasil, com no mnimo 2 e no mximo 60 caracteres.

Parmetro HTTP: billingAddressState Elemento XML:

Estado Presena: Obrigatrio para Carto de Crdito. Formato: Duas letras, representando a sigla do estado brasileiro correspondente (p.e, SP).

Parmetro HTTP: billingAddressCountry Elemento XML:

Pas Presena: Obrigatrio para Carto de Crdito. Formato: Reconhece apenas o valor BRA.

Retorno da API de Pagamento Direto Aps a chamada para a API de Pagamento Direto, retornado um XML com todos os dados da transao conforme o exemplo abaixo:

1.

2.

3. 2011-02-05T15:46:12.000-02:00

4. 2011-02-15T17:39:14.000-03:00


VERSO 1.0.2

5. 9E884542-81B3-4419-9A75-BCC6FB495EF1

6. REF1234

7. 1

8. 3

9.

10. 1

11. 101

12.

13.

14. https://pagseguro.uol.com.br/checkout/imprimeBoleto.jhtml?code=314601B208B24A5CA5

3260000F7BB0D0

15.

16. 49900.00

17. 0.00

18. 0.00

19. 49900.50

20. 0.00

21. 1

22. 2

23.

24.

25. 0001

26. Notebook Prata

27. 1

28. 24300.00

29.

30.

31. 0002

32. Notebook Rosa

33. 1

34. 25600.00

35.

36.

37.

38. Jos Comprador

39. [email protected]

40.

41. 11

42. 56273440

43.

44.

45.

46.

47. Av. Brig. Faria Lima

48. 1384

49. 5o andar


51. 01452002

52. Sao Paulo

53. SP

54. BRA

55.

56. 1

57. 21.50

58.

59.


VERSO 1.0.2

Parmetros de retorno da API de Pagamento Direto

A tabela abaixo descreve os parmetros de retorno da API de Pagamento Direto.

CAMPO DESCRIO

Este campo a raiz do XML e engloba os dados da transao.

Data da criao da transao.

Informa o momento em que a transao foi criada.

Presena: Obrigatria. Tipo: Data/hora. Formato: YYYY-MM-DDThh:mm:ss.sTZD, o formato oficial do W3C para datas. Veja mais sobre formatao de datas.

Data do ltimo evento.

Informa o momento em que ocorreu a ltima alterao no status da transao.

Presena: Obrigatria. Tipo: Data/hora. Formato: YYYY-MM-DDThh:mm:ss.sTZD, o formato oficial do W3C para datas. Veja mais sobre formatao de datas.

Cdigo identificador da transao

Retorna o cdigo que identifica a transao de forma nica.

Presena: Obrigatria. Tipo: Texto. Formato: Uma sequncia de 36 caracteres.

Cdigo de referncia da transao.

Informa o cdigo que foi usado para fazer referncia ao pagamento. Este cdigo foi fornecido no momento do pagamento e til para vincular as transaes do PagSeguro s vendas registradas no seu sistema.

Presena: Opcional. Tipo: Texto. Formato: Livre, com o limite de 200 caracteres.

Tipo da transao.

Representa o tipo da transao recebida. Os valores mais comuns para este campo e seus respectivos resultados so descritos abaixo.


VERSO 1.0.2

CAMPO DESCRIO

Cdigo Significado

1 Pagamento: a transao foi criada por um comprador fazendo um pagamento. Este o tipo mais comum de transao que voc ir receber.

Outros tipos menos comuns de transaes foram omitidos. Note que novos tipos podem ser adicionados em verses futuras da API.

Presena: Obrigatria. Tipo: Nmero. Formato: Inteiro.

Status da transao.

Informa o cdigo representando o status da transao, permitindo que voc decida se deve liberar ou no os produtos ou servios adquiridos. Os valores possveis esto descritos no diagrama de status de transaes e so apresentados juntamente com seus respectivos cdigos na tabela abaixo.

Cdigo Significado

1 Aguardando pagamento: o comprador iniciou a transao, mas at o momento o PagSeguro no recebeu nenhuma informao sobre o pagamento.

2 Em anlise: o comprador optou por pagar com um carto de crdito e o PagSeguro est analisando o risco da transao.

3 Paga: a transao foi paga pelo comprador e o PagSeguro j recebeu uma confirmao da instituio financeira responsvel pelo processamento.

4 Disponvel: a transao foi paga e chegou ao final de seu prazo de liberao sem ter sido retornada e sem que haja nenhuma disputa aberta.

5 Em disputa: o comprador, dentro do prazo de liberao da transao, abriu uma disputa.

6 Devolvida: o valor da transao foi devolvido para o comprador.

7 Cancelada: a transao foi cancelada sem ter sido finalizada.

Outros status menos relevantes foram omitidos. Em resumo, voc


VERSO 1.0.2

CAMPO DESCRIO

deve considerar transaes nos status de Paga para liberao de produtos ou servios.


Origem do cancelamento.

Informa a origem do cancelamento da transao: pelas instituies financeiras (Banco Emissor ou Operadora do Carto) ou pelo PagSeguro.

Valor Significado

INTERNAL PagSeguro

EXTERNAL Instituies Financeiras

Presena: Opcional (somente quando transactionStatus igual a 7). Tipo: Texto. Formato: Valores possveis INTERNAL ou EXTERNAL.

Dados do meio de pagamento usado pelo comprador.

Tipo do meio de pagamento.

Informa o tipo do meio de pagamento usado pelo comprador. Este tipo agrupa diversos meios de pagamento e determina de forma geral o comportamento da transao. A tabela abaixo descreve os valores disponveis e seus significados.

Cdigo Significado

1 Carto de crdito: o comprador escolheu pagar a transao com carto de crdito.

2 Boleto: o comprador optou por pagar com um boleto bancrio.

3 Dbito online (TEF): o comprador optou por pagar a transao com dbito online de algum dos bancos conveniados.

4 Saldo PagSeguro: o comprador optou por pagar a transao utilizando o saldo de sua conta PagSeguro.


VERSO 1.0.2

CAMPO DESCRIO

5 Oi Paggo *: o comprador escolheu pagar sua transao atravs de seu celular Oi.

7

Depsito em conta: o comprador optou por fazer um depsito na conta corrente do PagSeguro. Ele precisar ir at uma agncia bancria, fazer o depsito, guardar o comprovante e retornar ao PagSeguro para informar os dados do pagamento. A transao ser confirmada somente aps a finalizao deste processo, que pode levar de 2 a 13 dias teis.

* Os tipos marcados no esto disponveis para utilizao.


Link para o Pagamento.

Informa a URL para a exibio do boleto ou, quando o meio de pagamento for TEF, a URL para abrir o pop-up do banco. Quando o meio de pagamento for Carto de crdito este parmetro ser omitido.

Presena: Somente para pagamentos via Boleto e TEF. Tipo: Texto. Formato: URL

Cdigo identificador do meio de pagamento

Informa um cdigo que identifica o meio de pagamento usado pelo comprador. O meio de pagamento descreve a bandeira de carto de crdito utilizada ou banco escolhido para um dbito online. A tabela abaixo descreve os possveis valores e seus significados.

Cdigo Significado

101 Carto de crdito Visa.

102 Carto de crdito MasterCard.

103 Carto de crdito American Express.

104 Carto de crdito Diners.

105 Carto de crdito Hipercard.


VERSO 1.0.2

CAMPO DESCRIO

106 Carto de crdito Aura.

107 Carto de crdito Elo.

108 Carto de crdito PLENOCard.

109 Carto de crdito PersonalCard.

110 Carto de crdito JCB.

111 Carto de crdito Discover.

112 Carto de crdito BrasilCard.

113 Carto de crdito FORTBRASIL.

114 Carto de crdito CARDBAN.

115 Carto de crdito VALECARD.

116 Carto de crdito Cabal.

117 Carto de crdito Mais!.

118 Carto de crdito Avista.

119 Carto de crdito GRANDCARD.

201 Boleto Bradesco. *

202 Boleto Santander.

301 Dbito online Bradesco.

302 Dbito online Ita.

303 Dbito online Unibanco. *

304 Dbito online Banco do Brasil.

305 Dbito online Banco Real. *

306 Dbito online Banrisul.

307 Dbito online HSBC.

401 Saldo PagSeguro.

501 Oi Paggo. *


VERSO 1.0.2

CAMPO DESCRIO

701 Depsito em conta - Banco do Brasil

* Os meios de pagamento marcados no esto disponveis para utilizao.


Valor bruto da transao.

Informa o valor bruto da transao, calculado pela soma dos preos de todos os itens presentes no pagamento.

Presena: Obrigatria. Tipo: Nmero. Formato: Decimal, com duas casas decimais separadas por ponto ("."). Por exemplo, 1234.56.

Valor do desconto dado.

Informa o valor do desconto dado a compradores que optaram por pagar com dbito online ou boleto. Este desconto aplica-se quando voc opta por incluir no preo dos produtos o custo do parcelamento de pagamentos com carto de crdito. O desconto dado para no onerar os compradores que optaram por meios vista.


Valor total das taxas cobradas.

Informa o valor total das taxas cobradas pelo PagSeguro nesta transao.


Valor lquido da transao.

Informa o valor lquido da transao, que corresponde ao valor bruto, menos o valor das taxas. Caso presente, o valor de


VERSO 1.0.2

CAMPO DESCRIO

extraAmount (que pode ser positivo ou negativo) tambm considerado no clculo.


Data de crdito.

Data em que o valor da transao estar disponvel na conta do vendedor.

Presena: Presente apenas quando o status da transao for um dos seguintes valores:Paga (3), Disponvel (4), Em disputa (5) ou Devolvida (6). Tipo: Data/hora. Formato: YYYY-MM-DDThh:mm:ss.sTZD, o formato oficial do W3C para datas. Veja mais sobre formatao de datas.

Valor extra.

Informa um valor extra que foi somado ou subtrado do valor pago pelo comprador. Este valor especificado por voc no pagamento e pode representar um valor que voc quer cobrar separadamente do comprador ou um desconto que quer dar a ele.

Presena: Obrigatria. Tipo: Nmero. Formato: Decimal, com duas casas decimais separadas por ponto (.). Por exemplo, 1234.56 ou -1234.56.

Nmero de parcelas.

Indica o nmero de parcelas que o comprador escolheu no pagamento com carto de crdito.


Nmero de itens da transao.

Aponta o nmero de itens contidos nesta transao.



VERSO 1.0.2

CAMPO DESCRIO

Lista de itens contidos na transao. O nmero de itens sob este elemento corresponde ao valor de itemCount.

Representa um item da transao.

Identificador do item.

Identifica o item da transao. Este identificador deve ser nico por transao e foi informado por voc no fluxo de pagamento.

Presena: Obrigatria. Tipo: Texto. Formato: Livre.

Descrio do item.

Descreve o item da transao. A descrio um texto explicativo do item que voc especificou no fluxo de pagamento.

Presena: Obrigatria. Tipo: Texto. Formato: Livre.

Valor unitrio do item.

Informa o preo unitrio do item da transao. Este o valor que foi especificado no fluxo de pagamento.

Presena: Obrigatria. Tipo: Nmero. Formato: Decimal, com duas casas decimais separadas por ponto (p.e., 1234.56).

Quantidade do item.

Informa a quantidade do item da transao. Est a quantidade que foi especificada no fluxo de pagamento.

Presena: Obrigatria. Tipo: Nmero. Formato: Um nmero inteiro maior ou igual a 1 e menor ou igual a 999.


VERSO 1.0.2

CAMPO DESCRIO

Dados do comprador.

E-mail do comprador.

Informa o e-mail do comprador que realizou a transao.

Presena: Obrigatria. Tipo: Texto. Formato: um e-mail vlido (p.e., [email protected]), com no mximo 60 caracteres.

Nome completo do comprador.

Informa o nome completo do comprador que realizou o pagamento.

Presena: Opcional. Tipo: Texto. Formato: No mnimo duas sequncias de caracteres, com o limite total de 50 caracteres.

Dados do telefone do comprador.

DDD do comprador.

Informa o cdigo de rea (DDD) do comprador que realizou o pagamento.

Presena: Opcional. Tipo: Nmero. Formato: Um nmero de 2 dgitos correspondente a um DDD vlido.

Nmero de telefone do comprador.

Informa o nmero do telefone do comprador que realizou o pagamento.

Presena: Opcional. Tipo: Nmero. Formato: Um nmero de 7 a 9 dgitos.

Dados do frete.


VERSO 1.0.2

CAMPO DESCRIO

Tipo de frete.

Informa o tipo de frete a ser usado para o envio do produto. A tabela abaixo informa os valores possveis e seus significados.

Cdigo Significado

1 Encomenda normal (PAC).

2 SEDEX.

3 Tipo de frete no especificado.


Custo total do frete.

Informa o custo total do frete, a partir das opes de frete informadas no fluxo de pagamento.

Presena: Obrigatria. Tipo: Nmero. Formato: Decimal, com duas casas decimais separadas por ponto (p.e., 1234.56).

Dados do endereo de envio.

Pas do endereo de envio.

Informa o pas do endereo de envio do produto.

Presena: Opcional. Tipo: Texto. Formato: No momento, apenas o valor BRA permitido.

Estado do endereo de envio.

Informa o estado do endereo de envio do produto.

Presena: Opcional. Tipo: Texto. Formato: Duas letras, representando a sigla do estado brasileiro correspondente.


VERSO 1.0.2

CAMPO DESCRIO

Cidade do endereo de envio.

Informa a cidade do endereo de envio do produto.

Presena: Opcional. Tipo: Texto. Formato: Livre. Deve ser um nome vlido de cidade do Brasil, de acordo com os dados dos Correios.

CEP do endereo de envio.

Informa o CEP do endereo de envio do produto.

Presena: Opcional. Tipo: Nmero. Formato: Um nmero de 8 dgitos.

Bairro do endereo de envio.

Informa o bairro do endereo de envio do produto.

Presena: Opcional. Tipo: Texto. Formato: Livre.

Nome da rua do endereo de envio.

Informa o nome da rua do endereo de envio do produto.


Nmero do endereo de envio.

Informa o nmero do endereo de envio do produto.


Complemento do endereo de envio.

Informa o complemento (bloco, apartamento, etc.) do endereo de envio do produto.

Presena: Opcional. Tipo: Texto.


VERSO 1.0.2

CAMPO DESCRIO

Formato: Livre.

Documents

pagseguro-pagamento-direto-09-2013 (1)