manual do desenvolvedor interface padrão e interface ... · dos desenvolvedores do e-rede, seção...
TRANSCRIPT
Clique nos hiperlinks para navegar no material do Manual do Desenvolvedor Interface Padrão e Interface Personalizada
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
01
0403
02
ÍND
ICE
3
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
01 Captura de cartões pela Interface Personalizada
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
• HpsTxn - Esta seção contém todos os detalhes específicos à solicitação de configuração de sessão da Interface Personalizada
A Interface Personalizada permite que o e-Rede capture dadossensíveis do titular do cartão em nome dos estabelecimentoscomerciais 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 simplificaseus requisitos de conformidade com os Padrões de Segurançade Dados da Indústria de Cartões de Pagamento (PCI DSS).
1.1 Elementos da solicitação de configuração de sessão
4
Índice
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 configuradana 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
5
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
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>
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.
1.1.2
1.1.3
Exemplo de solicitações de XML de configuração de sessão
DynamicData
Nome do elemento DynamicData
Posição Request.Transaction.HpsTxn
6
Índice
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
7
Índice
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]]>
Exemplo de solicitação XML para configurar uma sessão, incluindo DynamicData
<Request version=’2’> <Authentication> <password>********</password>
1.1.4 Exemplo de solicitação de configuração de sessão com dados dinâmicos
8
Í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>
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.
1.2 Elementos da resposta de configuração de sessão
9
Índice
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_idUm 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.
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>
1.2.1 Exemplo de Respostas XML de configuração de sessão
10
Índice
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>
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 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 - Consulte a seção 1.3.2
1.3.1 Elementos da solicitação de consulta
11
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
Nome do elemento HistoricTxn
Posição Request.Transaction
1.3.2
1.3.3
HistoricTxn
Exemplo de consulta de configuração de sessão XML da Interface Personalizada
Elementos de HistoricTxn
Nome do elemento Descrição Valores / Limitações Obrigatório
method O tipo de transação query S
referenceO 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>
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>
12
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
<method>query</method> <reference>3900900100010001</reference> </HistoricTxn> </Transaction></Request>
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:
1.4 Elementos da resposta de consulta
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
You have queried an HPS transaction, whose processing failed
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 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
13
Índice
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 Valores / Limitações
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_capturedDetermina se um valor de CV2 foi capturado durante o processo da transação do HCC
Yes/No
capture_statusO status atual da transação do HCC no momento da consulta, por exemplo, "pending” (pendente), "populated” (inserida)
Pending; Populated; Purged_used; Purged_unused
14
Índice
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> <dc_response>1</dc_response> </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>
15
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
1.4.3 DynamicCapture
Nome do elemento DynamicCapture
Posição Response.HpsTxn
Elementos de DynamicCapture
Nome do elemento Descrição Valores / Limitações
capf1Campo 1 dinamicamente capturado, se inserido
32 caracteres (máx.)URL codificada (exceto espaços)
capf2Campo 2 dinamicamente capturado, se inserido
32 caracteres (máx.)URL codificada (exceto espaços)
capf3Campo 3 dinamicamente capturado, se inserido
32 caracteres (máx.)URL codificada (exceto espaços)
capf4Campo 4 dinamicamente capturado, se inserido
32 caracteres (máx.)URL codificada (exceto espaços)
capf5Campo 5 dinamicamente capturado, se inserido
32 caracteres (máx.)URL codificada (exceto espaços)
capf6Campo 6 dinamicamente capturado, se inserido
32 caracteres (máx.)URL codificada (exceto espaços)
capf7Campo 7 dinamicamente capturado, se inserido
32 caracteres (máx.)URL codificada (exceto espaços)
capf8Campo 8 dinamicamente capturado, se inserido
32 caracteres (máx.)URL codificada (exceto espaços)
capf9Campo 9 dinamicamente capturado, se inserido
32 caracteres (máx.)URL codificada (exceto espaços)
Observe também que este elemento somente é exibido em uma resposta de consulta se houve captura de dados.
16
Í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> <dc_response>1</dc_response> </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>
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.
1.5 Elementos das autorizações de cartão de banco utilizando dados da Interface Personalizada
17
Índice
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.
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.
Nome do elemento cardTxn
Posição Request.Transaction.CardTxn
Nome do elemento merchant_reference
Posição Request.TxnDetails
Elementos de CardTxn
Nome do elemento Descrição Valores / Limitações
card_detailsEspecifica 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 Atributo do elemento Valores / Limitações
type card_details
Especifica a natureza do elemento gateway_reference fornecido. Para uma transação da Interface Personalizada, ele deve ter o valor "from_hps"
18
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
1.5.1
1.5.2
Transação de cartão com dados da Interface Personalizada - Exemplos XML
Exemplo de uma Resposta XML a uma transação de cartão que utiliza dados da Interface Personalizada
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>
Exemplo de uma Resposta XML a uma transação de cartão que utiliza dados da Interface Personalizada <Response version=’2’><CardTxn><Cv2Avs>
19
Índice
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.
20
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
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.
• CardTxn - 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.
• HpsTxn - Esta seção contém todos os detalhes específicos à solicitação de configuração de sessão do HPS.
2.1 Elementos de uma solicitação de configuração de sessão
21
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
2.1.1
2.1.2
TxnDetails
ThreeDSecure
Nome do elemento TxnDetails
Posição Request.Transaction
Nome do elemento TxnDetails
Posição Request.Transaction
Todos os elementos e atributos a seguir são obrigatórios em uma solicitação de configuração de sessão do HPS.
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.
Elementos de TxnDetails
Nome do elemento Descrição Valores / Limitações
capturemethod Meio de captura da transação ecomm
merchantreferenceUm 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 amountA moeda é transmitida em formato alfabético ISO 4217 de três caracteres (o padrão é GBP) por exemplo, BRL
22
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
2.1.4
2.1.3
Card
2.1.3 CardTxn
Nome do elemento Card
Posição Request.Transaction.CardTxn
Nome do elemento CardTxn
Posição Request.Transaction
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.
Este elemento é obrigatório.
Elementos de CardTxn
Nome do elemento Descrição Valores / Limitações Obrigatório
method O tipo de transaçãoSó pode ter os valores "auth" ou "pre"
S
23
Índice
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.
Nome do elemento HpsTxn
Posição Request.Transaction
2.1.6 HpsTxn
Elementos de HpsTxn
Nome do elemento Descrição Valores / Limitações Obrigatório
method A ação que está sendo solicitadaDeve 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
24
Índice
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
<Response version=’2’> <HpsTxn> <hps_url>https://dev.example.com/hps/</hps_url> <session_id>1172</session_id> <dc_response>1</dc_response> </HpsTxn> <gateway_reference>4000900012345671</gateway_reference> <merchantreference>mref-123456</merchantreference> <mode>TEST</mode> <reason>ACCEPTED</reason> <status>1</status> <time>1258553216</time></Response>
25
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
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
2.2 Elementos de uma resposta de configuração de sessão
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.
Os elementos hps_url e session_id devem ser utilizados pelo estabelecimento comercial para redirecionar o titular do cartão à página hospedada.
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
26
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
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> <gateway_reference>4000900012345671</gateway_reference> <merchantreference>mref-123456</merchantreference> <mode>TEST</mode> <reason>ACCEPTED</reason> <status>1</status> <time>1258553216</time> </Response>
27
Índice
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>
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.
2.3 Elementos 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 • HistoricTxn - Consulte a seção 2.2.1.4 do Guia de Referência
dos Desenvolvedores do e-Rede
2.3.1 Elementos esquemáticos da solicitação de consulta
28
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
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 S
referenceO elemento gateway_reference da solicitação de configuração de sessão da Interface Padrão
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> <password>********</password>
29
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
<AcquirerCode> <rdcd_pv>123456789</rdcd_pv> </AcquirerCode> </Authentication> <Transaction> <HistoricTxn> <method>query</method> <reference>3900900100010001</reference> </HistoricTxn> </Transaction></Request>
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 Elementos da resposta de consulta
2.4.1 AuthAttempts
Nome do elemento AuthAttempts
Posição Response.HpsTxn.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.
30
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
2.4.2 Attempt
Nome do elemento Attempt
Posição Response.HpsTxn.AuthAttempts
Este elemento fornece detalhes sobre uma tentativa de pagamento realizada durante a sessão.
Elementos de Attempt
Nome do elemento Descrição Valores / Limitações
gateway_referenceO 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 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>
31
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
<gateway_reference>4000900012345673</gateway_reference> <reason>Declined</reason> <status>7</status> </Attempt> <Attempt> <gateway_reference>4000900012345674</gateway_reference> <dc_response>1</dc_response> <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>
32
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
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> <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>
33
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
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 pagamentosAo 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.
34
Índice
Manual do Desenvolvedor Interface Padrão e Interface Personalizada
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 Descrição
810 HPS: Inappropriate data suppliedForam encontradas informações que não se aplicam a esse tipo de solicitação
811 HPS: Missing dataA solicitação enviada não contém dados obrigatórios
812 HPS: Invalid reference A referência fornecida não é válida
813 HPS: Communications errorHouve um problema ao enviar uma solicitação ou ao receber uma resposta
814 HPS: Invalid HPS response Resposta válida
815 HPS: Invalid payment referenceA 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 longOs 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
821HPS: At least one auth attemptedAguardando detalhes do pagamento
É necessário o envio de pelo o menos uma tentativa de autenticação para a sessão gerada.
35
Índice
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 Descrição
822HPS: The maximum number of retry transaction was breached
Foi excedido o número máximo de tentativas de pagamento permitido para uma mesma sessão.
823HPS: The merchants customer did not complete within the session timeout
O fluxo para a geração do pagamento não foi finalizado dentro do período de expiração permitido para a sessão gerada.
824HPS: Payment in flight. Awaiting customer ACS submission
Fluxo para geração de pagamento em andamento. O sistema está aguardando o envio dos dados do cartão ao emissor.
825HPS: Merchant not configured for full-hps
Estabelecimento não habilitado para transações HPS.
826HPS: The transaction has already been marked as final
Transação já foi marcada como finalizada.
827 HPS: Invalid capturemethodO método de captura informado na transação é inválido.
828 HPS: Awaiting authorization Aguardando autorização da transação.
829HPS: Invalid payment method for Full HPS txns
O método de pagamento informado na transação é inválido para o tipo de transação HPS.