Manual do Desenvolvedor
Interface Padrão e
Interface Personalizada
estamos todos ligados
Índice
01
02
03
04
Captura de cartões pela
Interface Personalizada
3
1.1 Elementos da solicitação
de configuração de sessão
4
1.2 Elementos da resposta
de configuração de sessão
8
1.3 Elementos da solicitação de consulta
10
1.4 Elementos da resposta de consulta
12
1.5 Elementos das autorizações
de cartão de banco utilizando dados
da Interface Personalizada
16
Captura de cartões pela Interface Padrão
19
2.1 Elementos de uma solicitação
de configuração de sessão
20
2.2 Elementos de uma resposta
de configuração de sessão
25
2.3 Elementos da solicitação de consulta
27
2.4 Elementos da resposta de consulta
29
Suporte a múltiplos métodos de pagamentos
32
Códigos de resposta das transações
de pagamentos hospedados
33
Clique nos hiperlinks para navegar no material do Manual
do Desenvolvedor Interface Padrão e Interface Personalizada
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
01 Captura de cartões pela Interface
Personalizada
A Interface Personalizada permite que o e-Rede capture dados
sensíveis do titular do cartão em nome dos estabelecimentos
comerciais e processe transações utilizando esses dados.
Já que os estabelecimentos comerciais não capturam e armazenam
os dados dos titulares de cartão diretamente, esse serviço simplifica
seus requisitos de conformidade com os Padrões de Segurança
de Dados da Indústria de Cartões de Pagamento (PCI DSS).
1.1
Elementos da solicitação de configuração
de sessão
Nesta seção, são apresentados os campos obrigatórios para o tipo
de transação de configuração de sessão, bem como um exemplo
de XML desses campos. Aqui, também são exibidas as principais
seções das mensagens de configuração.
• Request
Authentication - Consulte o Guia de Referência
dos Desenvolvedores do e-Rede, seção 2.1.1.1.1
Transaction
• TxnDetails - Consulte o Guia de Referência
dos Desenvolvedores do e-Rede, seção 2.2.1.3. Contém
as informações de pagamento que serão exibidas ao cliente
•H
psTxn - Esta seção contém todos os detalhes específicos
à solicitação de configuração de sessão da Interface
Personalizada
Índice
3
4
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
1.1.1
HpsTxn
Nome do elemento
HpsTxn
Posição
Request.Transaction
Elementos de HPS Txn
Nome do elemento
Descrição
Valores / Limitações
Obrigatório
method
A ação que está sendo solicitada
Deve ter o valor "setup"
S
page_set_id
Um número de ID que significa
o “page set” que deve ser utilizado
ao apresentar a tela de captura
de dados ao titular do cartão.
O valor inteiro de um
page set que já tenha
sido configurado
S
return_url
Uma URL do website
do estabelecimento comercial.
Se esse valor for fornecido, quando
o processo de captura de dados
for concluído, o titular do cartão
será redirecionado a essa URL, em
vez da URL padrão configurada
na Interface Personalizada
Tamanho máximo 2083.
Deve ser totalmente
qualificado
O
expiry_url
Uma URL do website
do estabelecimento comercial. Se
esse valor for fornecido, ao tentar
visitar uma sessão expirada, o
titular do cartão será redirecionado
a essa URL, em vez da URL padrão
expirada configurada na Interface
Personalizada
Tamanho máximo 2083.
Deve ser totalmente
qualificado
O
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
1.1.2
Exemplo de solicitações de XML de configuração de sessão
Exemplo de Solicitação XML para configurar uma sessão,
incluindo Elementos XML opcionais
<Request version=’2’>
<Authentication>
<password>********</password>
<AcquirerCode>
<rdcd_pv>123456789</rdcd_pv>
</AcquirerCode>
</Authentication>
<Transaction>
<TxnDetails>
<merchantreference>mref-123456</merchantreference>
<amount currency=”BRL”>100.00</amount>
</TxnDetails>
<HpsTxn>
<method>setup</method>
<page_set_id>1</page_set_id>
<return_url>https://shop.example.com/process</return_url>
<expiry_url>https://shop.example.com/expired</expiry_url>
</HpsTxn>
</Transaction>
</Request>
1.1.3
DynamicData
Nome do elemento
DynamicData
Posição
Request.Transaction.HpsTxn
Este elemento opcional contém valores que podem ser utilizados
para substituir os valores marcadores de posição da página
de captura de cartão.
Índice
5
6
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
Elementos de DynamicData
Nome do elemento
Descrição
Valores / Limitações
Obrigatório
dyn_data_1
O valor destinado a substituir o
marcador de posição __DYNAMIC_
DATA_FIELD_1__ na página de
captura de cartão
Comprimento máximo:
2.048 caracteres.
O valor deve ser inserido
entre tags CDATA
se contiver HTML
O
dyn_data_2
O valor destinado a substituir o
marcador de posição __DYNAMIC_
DATA_FIELD_2__ na página de
captura de cartão
Comprimento máximo:
2.048 caracteres.
O valor deve ser inserido
entre tags CDATA
se contiver HTML
O
dyn_data_3
O valor destinado a substituir o
marcador de posição __DYNAMIC_
DATA_FIELD_3__ na página de
captura de cartão
Comprimento máximo:
2.048 caracteres.
O valor deve ser inserido
entre tags CDATA
se contiver HTML
O
dyn_data_4
O valor destinado a substituir o
marcador de posição __DYNAMIC_
DATA_FIELD_4__ na página de
captura de cartão
Comprimento máximo:
2.048 caracteres.
O valor deve ser inserido
entre tags CDATA
se contiver HTML
O
dyn_data_5
O valor destinado a substituir o
marcador de posição __DYNAMIC_
DATA_FIELD_5__ na página de
captura de cartão
Comprimento máximo:
2.048 caracteres.
O valor deve ser inserido
entre tags CDATA
se contiver HTML
O
dyn_data_6
O valor destinado a substituir o
marcador de posição __DYNAMIC_
DATA_FIELD_6__ na página de
captura de cartão
Comprimento máximo:
2.048 caracteres.
O valor deve ser inserido
entre tags CDATA
se contiver HTML
O
dyn_data_7
O valor destinado a substituir o
marcador de posição __DYNAMIC_
DATA_FIELD_7__ na página de
captura de cartão
Comprimento máximo:
2.048 caracteres.
O valor deve ser inserido
entre tags CDATA
se contiver HTML
O
Índice
7
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
Elementos de DynamicData
Nome do elemento
Descrição
Valores / Limitações
Obrigatório
dyn_data_8
O valor destinado a substituir o
marcador de posição __DYNAMIC_
DATA_FIELD_8__ na página de
captura de cartão
Comprimento máximo:
2.048 caracteres.
O valor deve ser inserido
entre tags CDATA
se contiver HTML
O
dyn_data_9
O valor destinado a substituir o
marcador de posição __DYNAMIC_
DATA_FIELD_9__ na página de
captura de cartão
Comprimento máximo:
2.048 caracteres.
O valor deve ser inserido
entre tags CDATA
se contiver HTML
O
É permitido inserir até nove valores. Se um valor de marcador de posição
estiver vazio ou ausente, o marcador de posição será removido
da página de captura de cartão visualizada pelo titular do cartão.
Para que o HTML possa ser utilizado nos valores marcadores de posição,
o conteúdo do elemento dyn_data deve ser inserido entre tags CDATA.
Exemplo de HTML inserido entre tags CDATA
<![CDATA[some <b>HTML</b> data]]>
1.1.4
Exemplo de solicitação de configuração de sessão
com dados dinâmicos
Exemplo de solicitação XML para configurar uma sessão,
incluindo DynamicData
<Request version=’2’>
<Authentication>
<password>********</password>
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
<AcquirerCode>
<rdcd_pv>123456789</rdcd_pv>
</AcquirerCode>
</Authentication>
<Transaction>
<TxnDetails>
<merchantreference>mref-123456</merchantreference>
<amount currency=”BRL”>100.00</amount>
</TxnDetails>
<HpsTxn>
<method>setup</method>
<page_set_id>1</page_set_id>
<return_url>https://shop.example.com/process</rreturn_url>
<expiry_url>https://shop.example.com/expired</expiry_url>
<DynamicData>
<dyn_data_1>
<![CDATA[some <b>dynamic</b> data]]>
</dyn_data_1>
<dyn_data_2>
<![CDATA[more dynamic data]]>
</dyn_data_2>
</DynamicData>
</HpsTxn>
</Transaction>
</Request>
1.2 Elementos da resposta de configuração
de sessão
Os elementos de Resposta XML padrão sempre são exibidos. Consulte
o Guia de Referência dos Desenvolvedores do e-Rede, seção 2.2.3.
Além disso, os elementos a seguir específicos a Interface Personalizada
serão exibidos como resposta a uma solicitação bem-sucedida
de configuração de sessão. Uma configuração bem-sucedida é indicada
pela exibição de um código de status 1. Qualquer outro código indica
uma solicitação rejeitada ou um erro.
Índice
8
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
Nome do elemento
HpsTxn
Posição
Response
Elementos de HPSTxn
Nome do elemento
Descrição
hps_url
A URL do HPS. Deve ser inclusa pelo estabelecimento comercial
session_id
Um valor único que corresponde à sessão que foi configurada
na Interface Personalizada
Os elementos hps_url e session_id devem ser utilizados pelo
estabelecimento comercial para redirecionar o titular do cartão
à página hospedada.
1.2.1
Exemplo de Respostas XML de configuração de sessão
O exemplo de mensagem XML a seguir será exibido como resposta
a uma solicitação bem-sucedida de configuração de sessão.
Exemplo de Resposta XML a uma configuração
de sessão bem-sucedida
<Response version=’2’>
<HpsTxn>
<hps_url>https://dpg.example.com/hps/</hps_url>
<session_id>1172</session_id>
</HpsTxn>
<gateway_reference>4000900012345671</gateway_reference>
<merchantreference>mref-123456</merchantreference>
<mode>TEST</mode>
<reason>ACCEPTED</reason>
<status>1</status>
<time>1258553216</time>
</Response>
Índice
9
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
O XML a seguir demonstra uma resposta a uma solicitação
de configuração não realizada com êxito.
Exemplo de Resposta XML a uma configuração de sessão
não realizada com êxito
<Response version=’2’>
<gateway_reference>4000900012345671</gateway_reference>
<information>new_session is not a valid HPS method</information>
<merchantreference>mref-123456</merchantreference>
<mode>TEST</mode>
<reason>Invalid transaction type</reason>
<status>15</status>
<time>1256046381</time>
</Response>
1.3 Elementos da solicitação de consulta
Depois que um titular de cartão for redirecionado ao seu website
após o processo de captura de dados, é possível enviar uma transação
de consulta de modo opcional. Isso permitirá determinar se a captura
de dados foi bem-sucedida, sem o envio de uma autorização.
Além disso, essa operação permitirá a obtenção de informações
sobre os detalhes do cartão que foram fornecidos.
1.3.1
Elementos da solicitação de consulta
• Request
Authentication - Consultar a seção 2.1.1.1.1 do Guia
de Referência dos Desenvolvedores do e-Rede
Transaction
• HistoricTxn - C
onsulte a seção 1.3.2
Índice
10
11
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
1.3.2
HistoricTxn
Nome do elemento
HistoricTxn
Posição
Request.Transaction
Elementos de HistoricTxn
Nome do elemento
Descrição
Valores / Limitações
Obrigatório
method
O tipo de transação
query
S
reference
O elemento gateway_reference
da solicitação de configuração de
sessão da Interface Personalizada
S
Exemplo de fragmento de solicitação XML dos elementos
complexos de HistoricTxn
<HistoricTxn>
<reference>3900900100010001</reference>
<method>query</method>
</HistoricTxn>
1.3.3
Exemplo de consulta de configuração de sessão XML
da Interface Personalizada
Exemplo de consulta de configuração de sessão XML
<Request version=’2’>
<Authentication>
<password>********</password>
<AcquirerCode>
<rdcd_pv>123456789</rdcd_pv>
</AcquirerCode>
</Authentication>
<Transaction>
<HistoricTxn>
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
<method>query</method>
<reference>3900900100010001</reference>
</HistoricTxn>
</Transaction>
</Request>
1.4 Elementos da resposta de consulta
Os elementos de Resposta XML padrão sempre são exibidos. Consulte
o Guia de Referência dos Desenvolvedores do e-Rede, seção 2.2.3.
Observe que, para as transações de consulta, se o status exibido for “1”,
isso indica que a consulta foi realizada com êxito. Isso não indica
que a transação consultada foi bem-sucedida.
Ao consultar uma solicitação de configuração de sessão da Interface
Padrão, o conteúdo do elemento “information” da resposta indica
o status da transação consultada. Ela pode ter um dos valores literais
a seguir:
Mensagem de resposta
Significado
You have queried an HPS transaction,
which has stored data that has not yet
been used
O pagamento pode ser efetuado utilizando os dados
armazenados. Prossiga à próxima etapa do processo
de transações
Não foi possível capturar os dados. Neste caso,
o elemento de status da resposta de consulta conterá
o status de código da falha
You have queried an HPS transaction,
whose processing failed
You have queried an HPS transaction,
whose data capture is pending
O titular do cartão ainda não concluiu o processo de captura
You have queried an HPS transaction,
whose data was not used and has been
deleted
Os dados capturados nesta sessão não foram utilizados em
um pagamento antes de seu vencimento e foram excluídos.
Para recapturar as informações de pagamento, envie uma
nova solicitação de configuração
You have queried an HPS transaction,
whose data has been used and
subsequently deleted
Os dados capturados nesta sessão já foram utilizados
em um pagamento. A autorização foi realizada, e os dados
sensíveis do cartão foram excluídos
Índice
12
13
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
Quando o primeiro valor desta lista é exibido, o código de status
será o mesmo que o código de falha original.
O terceiro valor desta lista indica que a captura de dados foi realizada
com êxito e que é possível prosseguir à transação de autorização.
Neste caso, a resposta da consulta também conterá os dados a seguir.
1.4.1
HpsTxn
Nome do elemento
HpsTxn
Posição
Response
Elementos de HpsTxn
Nome do elemento
Descrição
card_scheme
A bandeira do cartão, por exemplo, "MasterCard"
country
O país do cartão de emissão, por exemplo, “BRL"
expirydate
A data de vencimento do cartão em formato MMAA
issuer
O emissor do cartão, por exemplo, "Mybank PL"
pan
Uma versão mascarada do número do cartão
que exibe somente os seis primeiros e últimos
quatro dígitos. O restante dos dígitos é substituído
por asteriscos
cv2_captured
Determina se um valor de CV2 foi capturado
durante o processo da transação do HCC
Yes/No
capture_status
O status atual da transação do HCC no momento
da consulta, por exemplo, "pending” (pendente),
"populated” (inserida)
Pending; Populated;
Purged_used; Purged_
unused
Índice
Valores / Limitações
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
1.4.2
Exemplo da resposta de consulta XML
Exemplo da resposta de consulta XML de uma captura
de dados realizada com êxito
<Response version=’2’>
<HpsTxn>
<card_scheme>MasterCard</card_scheme>
<country>BRL</country>
<expirydate>1214</expirydate>
<issuer>Mybank PL</issuer>
<pan>544433******1111</pan>
<capture_status>populated</capture_status>
<cv2_captured>No</cv2_captured>
</HpsTxn>
<gateway_reference>4000900012345671</gateway_reference>
<information>You have queried an HPS transaction, which has stored
data that has not yet been used</information>
<merchantreference>mref123401</merchantreference>
<mode>TEST</mode>
<reason>ACCEPTED</reason>
<status>1</status>
<time>1256046399</time>
</Response>
Exemplo da resposta de consulta XML de uma captura
de dados pendente
<Response version=’2’>
<HpsTxn>
<capture_status>pending</capture_status>
</HpsTxn>
<gateway_reference>4000900012345671</gateway_reference>
<information>You have queried an HPS transaction, whose data capture
is pending</information>
<merchantreference>mref123401</merchantreference>
<mode>TEST</mode>
<reason>ACCEPTED</reason>
<status>1</status>
<time>1256046399</time>
</Response>
Índice
14
15
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
1.4.3
DynamicCapture
Observe também que este elemento somente é exibido
em uma resposta de consulta se houve captura de dados.
Nome do elemento
DynamicCapture
Posição
Response.HpsTxn
Elementos de DynamicCapture
Nome do elemento
Descrição
Valores / Limitações
capf1
Campo 1 dinamicamente
capturado, se inserido
32 caracteres (máx.)
URL codificada
(exceto espaços)
capf2
Campo 2 dinamicamente
capturado, se inserido
32 caracteres (máx.)
URL codificada
(exceto espaços)
capf3
Campo 3 dinamicamente
capturado, se inserido
32 caracteres (máx.)
URL codificada
(exceto espaços)
capf4
Campo 4 dinamicamente
capturado, se inserido
32 caracteres (máx.)
URL codificada
(exceto espaços)
capf5
Campo 5 dinamicamente
capturado, se inserido
32 caracteres (máx.)
URL codificada
(exceto espaços)
capf6
Campo 6 dinamicamente
capturado, se inserido
32 caracteres (máx.)
URL codificada
(exceto espaços)
capf7
Campo 7 dinamicamente
capturado, se inserido
32 caracteres (máx.)
URL codificada
(exceto espaços)
capf8
Campo 8 dinamicamente
capturado, se inserido
32 caracteres (máx.)
URL codificada
(exceto espaços)
capf9
Campo 9 dinamicamente
capturado, se inserido
32 caracteres (máx.)
URL codificada
(exceto espaços)
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
1.4.4
Exemplo de resposta de consulta XML
com captura de dados dinâmicos
Exemplo da resposta de consulta XML de uma captura
de dados realizada com êxito
<Response version=’2’>
<HpsTxn>
<card_scheme>MasterCard</card_scheme>
<country>BRL</country>
<expirydate>1214</expirydate>
<issuer>Mybank PL</issuer>
<pan>544433******1111</pan>
<DynamicCapture>
<capf1>A. N. Other</capf1>
<capf3>%3Cid%3Ecat%3C%2Fid%3E</capf3>
<capf6>cat</capf6>
<capf9>87</capf9>
</DynamicCapture>
</HpsTxn>
<gateway_reference>4000900012345671</gateway_reference>
<information>You have queried an HPS transaction, which has stored
data that has not yet been used</information>
<merchantreference>mref123401</merchantreference>
<mode>TEST</mode>
<reason>ACCEPTED</reason>
<status>1</status>
<time>1256046399</time>
</Response>
1.5 Elementos das autorizações de cartão de banco
utilizando dados da Interface Personalizada
Assim que os dados de um titular de cartão forem capturados
com a Interface Personalizada, uma transação de cartão pode
ser enviada. Essa transação faz referência à configuração de sessão
da Interface Personalizada, em vez de fornecer dados do cartão.
Índice
16
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
Para obter informações sobre como realizar uma solicitação
desse tipo, consulte o Guia de Referência dos Desenvolvedores
do e-Rede, seção 2.2. Neste caso, em vez de fornecer o elemento
complexo do cartão, devem ser fornecidos os elementos e atributos
a seguir. Nenhum deles pode ser omitido.
Nome do elemento
cardTxn
Posição
Request.Transaction.CardTxn
Elementos de CardTxn
Nome do elemento
Descrição
Valores / Limitações
card_details
Especifica o elemento gateway_reference
de uma configuração de sessão
bem-sucedida da Interface Personalizada
O elemento gateway_reference
fornecido durante a resposta de
configuração deve ter 16 dígitos
Atributos dos elementos de CardTxn
Nome do atributo
type
Atributo do elemento
Valores / Limitações
card_details
Especifica a natureza do elemento
gateway_reference fornecido.
Para uma transação da Interface Personalizada,
ele deve ter o valor "from_hps"
Observe também que o elemento a seguir é opcional para
uma transação que utiliza dados capturados por meio da Interface
Personalizada. Se ele for omitido, o valor da solicitação de configuração
de sessão é utilizado em seu lugar. Consulte o Guia de Referência
dos Desenvolvedores do e-Rede, seção 2.2.1.3.
Índice
Nome do elemento
merchant_reference
Posição
Request.TxnDetails
17
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
1.5.1
Transação de cartão com dados da Interface
Personalizada - Exemplos XML
Exemplo de transação de cartão XML com utilização
de dados capturados
<Request version=’2’>
<Authentication>
<password>********</password>
<AcquirerCode>
<rdcd_pv>123456789</rdcd_pv>
</AcquirerCode>
</Authentication>
<Transaction>
<TxnDetails>
<merchantreference>mref123501</merchantreference>
<amount currency=”BRL”>1000.00</amount>
<capturemethod>ecomm</capturemethod>
</TxnDetails>
<CardTxn>
<Card>
<card_account_type>credit</card_account_type>
</Card>
<method>auth</method>
<card_details type=”from_hps”>4000900012345671</card_details>
</CardTxn>
</Transaction>
</Request>
1.5.2
Exemplo de uma Resposta XML a uma transação
de cartão que utiliza dados da Interface Personalizada
Exemplo de uma Resposta XML a uma transação de cartão
que utiliza dados da Interface Personalizada
<Response version=’2’>
<CardTxn>
<Cv2Avs>
Índice
18
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
<cv2avs_status>SECURITY CODE MATCH ONLY</cv2avs_status>
<policy>0</policy>
</Cv2Avs>
<authcode>794408</authcode>
<card_scheme>Mastercard</card_scheme>
<country>Brazil</country>
<issuer>CREDICARD, S.A.</issuer>
<token>CFA8DEA66BD78DAF4345B50557C226B2B2ED2AC9</token>
</CardTxn>
<acquirer>Rede</acquirer>
<auth_host_reference>2000569</auth_host_reference>
<gateway_reference>3100900010001096</gateway_reference>
<merchantreference>mref123563</merchantreference>
<mid>012341088</mid>
<mode>LIVE</mode>
<reason>ACCEPTED</reason>
<status>1</status>
<time>1363615231</time>
</Response>
02 Captura de cartões pela Interface Padrão
A Interface Padrão permite que o e-Rede capture dados
sensíveis do titular do cartão e autorize pagamentos em nome
dos estabelecimentos comerciais. Ao contrário da Interface
Personalizada, o estabelecimento comercial não precisa enviar
solicitações subsequentes para autorizar o pagamento.
Essa configuração de sessão contém os valores modelo utilizados
pela Interface Padrão para processar a escolha de pagamento
feita pelo titular do cartão na página de captura de cartão
da Interface Padrão.
Índice
19
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
2.1
Elementos de uma solicitação
de configuração de sessão
Nesta seção, são apresentados os campos obrigatórios para o tipo
de transação de configuração de sessão, bem como um exemplo
de XML desses campos. Aqui, também são exibidas as principais
seções das mensagens de configuração.
• Request
Authentication - Consulte a seção 2.1.1.1.1 do Guia de Referência
dos Desenvolvedores do e-Rede
Transaction
• TxnDetails - Consulte o Guia de Referência
dos Desenvolvedores do e-Rede, seção 2.2.1.3.
Contém as informações de pagamento que serão
exibidas ao cliente.
ThreeDSecure - Consulte o Anexo 1 3-D Secure, Seção 1.1.1. do Guia de Referência
dos Desenvolvedores do e-Rede.
Ele contém os detalhes necessários para iniciar
a verificação do 3-D Secure.
•C
ardTxn - Consulte a seção 2.2.1.2 do Guia de Referência
dos Desenvolvedores do e-Rede.
Ela contém o tipo de transação de cartão e outras
informações que serão usadas se o cliente tentar efetuar
o pagamento com cartão.
Card - Consulte o Anexo 1 - 3-D Secure, seção 1.1.1.
do Guia de Referência dos Desenvolvedores do
e-Rede. Ele contém os detalhes necessários para
iniciar a verificação do 3-D Secure.
• CV2AVS - Consulte a seção 2.3.1.1.
do Guia de Referência dos Desenvolvedores
do e-Rede. Ela contém detalhes sobre CV2
e endereços.
•H
psTxn - Esta seção contém todos os detalhes específicos
à solicitação de configuração de sessão do HPS.
Índice
20
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
2.1.1
TxnDetails
Todos os elementos e atributos a seguir são obrigatórios
em uma solicitação de configuração de sessão do HPS.
Nome do elemento
TxnDetails
Posição
Request.Transaction
Elementos de TxnDetails
Nome do elemento
Descrição
Valores / Limitações
capturemethod
Meio de captura da transação
ecomm
merchantreference
Um número de referência único
para cada transação
Mínimo de 6 e máximo de 30 caracteres
alfanuméricos. Deve ser único
amount
O valor da transação
Atributos dos elementos de TxnDetails
Nome do atributo
Atributo do elemento
Valores / Limitações
currency
amount
A moeda é transmitida em formato alfabético
ISO 4217 de três caracteres (o padrão é GBP)
por exemplo, BRL
2.1.2
ThreeDSecure
Nome do elemento
TxnDetails
Posição
Request.Transaction
Este elemento é especificado no Guia de Referência dos
Desenvolvedores do e-Rede, Anexo 1: 3-D Secure, seção 1.1.1.
Não há restrições adicionais.
Índice
21
22
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
2.1.3
2.1.3CardTxn
Nome do elemento
CardTxn
Posição
Request.Transaction
Elementos de CardTxn
Nome do elemento
Descrição
Valores / Limitações
Obrigatório
method
O tipo de transação
Só pode ter os valores
"auth" ou "pre"
S
Este elemento é obrigatório.
2.1.4
Card
Nome do elemento
Card
Posição
Request.Transaction.CardTxn
Em uma configuração de sessão completa da Interface Padrão,
este elemento pode conter somente o elemento CV2AVS.
Não é permitido inserir outros elementos.
Índice
23
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
2.1.5
Cv2Avs
Nome do elemento
Cv2Avs
Posição
Request.Transaction.CardTxn.Card.Cv2Avs
Este elemento é especificado no Guia de Referência
dos Desenvolvedores do e-Rede, seção 2.3.1.1.
Não há restrições adicionais.
2.1.6
HpsTxn
Nome do elemento
HpsTxn
Posição
Request.Transaction
Elementos de HpsTxn
Nome do elemento
Descrição
Valores /
Limitações
Obrigatório
method
A ação que está sendo solicitada
Deve ter o valor
setup_full
S
page_set_id
Um número de ID que significa
o “page set” que deve ser utilizado
ao apresentar a tela de captura
de dados ao titular do cartão
O valor inteiro de um
page set que já tenha
sido configurado
S
return_url
Uma URL do website
do estabelecimento comercial.
Se esse valor for fornecido, quando
o processo de captura de dados
for concluído, o titular do cartão será
redirecionado a essa URL,
em vez da URL padrão configurada
na Interface Padrão
Tamanho máximo
2083. Deve ser
totalmente
qualificado
O
Índice
24
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
Elementos de HpsTxn
Nome do elemento
Descrição
Valores /
Limitações
Obrigatório
expiry_url
Uma URL do website
do estabelecimento comercial.
Se esse valor for fornecido,
ao tentar visitar uma sessão
expirada, o titular do cartão
será redirecionado a essa URL,
em vez da URL padrão expirada
configurada na Interface Padrão
Tamanho máximo
2083. Deve ser
totalmente
qualificado
O
2.1.7
Exemplo de solicitações de XML de configuração
de Sessão
Exemplo de Solicitação XML para configurar uma sessão,
incluindo elementos XML opcionais
<Request version=’2’>
<Authentication>
<password>********</password>
<AcquirerCode>
<rdcd_pv>123456789</rdcd_pv>
</AcquirerCode>
</Authentication>
<Transaction>
<TxnDetails>
<merchantreference>mref-123456</merchantreference>
<amount currency=”BRL”>100.00</amount>
<capturemethod>ecomm</capturemethod>
<ThreeDSecure>
<verify> yes </verify>
<merchant_url> https://www.example-merchant.com.au
</merchant_url>
<purchase_datetime> 20120121 09:31:40 </purchase_datetime>
<purchase_desc> goods </purchase_desc>
<Browser>
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
<device_category> 0 </device_category>
<accept_headers> *.* </accept_headers>
<user_agent> Mozilla </user_agent>
</Browser>
</ThreeDSecure>
</TxnDetails>
<CardTxn>
<method>pre</method>
<Card>
<Cv2Avs>
<cpf>…</cpf>
<postcode>...</postcode>
<street_address1>...</street_address1>
<street_address2>...</street_address2>
<street_address3>...</street_address3>
<street_address4>...</street_address4>
<policy>3</policy>
</Cv2Avs>
</Card>
</CardTxn>
<HpsTxn>
<method>setup_full</method>
<page_set_id>1</page_set_id>
<return_url>https://shop.example.com/process</return_url>
</HpsTxn>
</Transaction>
</Request>
2.2
Elementos de uma resposta
de configuração de sessão
Os elementos de Resposta XML padrão sempre são exibidos. Consulte
o Guia de Referência dos Desenvolvedores do e-Rede, seção 2.2.3.
Além disso, os elementos a seguir específicos a Interface
Índice
25
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
Padrão serão exibidos como resposta a uma solicitação bem-sucedida
de configuração de sessão. Uma configuração bem-sucedida é indicada
pela exibição de um código de status 1. Qualquer outro código indica
uma solicitação rejeitada ou um erro.
Nome do elemento
HpsTxn
Posição
Response
Elementos de HPSTxn
Nome do elemento
Descrição
hps_url
A URL da Interface Padrão
session_id
Um valor único que corresponde à sessão que foi configurada no HPS
Os elementos hps_url e session_id devem ser utilizados
pelo estabelecimento comercial para redirecionar o titular
do cartão à página hospedada.
2.2.1
Exemplo de Respostas XML de configuração
de sessão
O exemplo de mensagem XML a seguir será exibido como resposta
a uma solicitação bem-sucedida de configuração de sessão.
Exemplo de Resposta XML a uma configuração de sessão
bem-sucedida
<Response version=’2’>
<HpsTxn>
<hps_url>https://dev.example.com/hps/</hps_url>
<session_id>1172</session_id>
</HpsTxn>
Índice
26
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
<gateway_reference>4000900012345671</gateway_reference>
<merchantreference>mref-123456</merchantreference>
<mode>TEST</mode>
<reason>ACCEPTED</reason>
<status>1</status>
<time>1258553216</time>
</Response>
O XML a seguir demonstra uma resposta a uma solicitação
de configuração não realizada com êxito.
Exemplo de Resposta XML a uma configuração de sessão
não realizada com êxito
<Response version=’2’>
<gateway_reference>4000900012345671</gateway_reference>
<information>new_session is not a valid HPS method</information>
<merchantreference>mref-123456</merchantreference>
<mode>TEST</mode>
<reason>Invalid transaction type</reason>
<status>15</status>
<time>1256046381</time>
</Response>
2.3
Elementos da solicitação de consulta
A qualquer momento após uma configuração de sessão
bem-sucedida, uma consulta pode ser enviada para determinar
o estado atual da transação. Essa consulta pode ser utilizada
para determinar qual etapa do processo de pagamento foi atingida
pelo titular do cartão e se uma tentativa de pagamento foi realizada
com êxito.
Índice
27
28
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
2.3.1
Elementos esquemáticos da solicitação de consulta
• Request
Authentication - Consulte a seção 2.1.1.1.1
do Guia de Referência dos Desenvolvedores do e-Rede
Transaction
• H
istoricTxn - Consulte a seção 2.2.1.4 do Guia de Referência
dos Desenvolvedores do e-Rede
2.3.2
HistoricTxn
Nome do elemento
HistoricTxn
Posição
Request.Transaction
Elementos de HistoricTxn
Nome do elemento
Descrição
Valores / Limitações
method
O tipo de transação
query
reference
O elemento gateway_reference da solicitação
de configuração de sessão da Interface Padrão
S
S
Exemplo de fragmento de solicitação XML dos elementos
complexos de HistoricTxn
<HistoricTxn>
<reference>3900900100010001</reference>
<method>query</method>
</HistoricTxn>
2.3.3
Exemplo de consulta de configuração de sessão XML
da Interface Padrão
Exemplo de Consulta de Configuração de Sessão XML
<Request version=’2’>
<Authentication>
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
<password>********</password>
<AcquirerCode>
<rdcd_pv>123456789</rdcd_pv>
</AcquirerCode>
</Authentication>
<Transaction>
<HistoricTxn>
<method>query</method>
<reference>3900900100010001</reference>
</HistoricTxn>
</Transaction>
</Request>
2.4
Elementos da resposta de consulta
Os elementos de Resposta XML padrão sempre são exibidos.
Consulte o Guia de Referência dos Desenvolvedores do e-Rede,
Seção 2.2.3. Observe que, para as transações de consulta, se o status
exibido for “1”, isso indica que a consulta foi realizada com êxito.
Isso não indica que a transação consultada foi bem-sucedida.
Ao consultar uma solicitação de configuração de sessão da Interface
Padrão, o conteúdo do elemento “information” da resposta indica
o status da transação consultada. Consulte a seção 4 para obter
uma lista de possíveis códigos de resposta específicos
da Interface Padrão.
2.4.1
AuthAttempts
Este elemento contém uma lista das tentativas de pagamento
realizadas durante a sessão. Ele somente será exibido se o cliente
realizou, no mínimo, uma tentativa de pagamento.
Índice
Nome do elemento
AuthAttempts
Posição
Response.HpsTxn.AuthAttempts
29
30
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
2.4.2
Attempt
Este elemento fornece detalhes sobre uma tentativa
de pagamento realizada durante a sessão.
Nome do elemento
Attempt
Posição
Response.HpsTxn.AuthAttempts
Elementos de Attempt
Nome do elemento
Descrição
gateway_reference
O elemento gateway_reference da tentativa
de autorização do pagamento
reason
O motivo do resultado da tentativa
dc_response
O código de status da tentativa de autenticação
2.4.3
Valores / Limitações
Exemplo da resposta de consulta XML
Exemplo da resposta de consulta XML de um pagamento
efetuado após 2 tentativas de pagamento não realizadas com êxito
<Response version=’2’>
<HpsTxn>
<session_id>1172</session_id>
<gateway_reference>4000900012345674</gateway_reference>
<AuthAttempts>
<Attempt>
<gateway_reference>4000900012345672</gateway_reference>
<reason>Declined</reason>
<status>7</status>
</Attempt>
<Attempt>
<gateway_reference>4000900012345673</gateway_reference>
<reason>Declined</reason>
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
<status>7</status>
</Attempt>
<Attempt>
<gateway_reference>4000900012345674</gateway_reference>
<reason>ACCEPTED</reason>
<status>1</status>
</Attempt>
</AuthAttempts>
</HpsTxn>
<gateway_reference>4000900012345671</gateway_reference>
<merchantreference>mref-123456</merchantreference>
<mode>TEST</mode>
<reason>ACCEPTED</reason>
<status>1</status>
<time>_UNIX_TIME_</time>
</Response>
2.4.4
Exemplo da resposta de consulta XML
Exemplo da Resposta de Consulta XML após falha
de todas as tentativas de pagamento
<Response version=’2’>
<HpsTxn>
<session_id>1172</session_id>
<AuthAttempts>
<Attempt>
<gateway_reference>4000900012345672</gateway_reference>
<reason>Declined</reason>
<status>7</status>
</Attempt>
<Attempt>
<gateway_reference>4000900012345673</gateway_reference>
<reason>Declined</reason>
<status>7</status>
</Attempt>
<Attempt>
Índice
31
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
32
<gateway_reference>4000900012345674</gateway_reference>
<reason>Declined</reason>
<status>7</status>
</Attempt>
</AuthAttempts>
</HpsTxn>
<gateway_reference>4000900012345671</gateway_reference>
<information>You have queried an HPS transaction, where the all retry
attempts were exhausted.</information>
<merchantreference>mref-123456</merchantreference>
<mode>TEST</mode>
<reason>HPS: The maximum number of retry transaction was breached</reason>
<status>822</status>
<time>_UNIX_TIME_</time>
</Response>
2.4.5
Consulta de uma tentativa de pagamento
Os detalhes de uma tentativa de pagamento podem ser obtidos
consultando o elemento gateway_reference que é exibido como
um elemento secundário do elemento Attempt.
Para as consultas de tentativas de pagamento dos cartões de banco,
as respostas são exibidas conforme a seção 2.4 do Guia de Referência
dos Desenvolvedores do e-Rede.
03 Suporte a múltiplos métodos de pagamentos
Ao usar as Interfaces Padrão e Personalizada, múltiplas páginas de captura/
pagamentos podem ser configuradas para sua conta. Várias páginas
de captura/pagamentos podem ser necessárias para suportar múltiplos
métodos de pagamento (cartões bancários vs. métodos alternativos
de pagamento). Se você deseja alterar uma página existente ou adicionar
novas páginas, por favor contate o time de suporte do e-Rede. O time
de suporte poderá informá-los sobre o ID da página a suportar
a configuração de cada método de pagamento para sua conta.
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
33
04 Códigos de resposta das transações
de pagamentos hospedados
A seguir, é apresentada uma tabela com os códigos de resposta específicos
às transações de pagamentos hospedados. Para obter uma lista dos códigos
de resposta gerais, consulte o Guia de Referência dos Desenvolvedores
do e-Rede.
Caso seja recebido um código de resposta que não esteja detalhado na tabela
a seguir, entre em contato com sua equipe de suporte do portal para obter
mais detalhes.
Códigos de resposta das transações de pagamentos hospedados
Código
Código de retorno geral
810
HPS: Inappropriate data supplied
811
HPS: Missing data
812
HPS: Invalid reference
A referência fornecida não é válida
813
HPS: Communications error
Houve um problema ao enviar uma solicitação
ou ao receber uma resposta
814
HPS: Invalid HPS response
Resposta válida
815
HPS: Invalid payment reference
A referência fornecida não pode ser utilizada
para efetuar um pagamento
816
HPS: Merchant not configured
Estabelecimento não configurado
817
HPS: Capture field data too long
Os dados especificados no campo de captura
dinâmica são muito longos
818
HPS: Dynamic Data Field too long
O valor do campo Dynamic Data é muito longo
820
HPS: Awaiting customer card details
Aguardando detalhes do pagamento
821
HPS: At least one auth attempted
Aguardando detalhes do pagamento
Índice
Descrição
Foram encontradas informações
que não se aplicam a esse tipo de solicitação
A solicitação enviada não contém dados
obrigatórios
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
Códigos de resposta das transações de pagamentos hospedados
Código
Código de retorno geral
822
HPS: The maximum number of retry
transaction was breached
823
HPS: The merchants customer did not
complete within the session timeout
824
HPS: Payment in flight. Awaiting
customer ACS submission
825
HPS: Merchant not configured for fullhps
826
HPS: The transaction has already been
marked as final
827
HPS: Invalid capturemethod
828
HPS: Awaiting authorization
829
HPS: Invalid payment method for Full
HPS txns
Índice
Descrição
34