API de Notificações


 

A API de Notificações do Oxipag se destina a prover aos parceiros integradores informações detalhadas sobre as operações de pagamento realizadas através do Oxipag. Através dela, a loja virtual poderá consultar, entre outras informações, o status da operação, a fim de saber se o pagamento foi autorizado pela instituição financeira, se está pendente de autorização e etc.

 

 

Configuração da API

Configurar a API é bastante simples. Basta acessar o seu cadastro clicando em Minha Conta > Meus Dados, e inserir no campo "Url para envio de notificações" a URL para a qual o Oxipag deverá enviar as notificações. Uma vez feita esta configuração, O Oxipag enviará automaticamente uma notificação sempre que uma operação de pagamento mudar de status.

 

 

Conteúdo e características das notificações enviadas

As notificações são enviadas à url configurada(de acordo com o parágrafo anterior) através de um simples POST que contém apenas um parâmetro chamado "key". Veja um exemplo:


POST http://url/configurada/por/voce HTTP/1.1
Host:oxipag.com
Content-Length:70
Content-Type:application/x-www-form-urlencoded
key=f02c4ad50e09a94b20b46ba54f64b8ab


Perceba que a notificação não contém qualquer informação sobre a operação, mas apenas um parâmetro chamado key.  Para acessar os dados da operação propriamente ditos, é necessário fazer uma consulta ao Oxipag, conforme explicaremos a seguir:



Consultando uma notificação

Para obter os dados detalhadas sobre a operação relacionada à notificação recebida, é necessário fazer uma requisição ao Oxipag via GET, cuja qual deve conter a chave da notificação, o seu e-mail cadastrado no Oxipag, o seu token de integração(informado na sua página de cadastro) como no exemplo abaixo:


https://www.oxipag.com/notifications/?key=c4ad50e09a946ba54f64b8ab412a7184

?email=[email protected]
&token=f02c4ad50e09a94b20b46ba54f64b8ab


Veja a descrição detalhada dos parâmetros enviados ao Oxipag na tabela abaixo:



PARÂMETRODESCRIÇÃO
key

Chave da notificação

Este parâmetro, recebido anteriormente do Oxipag, contém a chave da notificação a ser consultada.

Frequencia Obrigatória..
Formato: Sequência de 32 caracteres.

 

email

E-mail do parceiro integrador

E-mail cadastrado no oxipag

Frequência: Obrigatória.
Formato: um e-mail válido

token

Token do parceiro integrador

Sequencia de 32 caracteres utilizada para identificar o integrador, tal sequencia encontra-se na sua página de dados cadastrais no Oxipag, que pode ser acessada em Minha Conta > Meus Dados

Frequência: Obrigatória.

 


Formato: Sequencia de 32 caracteres

 

 

A resposta da requisição é um XML contendo os dados da operação:

 

<operacao>
<data>2012-01-09T22:03:26-02:00</data>
<id>52</id>
<referencia>100000215</referencia>
<tipo>1</tipo>
<status>2</status>
<montanteBrutoBRL>18500</montanteBrutoBRL>
<montanteBrutoBIZ/>
<montanteTaxasBRL>1698</montanteTaxasBRL>
<montanteLiquidoBRL>16802</montanteLiquidoBRL>
<items>
<item>
<codigo>amd-1</codigo>
<descricao>Phenom X6</descricao>
<quantidade>1</quantidade>
<total>18500</total>
</item>
</items>
<comprador>
<nome>José Cliente</nome>
<email>[email protected]</email>
<telefone>
<ddi>55</ddi>
<ddd>11</ddd>
<numero>54855245</numero>
</telefone>
</comprador>
<envio>
<endereco>
<rua>Joaquim Falco Uriarte</rua>
<numero>82</numero>
<complemento/>
<bairro>São Vicente<bairro/>
<cep>88303380</cep>
<cidade>Itajaí</cidade>
<estado>SC</estado>
<pais>Brasil</pais>
</endereco>
</envio>
</operacao>
 
 
 

Veja na tabela abaixo a descrição de cada parâmetro retornado:

 

CAMPODESCRIÇÃO
<operacao>

 

<operacao>
<data>


Data da criação da operação.

Informa data e hora de criação da operação


Formato: YYYY-MM-DDThh:mm:ss.sTZD (ISO)

Frequência: obrigatória

 

<operacao>
<id>


Número identificador da transação

Retorna o número que identifica a operação de forma única.


Tipo: numero inteiro

Frequência: obrigatória

 

<operacao>
<referencia>


Código de referência da transação.


Código de referência atribuido pela loja à operação de pagamento (geralmente utlizado pelos integradores para vincular uma um pagamento ao número interno do pedido)


Formato: texto livre

Frequencia: opcional(presente quando fornecido pelo integrador)

 

<operacao>
<tipo>


Tipo da operação.

Representa o tipo de operação. Os valores mais comuns para este campo e seus respectivos resultados são descritos abaixo.

CódigoSignificado
1 Pagamento: Originada a partir do pagamento de uma compra de produtos ou serviços.
2 Cobrança: Operação originada de um pagamento de cobrança enviada via e-mail


Formato: Numero inteiro.
Frequencia: Obrigatória

 

<operacao>
<status>


Status da operação.

Código que representa o status da operação de pagamento. Abaixo os códigos retornados e os significados:

 

CódigoSignificado
1 Aguardando pagamento: A operação foi criada e totalizada mas o pagamento não foi confirmado até o momento.
2 Paga: O pagamento foi confirmado pela instituição financeira e o valor está pedente de liberação por parte do comprador.
3 Em processo de mediação: O comprador solicitou o bloqueio do pagamento e um processo de mediação está em andamento. O valor da operação ficará retido no Oxipag até que este processo seja concluído.
4 Cancelada: O pagamento não foi efetuado ou aprovado pela instituição financeira e a operação foi cancelada
5 Disponível: A operação foi finalizada com sucesso e o valor está disponível ao vendedor
6 Estornada pelo mediador: o valor da operação foi estornado ao comprador após processo de mediação(disputa) por decisão de um mediador do Oxipag.
7 Estornada pelo recebedor/vendedor: o comprador teve o valor pago estornado por iniciativa da contraparte da operação (vendedor/recebedor sinalizou que o valor pago deveria ser estornado ao comprador sem a necessidade de intervenção do mediador


Formato: Número Inteiro.

Frequência: obrigatória

 

<operacao>
<montanteBrutoBRL>


Valor bruto da operação em Reais.

Contém o valor bruto da operação em Reais(R$), representado por um número inteiro cujos dois ultimos digitos referem-se aos centavos(inclusive quando tratar-se de valor redondo). Tabela de exemplos:

Montante       Representação no XML  
R$ 43,25 <montanteBrutoBRL>4325</montanteBrutoBRL>
R$ 50,00 <montanteBrutoBRL>5000</montanteBrutoBRL>
R$ 60,03

<montanteBrutoBRL>6003</montanteBrutoBRL>

 

 

 

 

 

 

<operacao>
<montanteBrutoBIZ>


Valor Bruto da operacao em BIZ(quando houver).

Contém o valor bruto da operação em Reais(R$), representado por um número inteiro cujos dois ultimos digitos referem-se aos centavos(inclusive quando tratar-se de valor redondo). Exemplos:

Montante        Representação no XML
B$ 43,25 <montanteBrutoBIZ>4325</montanteBrutoBIZ>
B$ 50,00 <montanteBrutoBIZ>5000</montanteBrutoBIZ>
B$ 60,03

<montanteBrutoBIZ>6003</montanteBrutoBIZ>

    

 

 

 

 

 

<operacao>
<montanteLiquidoBRL>


Valor líquido da transação em Reais.

Contém o valor líquido da operação em Reais(R$), representado por um número inteiro cujos dois ultimos digitos referem-se aos centavos(inclusive quando tratar-se de valor redondo). Tabela de exemplos:

Montante        Representação no XML
R$ 43,25 <montanteLiquidoBRL>4325</montanteLiquidoBRL>
R$ 50,00 <montanteLiquidoBRL>5000</montanteLiquidoBRL>
R$ 60,03

<montanteLiquidoBRL>6003</montanteLiquidoBRL>

 

 

 

 

 

 

<operacao>
<items>

Lista de items da operação

<operacao>
<items>
<item>

 

Nó que contém um item da operação, poderá se repetir N vezes, de acordo com o número de itens da operação.

<operacao>
<items>
<item>
<codigo>


Identificador do item.

Código que identifica o produto, informado pelo integrador no post enviado ao oxipag no redirecionamento do fluxo.

Frequência: Obrigatória.
Formato: texto livre.

 

<operacao>
<items>
<item>
<descricao>


Descrição do item.

Texto descritivo sobre o item

Frequência: Obrigatória.
Formato: Texto livre

 

<operacao>
<items>
<item>
<quantidade>


Quantidade do item.

Informa a quantidade do item na operação

Frequência: Obrigatória.
Formato: Número inteiro maior ou igual a 1

 

<operacao>
<items>
<item>
<total>

 


Valor total do item.

Contém o valor total do item(quantidade, multiplicado por preço unitário informado no redirecionamento do fluxo), representado por um número inteiro cujos dois ultimos digitos referem-se aos centavos, inclusive quando o valor for redondo. Exemplos:

 

Montante       Representação no XML  
R$ 43,25 <total>4325</total>
R$ 50,00 <total>5000</total>
R$ 60,03

<total>6003</total>







Frequência: Obrigatória
Formato: Numero inteiro

 

 

<operacao>
<comprador>

 

Este nó do XML contém informações do comprador/pagador do operação. Tais informações são num primeiro momento fornecidas pelo parceiro integrador via post, no momento do redirecionamento do fluxo ao oxipag e podem ser editadas pelo comprador no momento do pagamento, a fim de corrigir campos inconsistentes ou completar campos faltantes.

Frequencia: Obrigatória

 

<operacao>
<comprador>
<nome>

Nome completo do comprador.

Informa o nome completo do comprador que realizou o pagamento.

Presença: Opcional.
Tipo: Texto.
Formato: No mínimo duas sequências de caracteres, com o limite total de 50 caracteres.

<operacao>
<comprador>
<email>


E-mail do comprador.

Informa o e-mail do comprador que realizou a transação.

Presença: Obrigatória.
Formato: texto contendo um e-mail valido

 

<operacao>
<comprador>
<telefone>

Dados do telefone do comprador.

<operacao>
<comprador>
<telefone>
<ddi>


Codigo do país.

Informa o código do país(DDI)

Presença: Opcional.
Formato: Numero inteiro de dois digitos.

 

<operacao>
<comprador>
<telefone>
<ddd>

Codigo do país.

Informa o código do país(DDI)

Presença: Opcional.
Formato: Numero inteiro de dois digitos.

<operacao>
<comprador>
<telefone>
<numero>


Numero

Contém o número do telefone

Frequência:opcional.
Formato: Um número de 8 dígitos.

 

   
<operacao>
<envio>

Nó do XML que contém os dados de envio

<operacao>
<envio>
<endereco>

 

Nó contendo os dados do endereço de envio. Tais informações são num primeiro momento fornecidas pelo parceiro integrador via post, no momento do redirecionamento do fluxo ao oxipag e podem ser editadas pelo comprador no momento do pagamento, a fim de corrigir campos inconsistentes ou completar campos faltantes.

 

<operacao>
<envio>
<endereco>
<pais>


País do endereço de envio.

Contém o país do endereço de envio do produto. Atualmente somente o valor Brasil é retornado.

Frequência: Opcional.
Formato: Texto

 

<operacao>
<envio>
<endereco>
<estado>


Estado do endereço de envio.

Informa o estado do endereço de envio do produto, representado pela sigla do estado, formada por duas letras.

Frequência: Opcional.
Formato: Texto de dois caracteres.

 

<operacao>
<envio>
<endereco>
<cidade>


Cidade do endereço de envio.

Contém o nome da cidade.

Frequência: Opcional.
Formato: Nome da cidade

 

<operacao>
<envio>
<endereco>
<cep>


CEP.

Informa o CEP do endereço de envio do produto.

Frequência: Opcional..
Formato: Um número de 8 dígitos.

 

<operacao>
<envio>
<endereco>
<bairro>


Bairro.

Contém o bairro do endereço de envio.

Presença: Opcional.
Tipo: Texto.
Formato: Livre.

 

<operacao>
<envio>
<endereco>
<rua>


Rua.

Coném a rua do endereço de envio

Frequência: Opcional.
Formato: Texto Livre.

 

<operacao>
<envio>
<endereco>
<numero>


Número.

Informa o número do endereço de envio

Frequência: Opcional.
Formato: Texto Livre.

 

<operacao>
<envio>
<endereco>
<complemento>


Complemento do endereço de envio.

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

Frequência: Opcional.
Formato: Texto Livre.

 

 

 

Um site validado pela Certisign 
					indica que nossa empresa concluiu satisfatoriamente todos os procedimentos para determinar que o domínio validado é de propriedade ou se encontra registrado por uma empresa ou organização autorizada a negociar por ela ou exercer qualquer atividade lícita em seu nome.