Gateway de Pagamentos Online CobreDireto

Integração

O webservice do CobreDireto foi construído usando o padrão SOAP, bastante popular. Não importa em que linguagem seja construída sua loja, é muito provável que haja pacotes ou bibliotecas SOAP prontas para ela, que vão facilitar a integração.

Há apenas um método disponível no webservice: doService. Os parâmetros que esse método recebe são:

• Version: a versão do webservice que sua loja utiliza. Use “1.1.0”
• Action: “payOrder” se você estiver criando um pedido e “probe” se estiver consultando o status de um pedido.
• Merchant: o código de sua loja no CobreDireto
• User: o login de sua loja no CobreDireto
• Password: a senha de sua loja no CobreDireto
• Data: um XML com os dados necessários para a ação solicitada.

O método doService sempre retornará uma variável doServiceReturn com uma string XML. Veja as seções “Criando o pedido” e “Recebendo o retorno” para mais detalhes sobre o XML enviado no parâmetro “Data” e recebido no retorno do método.

Criando o pedido

Para a criação do pedido, na chamada do SOAP o action deve ser “payOrder”, o XML a ser enviado no parametro Data deve seguir uma estrutura pré-definida.

• ‘order_data’, onde estarão todos os dados do pedido;
• ‘behavior_data’ com as configurações das URL’s de recibo, erro e retorno;
• ‘payment_data’ com as configurações de pagamento;
• ‘customer_data’ com as informações do consumidor, entrega e cobrança.

Você deve ter um nó mestre nomeado ‘payOrder’, dentro deste é necessário ter a sequência abaixo de tags:

Ficando a estrutura inicial desse modo:

<payOrder>
   <order_data>
      Informações do Pedido
   </order_data>
   <behavior_data>
      Configuração de URLs para retorno
   </behavior_data>
   <payment_data>
      Informações sobre o Pagamento
   </payment_data>
   <customer_data>
      Informações do Comprador
   </customer_data>
</payOrder>

Essas tags devem respeitar a ordem mostrada.

1 – Criando a ‘order_data’

A tag ‘order_data’ contém as informações do pedido.

Campo	Descrição	Tipo	Tamanho	Comentário
1 . Objeto ‘order_data’
merch_ref	Número do pedido	String Alfanumérico	20
tax_freigtht	Valor do frete	Long Numérico	18	Somente valores positivos são aceitos. Valor sem formatação. Os dois últimos digitos são centavos: Ex. 1234 = 12,34
order_subtotal	Subtotal do pedido	Long Numérico	18	Somente valores positivos são aceitos. Valor sem formatação. Os dois últimos digitos são centavos: Ex. 1234 = 12,34
order_total	Valor total = taxas + discount_plus + subtotal + interests_value	Long Numérico	18	Somente valores positivos são aceitos. Valor sem formatação. Os dois últimos digitos são centavos: Ex. 1234 = 12,34
order_items	Itens do pedido	Objetos order_item		O primeiro item representa o primeiro item comprado neste pedido, o segundo item representa o segundo item comprador neste pedido e assim por diante.

Campo	Descrição	Tipo	Tamanho	Comentário
Objeto order_item
code	Código do item na loja	String Alfanumérico	18
description	Descrição do item	String Alfanumérico	300	Não utilizar caracteres especiais: Ex. &
units	Quantidade de unidades	Integer Numérico	9
units_value	Valor unitário do item	Integer Numérico	18	Somente valores positivos são aceitos. Valor sem formatação. Os dois últimos digitos são centavos: Ex. 1234 = 12,34

<order_data>
   <merch_ref>número do pedido</merch_ref>
   <tax_freight>Valor do frete</tax_freight>
   <order_subtotal>Subtotal do pedido</order_subtotal>
   <order_total>Total do pedido</order_total>
   <order_items>

      <!-- Os items do pedido, serão descritos aqui,
          separe cada item dentro de uma tag 'order_item' -->
      <order_item>
         <code>Código do item</code>
         <description>Descrição do item</description>
         <units>Quantidade do item</units>
         <unit_value>Valor unitário do item</unit_value>
      </order_item>
   </order_items>
</order_data>

Todas as tags que recebem um valor devem recebê-lo como um inteiro, em centavos. Ex.: R$ 10,50 ==> 1050

2 – Criando a ‘behavior_data’

Dentro da tag ‘behavior_data’ estarão as configurações das URL’s para o CobreDireto, são elas:

<behavior_data>
   <url_post_bell>URL de retorno, para onde
      será enviada a campainha</url_post_bell>
   <url_redirect_success>URL em caso de sucesso,
      normalmente o recibo</url_redirect_success>
   <url_redirect_error>URL para o caso de algum erro
      durante a transação</url_redirect_error>
</behavior_data>

Todas URLs deverão estar com disponibilidade para acesso, através da porta 443 ou 80.

Campo	Descrição	Tipo	Tamanho	Comentário
2. Objeto ‘behavior_data’
url_post_bell	URL para envio do post de aviso de mudança de status.	String Alfanumérico	256	Retorno do pagamento
url_redirect_sucess	URL de direcionamento em caso de termino de processamento com sucesso.	String Alfanumérico	256
url_redirect_error	URL de direcionamento em caso de termino de processamento com erro.	String Alfanumérico	256	Usada quando algum erro ocorre durante o processo do pagamento ou quando o pagamento não é autorizado.

3 – Criando a ‘payment_data’

Você pode pedir ao usuário que escolha o meio e condições de pagamento em seu site. Se o fizer, deverá enviar ao CobreDireto a tag payment_data:

<payment_data>
   <payment>
      <payment_method>Meio de pagamento</payment_method>
      <installments>Quantidade de Parcelas</installments>
   </payment>
</payment_data>

Se você não enviar payment_data, está dizendo ao CobreDireto que não perguntou ao usuário nada sobre forma de pagamento em seu site. Nesse caso, o CobreDireto permitirá ao usuário escolher meio e condições de pagamento.

Campo	Descrição	Tipo	Tamanho	Comentário
3. Objeto ‘payment_data’
payment_method	Meio de pgamento	String Alfanumérico	50	Se não enviar o meio de pagamento escolhido, o CobreDireto apresenta a tela com os meios de pagamento configurados da sua loja. Para enviar o ‘payment_method’, consulte a Tabela de Meios de Pagamento
installments	Número de parcelas	Integer Numérico	9	Se o número de parcelas não for enviado, o CobreDireto assumirá que a loja deseja que o usuário escolha o parcelamento na tela de pagamento do CobreDireto.

4 – Criando a ‘customer_data’

Dentro do customer_data, existem mais três tags (customer_info, billing_info, shipment_info).

Campo	Descrição	Tipo	Tamanho	Comentário
4. Objeto ‘customer_data’
customer_info	Dados do consumidor	Objeto do tipo customer_item		Tag obrigatória caso criado "customer_data".
billing_info	Dados da cobrança	Objeto do tipo customer_item		Opcional, caso queira enviar os dados de cobrança seguir mesma estrutura customer_info.
shipment_info	Dados da entrega	Objeto do tipo customer_item		Opcional, caso queira enviar os dados de entrega seguir mesma estrutura customer_info.

A tag customer_data é opcional. Se for criada, a tag customer_info é obrigatória.

Campo	Descrição	Tipo	Tamanho	Comentário
Objeto customer_item
fist_name	Primeiro nome do consumidor	String Alfanumérico	30
middle_name	Nome do meio do consumidor	String Alfanumérico	60
last_name	Último nome	String Alfanumérico	30
email	E-mail válido	String Alfanumérico	256
document	Documento (normalmente CPF)	String Alfanumérico	50
phone_home	Telefone residencial	Obejto do tipo Phone
address_zip	CEP	String Numérico	8

Campo	Descrição	Tipo	Tamanho	Comentário
Objeto phone
area_code	Código de area	String Numérico	4
phone_number	Número de telefone	String Numérico	15

<customer_data>
   <customer_info>
      Informações do consumidor
   </customer_info>
   <billing_info>
      Informações de cobrança
   </billing_info>
   <shipment_info>
      Informações de entrega
   </shipment_info>
</customer_data>

Cada uma delas segue a mesma estrutura de XML. A tag phone_home é mais especifica, contendo dentro dela duas outras tags (area_code e phone_number).
Segue a estrutura:

<customer_info>
   <first_name>Primeiro nome</first_name>
   <middle_name>Nome do meio</middle_name>
   <last_name>Último nome</last_name>
   <email>Email válido</email>
   <document>Documento, normalmente o CPF</document>
   <phone_home>
      <area_code>Código DDD</area_code>
      <phone_number>O telefone sem o hifen</phone_number>
   </phone_home>
   <address_zip>CEP sem o hifen</address_zip>
</customer_info>

Com toda a estrutura do payOrder montada, é só requisitar o SOAP passando o payOrder no campo data, com isso feito o webservice do CobreDireto retornará a variável doServiceReturn. Nela esta contida um XML com a seguinte estrutura:

<payOrder>
   <status>Status da comunicação, o status do pedido deve ser
      visto dentro de bpag_data.status</status>
   <msg></msg>
   <bpag_data>
      <status>Status do Pedido</status>
      <msg></msg>
      <url>URL para redirecionamento</url>
      <id>Código do pedido no CobreDireto</id>
   </bpag_data>
</payOrder>

Após receber esse retorno, redirecione o usuário para a URL que você recebeu. Lá ele verá a tela de pagamento. A cada mudança de status do pagamento, você será avisado pelo CobreDireto através da campainha.