Koin APIs

Nossas APIs foram desenvolvidas para oferecer maior controle ao lojista e para tornar o processo de compra e venda transparente.

Com elas, o cliente permanece no e-commerce durante todo o processo de compra, sem ser redirecionado para páginas intermediárias e o lojista pode acompanhar suas vendas, enviar as informações de rastreio e gerenciar seus pedidos diretamente de seu sistema.

Como Utilizar?

Com nossas APIs é possível integrar a Koin das seguintes maneiras:

  Koin Select
O Select é a melhor maneira de utilizar a Koin no checkout da Loja, integrando esta opção, os clientes que já possuem alguma restrição em nossa base não conseguirão finalizar o pedido com a Koin e serão orientados a utilizar outro meio de pagamento, não impactando a experiência de compra.

  Koin Full
Na opção Full, a Koin será apresentada junto aos demais meios de pagamento no checkout da Loja, assim todos os clientes que estiverem finalizando um pedido poderão escolher a KOIN.

  Koin OTAs
No fluxo para OTAs, capturamos informações importantes durante o processo de compra para que seja possível autorizar e personalizar as opções de parcelamento de acordo com a viagem e o cliente.

  Koin Recovery
Já o Recovery é utilizado para recuperar pedidos negados no cartão de crédito. Ele pode ser utilizado sem nenhuma integração ou em conjunto com as opções Select, Full e OTAs (Solicite mais informações em integracao@koin.com.br).


    Koin Select

Esta é a melhor maneira de utilizar a Koin no checkout da Loja, com ela, os clientes que já possuem alguma restrição em nossa base não conseguirão finalizar o pedido com a Koin e serão orientados a utilizar outro meio de pagamento, não impactando a experiência de compra.

Para utilizar o Koin Select corretamente, deve-se realizar o seguinte fluxo de integração:

  1. No checkout da loja, assim que o cliente selecionar a Koin como opção de pagamento, consulte o limite e os valores das parcelas utilizando o serviço de Consultar Crédito e Parcelas ;
  2. Armazene o limite disponível para o cliente, retornado pela KOIN, e compare-o com o valor total do pedido;
    • Quando o limite disponível for menor que o valor total do pedido, deve-se apresentar a seguinte mensagem: "Infelizmente não será possível finalizar o pedido com a KOIN, sugerimos que escolha outra opção de pagamento! Para mais informações entre em contato com a Koin (www.koin.com.br)";
    • Já quando o limite disponível for maior que o valor total do pedido, deve-se apresentar os valores e as opções de parcelamento retornadas (Importante: Para cada parcela haverá um "PaymentType" diferente, que será utilizado para identificar o parcelamento selecionado pelo cliente no momento da compra);
  3. Quando o cliente finalizar a compra, basta utilizar o serviço de Gerar Pedidos para enviar à Koin as informações do pedido e a opção de parcelamento selecionada pelo cliente (PaymentType);
  4. Os pedidos finalizados com Koin podem ser automaticamente Aprovados, Reprovados ou serem enviados para Análise Manual e, para esses casos, deve-se criar uma rotina para consultar o status dos pedidos Em Análise até que eles sejam Aprovados ou Reprovados. Para isso, basta utilizar o serviço de Consultar Status ;

Segue abaixo os serviços utilizados para integração do Koin Select :

Integração Recomendada:

Informar Rastreio;

Cancelar Pedido;











    Koin Full

Na opção Full, a Koin será apresentada junto aos demais meios de pagamento no checkout da Loja, assim todos os clientes que estiverem finalizando um pedido poderão escolher a KOIN.

Para utilizar o Koin Full corretamente, deve-se realizar o seguinte fluxo de integração:

  1. A Koin deverá estar no checkout junto aos demais meios de pagamento;
  2. Assim que o cliente selecionar a KOIN, as opções de parcelamento devem ser consultadas utilizando o serviço de Consultar Parcelas ;
  3. Prepare o checkout de acordo com os valores e opções de parcelamento retornadas (Importante: Para cada parcela haverá um "PaymentType" diferente, que será utilizado para identificar o parcelamento selecionado pelo cliente no momento da compra);
  4. Quando o cliente finalizar a compra, basta utilizar o serviço de Gerar Pedidos para enviar à Koin as informações do pedido e a opção de parcelamento selecionada pelo cliente (PaymentType);
  5. Os pedidos finalizados com Koin podem ser automaticamente Aprovados, Reprovados ou serem enviados para Análise Manual e, para esses casos, deve-se criar uma rotina para consultar o status dos pedidos Em Análise até que eles sejam Aprovados ou Reprovados. Para isso, basta utilizar o serviço de Consultar Status;

Segue abaixo os serviços utilizados para integração do Koin Full :

Integração Recomendada:

Informar Rastreio;

Cancelar Pedido;










    Koin OTAs

Para que possamos autorizar e personalizar as opções de parcelamento de acordo com o cliente e sua viagem, as OTAs devem realizar o seguinte fluxo de integração:

  1. Quando o cliente selecionar a Koin como opção de pagamento, solicite o CPF e o E-mail do pagador, disponibilize um Checkbox com a frase "Li e Aceito os Termos de Uso da KOIN" (Com Link para: https://www.koin.com.br/termos-e-condicoes ) e um botão "Selecionar Parcelas";
  2. Assim que o cliente clicar em "Selecionar Parcelas", consulte a disponibilidade e as opções de parcelamento através do serviço de Autorizar Parcelamento (Importante: A consulta não deve ser realizada sem que o cliente tenha aceito os Termos de Uso da KOIN);
  3. Verifique o retorno da consulta e realize a seguinte validação:
    • Quando o cliente não estiver autorizado a comprar com KOIN, apresente a mensagem: "Parcelamento não autorizado, escolha outra opção de pagamento e finalize sua compra! Para mais informações entre em contato com a KOIN."
    • Já quando o cliente estiver autorizado a comprar com KOIN, apresente os valores e as opções de parcelamento retornadas (Importante: Para cada parcela haverá um "PaymentType" diferente, que será utilizado para identificar o parcelamento selecionado pelo cliente no momento da compra);
  4. Quando o cliente finalizar a compra, basta utilizar o serviço de Gerar Pedidos para enviar à Koin as informações do pedido, do(s) viajante(s) e a opção de parcelamento selecionada pelo cliente (PaymentType);
  5. Os pedidos finalizados com Koin podem ser automaticamente Aprovados, Reprovados ou serem enviados para Análise Manual e, para esses casos, deve-se criar uma rotina para consultar o status dos pedidos Em Análise até que eles sejam Aprovados ou Reprovados. Para isso, basta utilizar o serviço de Consultar Status ;

Segue abaixo os serviços utilizados para integração do Koin OTAs :

Integração Recomendada:

Cancelar Pedido;







Autenticação

Para utilizar as APIs disponibilizadas pela KOIN, primeiro é necessário autenticar-se no serviço que será utilizado. O processo de autenticação é o mesmo para todas as APIs.

A autenticação é necessária, pois somente ela garantirá a origem das informações enviadas para KOIN, além de impossibilitar quaisquer tentativas de utilização não autorizadas.

Utiliza-se a URL do Serviço e as chaves de identificação fornecidas pela Koin no credenciamento da loja, que são: Consumer Key e Secret Key. Com essas informações deve-se criar um Hash, que será inserido junto a outros dados na variável "Autorization" que, por sua vez, deverá ser enviada no header da requisição.

Sequência para Autenticação

A autenticação com a Koin é realizada em fases, são elas:

  1. Primeiro deve-se obter o timestamp do servidor, convertê-lo para UTC e armazenar o resultado em uma variável;
  2. Posteriormente, deve-se converter para HMAC SHA512 as informações abaixo, obedecendo a ordem:
    URL do Serviço (Cada serviço possui sua própria URL, verifique-a na aba "Requisição" da documentação do serviço que está sendo utilizado), concatenada ao timestamp do servidor convertido para UTC (Variável armazenada no 1º passo ) e a Secret Key da Loja;
  3. O resultado da conversão para HMAC SHA512 deve ser convertido para Base64, gerando assim o Hash;
  4. Por fim, a autenticação é realizada enviando no header de requisição a variável "Autorization" com as seguintes informações: Consumer Key, Hash e o timestamp do servidor, exatamente nesta ordem.
IMPORTANTE
Para toda requisição enviada é obrigatório uma nova autenticação.

Exemplo de Autenticação


//Definindo a URL de requisição do serviço
$url = "VERIFIQUE A URL DO SERVIÇO EM SUA RESPECTIVA DOCUMENTAÇÃO";

//Chaves de autenticação
//Solicite as chaves de identificação para a Equipe de Integração (integracao@koin.com.br)
$consumerKey = "informe_a_consumer_key_da_loja"; 
$secretKey = "informe_a_secret_key_da_loja";

//Obtendo o Timestamp do Servidor e armazenando na variável $time
$time = time();
	
//Convertendo o Timestamp para UTC 
date_default_timezone_set("UTC");
	  
//Criando o hash de autenticação
$binaryHash = hash_hmac('sha512', $url.$time, $secretKey, true);
	
//Convertendo para Base64
$hash = base64_encode($binaryHash);
	
//Enviando a requisição
$ch = curl_init();
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonObject);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-Type:application/json; charset=utf-8",
					   "Content-Length:".strlen($jsonObject), 
					   "Authorization: {$consumerKey},{$hash},{$time}"));
						

Gerar Pedidos
(À Vista ou Parcelado)

É através desta API que os pedidos, à vista ou parcelado, são gerados na KOIN. Visando oferecer segurança e facilidade ao processo de compra, não exigimos os dados financeiros do cliente e ele finaliza o pedido na própria página ou aplicativo da Loja.

Requisição

Para gerar um pedido na KOIN, deve-se enviar os dados do cliente, de entrega, os produtos, os valores do pedido e o PaymentType, que varia de acordo com a opção de parcelamento selecionada pelo cliente ao finalizar a compra.

Estas informações devem ser enviadas em um JSON através de uma requisição POST, ou seja, basta verificar os dados obrigatórios em Parâmetros, alimentar o objeto JSON e enviar a requisição.

IMPORTANTE
Todas as APIs disponibilizadas pela Koin necessitam de Autenticação.

URL de Requisição

Ambiente de Testes (Case Sensitive):

Ambiente de Produção (Case Sensitive):

Termos de Uso

Todas a Lojas que utilizam a KOIN, obrigatoriamente deverão apresentar os Termos de Uso em seu checkout.

O cliente só poderá finalizar uma compra com a Koin após aceitar nossos Termos de Uso, sendo assim, deverá haver uma validação no checkout para que pedidos não sejam finalizados sem esse aceite.

URL dos Termos de Uso da KOIN:

Fraud ID

O FraudId é um código de segurança utilizado pela Koin para identificar o cliente em nossos processos de análise, com essa informação garantimos maior segurança ao cliente e ao lojista.

Cada requisição deverá conter um FraudId diferente e para gerá-lo, basta seguir o exemplo abaixo utilizando a URL a seguir:

URL do JS Fraud ID:

ATENÇÃO
Nunca importe o JS para sua aplicação. A Koin frequentemente realiza melhorias no JS e qualquer divergência no FraudId fará com que os pedidos sejam reprovados.

Obtendo o Fraud ID


<html>		
  <head>
  <script type="text/javascript" src="https://resources.koin.com.br/scripts/koin.min.js">
  </script>
  	<script type="text/javascript">
  	   window.onload = function() {
  		GetKoinFraudID(function (guid) { 	
  		document.getElementById('fraudId').innerHTML = guid;});
  			}	
  	</script>
  </head>
    <body>
         FraudId <span id="fraudId"></span>
    </body>
</html>

Parâmetros

Veja abaixo as obrigatoriedades e as descrição dos parâmetros aceitos pela API de Gerar Pedidos:

IMPORTANTE
Atente-se ao parâmetro PaymentType, pois o mesmo irá variar de acordo com a opção de parcelamento selecionada pelo cliente. As opções de parcelamento deverão ser capturadas através do serviço de Consultar Parcelas ou do serviço de Autorizar Parcelamento, no caso das OTAs.

Transaction

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
FraudId String Sim 32 Código utilizado no processo de análise de risco.

Ex: cfbec22f99d2f557e1426821c42ed3dd
Reference String Sim 300 Número do pedido enviado pela loja.

Ex: 12345
Obs.: Recomendamos utilizar apenas números.
Currency String Sim 3 Tipo de moeda utilizada.

Ex: "BRL"
Price Decimal Sim 9.2 Valor total do pedido.
(Soma do itens + valor do frete)

Ex: 250.99
DiscountPercent Decimal Não 2.2 Desconto percentual sobre o valor total do pedido.

Ex: 10
DiscountValue Decimal Não 9.2 Desconto fixo sobre o valor total do pedido.

Ex: 50.99
IncreasePercent Decimal Não 2.2 Acréscimo percentual sobre o valor total do pedido.

Ex: 10
IncreaseValue Decimal Não 9.2 Acréscimo fixo sobre o valor total do pedido.

Ex: 50.99
PaymentType Integer Sim 3 Código que informará a opção de parcelamento selecionada pelo cliente ao finalizar um pedido.

Cada parcela terá um código diferente que deverá ser capturado através do serviço de Consultar Parcelas ou do serviço de Autorizar Parcelamento, no caso das OTAs..

Ex: 25
Buyer Verificar Sim Nó que recebe as informações do Pagador.
Shipping Verificar Sim Nó que recebe as informações de Entrega e Frete.

Quando não enviado, o endereço de cobrança será
considerado também o endereço de entrega.
Items Verificar Sim Nó que recebe as informações dos Itens do pedido.
AdditionalParameters Verificar Sim Nó que recebe os parâmetros adicionais do pedido.
AdditionalData Verificar Sim ¹ Nó que recebe dados adicionais do pedido.

¹ = Obrigatório somente para as OTAs.


Buyer

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
Name String Sim 100 Nome do Pagador.

Ex: João da Silva
Obs.: Sempre enviar o Nome Completo.
Email String Sim 300 E-mail do Pagador.

Ex: joao.silva@dominio.com
BuyerStatus Integer Sim 2 Status do Pagador, sendo:

0 = Verify;
1 = Trusted;
2 = Not Trusted.

Ip String Sim 50 Endereço de IP do Pagador.

Ex: 123.123.12.12
Documents Verificar Sim Nó que recebe os documentos do Pagador.
AdditionalInfo Verificar Sim Nó que recebe informações adicionais referentes ao Pagador.
Phones Verificar Sim Nó que recebe o telefone de contato do Pagador.
Address Verificar Sim Nó que recebe o endereço de cadastro do Pagador.
RegistrationData Verificar Não Nó que recebe o endereço de cadastro do Pagador.

Documents

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
Key String Sim 14 Tipo do documento do Pagador.

- Ao menos o CPF precisa ser enviado.

Ex: CPF
Value String Sim 14 Número do documento do Pagador.
(Pode ser enviado com ou sem máscara)

Ex: 259.228.370-60 ou 25922837060
ATENÇÃO
A Koin ainda não concede crédito para Pessoa Jurídica (CNPJ), sendo assim, deve-se criar uma validação que oculte a Koin como opção de pagamento para esses compradores.

AdditionalInfo

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
Key String Sim 10 Informar a data de nascimento do pagador.

Ex: BirthDay
Value Date Sim 10 Inserir Data de nascimento do pagador.

Formato: yyyy-MM-dd
Ex: 1958-12-22

Phones

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
AreaCode Integer Sim 2 Código de área do telefone de contato.

Ex: 11
Number String Sim 12 Telefone de contato do Pagador.

Ex: 2309-6020
PhoneType Integer Sim 1 Tipo do telefone de contato, sendo:

2 = Residencial;
3 = Comercial;
4 = Celular.


Address

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
ZipCode String Sim 10 CEP do endereço de cadastro ou de entrega.

Ex: 01310-200
Street String Sim 100 Endereço de cadastro ou de entrega.

Ex: Av. Paulista
Number String Sim 10 Número do endereço de cadastro ou de entrega.

Ex: 1728
Complement String Não 300 Complemento do endereço.

Ex: 7º andar
District String Sim 100 Bairro de cadastro ou de entrega.

Ex: Bela Vista
City String Sim 100 Cidade de cadastro ou de entrega.

Ex: São Paulo
State String Sim 2 Estado de cadastro ou de entrega.

Formato: UF;
Ex: SP.
Country String Sim 100 País de cadastro ou de entrega.

Ex: Brasil
AddressType Integer Sim 1 Tipo do endereço, sendo:

1 = Residencial;
2 = Comercial.

RegistrationData

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
Gender Integer Não 1 Sexo do Pagador, sendo:

1 = Feminino;
2 = Masculino.
MaritalStatus Integer Não 2 Estado Civil do Pagador, sendo:

1 = Solteiro;
2 = Casado;
3 = Desquitado;
4 = Divorciado;
5 = Viuvo;
6 = Separado Judicialmente;
7 = Não informado;
8 = Outros.
PlaceOfBirth String Não 100 Cidade onde nasceu o Pagador (Naturalidade).

Ex: Marília.
StateOfBirth String Não 2 Estado onde nasceu o Pagador.

Formato: UF;
Ex: SP.
Nationality String Não 100 País onde nasceu o Pagador (Nacionalidade).

Ex: Brasil.
MothersName String Não 100 Nome da Mãe do Pagador.

Ex: Maria Rita de Cássia.
DocumentType Integer Não 1 Tipo de Documento do Pagador, sendo:

1 = CNH;
2 = RG.
DocumentNumber String Não 100 Número do Documento do Pagador.

Ex: 65269241027.
IssuanceAuthority String Não 100 Orgão Emissor do Documento do Pagador.

Ex: Detran.
IssuanceAuthorityState String Não 2 Estado do Orgão Emissor do Documento do Pagador.

Formato: UF;
Ex: SP.
IssuanceDate Date Não 10 Data de Emissão do Documento do Pagador.

Formato: yyyy-MM-dd
Ex: 2018-12-22
MonthlyIncome Decimal Não 9.2 Renda do Pagador

Ex: 2954.99
Occupation String Não 100 Profissão do Pagador

Ex: Administrador.
JobTitle String Não 100 Cargo do Pagador

Ex: Gerente Financeiro.

Shipping

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
Address Verificar Sim Informações referentes ao endereço de entrega.
DeliveryDate Date Sim 10 Data da utilização do serviço.

- OTAs: enviar data da viagem ou a partir de qual data será possível viajar;
- E-commerces convencionais: enviar previsão de entrega do produto;

Formato: yyyy-MM-dd
Ex: 1958-12-22
Price Decimal Sim 9.2 Valor do frete a ser cobrado.

Ex: 25.00
Obs.: Esse parâmetro é apenas informativo.

Item

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
Reference String Sim 50 Código do item.

Ex: 123456789
Description String Sim 500 Descrição do item.

Ex: Camiseta Selecao Brasileira
Category String Sim 500 Categoria a qual pertence o item.

Ex: Vestuario
Quantity Integer Sim 3 Quantidade de itens que foram adquiridos.

Ex: 2
Price Decimal Sim 9.2 Valor unitário do item.

Ex: 199.90
Obs.: Esse parâmetro é apenas informativo.
Attributes KeyValue Não Atributos que compõem o item.

Ex: [
{"Key":"Cor","Value":"Amarela"},
{"Key":"Tamanho","Value":"M"}
]

AdditionalParameters

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
PartnerId String Só para Plataformas 10 Número de identificação da Plataforma na KOIN, caso sua plataforma ainda não tenha, entre em contato conosco.

Ex: 01
ExpirationDate DateTime Sim ¹ Data e hora de expiração da reserva para a KOIN.

- OTAs: informar data e hora limite para a Koin finalizar a análise do pedido, evitando assim que pedidos sejam aprovados após a reservar expirar;

Formato: yyyy-MM-dd HH:mm:ss
Ex: 2019-10-02 23:59:00
IntermediateId String Sim ¹ 50 Código do intermediário ou da Agência.

Ex: ABC123
SalesChannelId Integer Sim 2 Código do Canal de Vendas, sendo:

3 = Checkout;
5 = Recuperação Checkout;

¹ = Obrigatório somente para as OTAs.



AdditionalData

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
AirlineData Verificar Sim ¹ Nó que recebe as informações do voo.
LodgingData Verificar Sim ² Nó que recebe as informações da hospedagem.

¹ = Obrigatório somente quando houver vôos no pedido.
² = Obrigatório somente quando houver hospedagem no pedido.


AirlineData

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
Legs Verificar Sim Nó que recebe as informações dos trechos.
Passengers Verificar Sim Nó que recebe as informações dos passageiros.

Legs

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
LegNumber Integer Sim 2 Identificação sequencial do trecho.

Ex: 1
Origin String Sim 3 Código do Aeroporto de Origem.

Ex: CGH
Destination String Sim 3 Código do Aeroporto de Destino.

Ex: REC
FlightNumber String Sim 10 Número do Voo.

Ex: 1063
DepartureTime DateTime Sim 19 Data e hora do Voo.

Formato: yyyy-MM-dd HH:mm:ss
Ex: 2019-04-13 08:34:00
StopOverAllowed String Sim 1 StopOver autorizado? Onde:

- Y: Yes
- N: No

Ex: N
IdClass String Não 1 Classe do Voo, onde:

- F: First Class
- J: Business Class
- Y: Economy Class
- W: Premium Economy

Ex: F
AirlineRefund String Não 1 Indica se passagem é reembolsável, onde:

- Y: Yes
- N: No

Ex: N

Passengers

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
PassengerName String Sim 100 Nome do passageiro.

Ex: João da Silva
PassengerEmail String Sim 300 E-mail do passageiro.

Ex: jsilva@dominio.com
PassengerPhone String Sim 15 Telefone do passageiro.

Ex: 552133665591
Código do País(55) + Região (21) + Número(33665591)
PassengerBirthDate Date Sim 10 Data de nascimento do passageiro.

Formato: yyyy-MM-dd
Ex: 1958-12-22
PassengerRating String Não 10 Classificação etária do passageiro, onde:

- “Adult” (Adulto);
- “Child” (Criança);
- “Youth” (Adolescente);
- “Student” (Estudante);
- “SeniorCitizen” (Idoso);
- “Military” (Militar).

Ex: Adult
PassengerStatus String Não 10 Classificação do passageiro na cia aérea.

Ex: Gold, Platina ou outros.
PassengerNationality String Não 100 Nacionalidade do passageiro.

Ex: Brasil
PassengerDocuments Verificar Sim Nó que recebe os documentos do passageiro.

PassengerDocuments

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
Key String Não 14 Tipo do documento do passageiro.

- CPF
- RG
- Passport.

Ex: CPF
Value String Não 50 Número do documento do passageiro.
(Pode ser enviado com ou sem máscara)

Ex: 259.228.370-60 ou 25922837060 (CPF)
Ex: 65.935.950-9 ou 659359509 (RG)
Ex: CY4256890 (Passaporte)

LodgingData

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
LodgingName String Sim 100 Nome do local de hospedagem.

Ex: Pousada Porto e Mar
CheckInDate Date Sim 10 Data do CheckIn.

Formato: yyyy-MM-dd
Ex: 2019-04-06
CheckOutDate Date Sim 10 Data do CheckOut.

Formato: yyyy-MM-dd
Ex: 2019-04-13
Duration Integer Sim 5 Duração da hospedagem em noites.

Ex: 7
LodgingRefund String Sim 1 Indica se a hospedagem é reembolsável, onde:

- Y: Yes
- N: No

Ex: N
LodgingAddress Verificar Sim Nó que recebe o endereço do local de hospedagem.
Lodgers Verificar Sim Nó que recebe as informações dos hóspedes.

LodgingAddress

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
ZipCode String Sim 10 CEP da hospedagem.

Ex: 55590-000
Street String Sim 100 Endereço da hospedagem.

Ex: Rua da Posteação
Number String Sim 10 Número do endereço da hospedagem.

Ex: s/n
Complement String Não 300 Complemento do endereço da hospedagem.

Ex: s/complemento
District String Sim 100 Bairro da hospedagem.

Ex: Praça 13
City String Sim 100 Cidade da hospedagem.

Ex: Porto de Galinhas
State String Sim 2 Estado da hospedagem.

Formato: UF;
Ex: PE.
Country String Sim 100 País da hospedagem.

Ex: Brasil

Lodgers

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
LodgerName String Sim 100 Nome do hóspede.

Ex: João da Silva
LodgerEmail String Sim 300 E-mail do hóspede.

Ex: jsilva@dominio.com
LodgerPhone String Sim 15 Telefone do hóspede.

Ex: 552133665591
Código do País(55) + Região (21) + Número(33665591)
LodgerDocuments Verificar Sim Nó que recebe os documentos do hóspede.

LodgerDocuments

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
Key String Não 14 Tipo do documento do hóspede.

- CPF
- RG
- Passport.

Ex: CPF
Value String Não 50 Número do documento do hóspede.
(Pode ser enviado com ou sem máscara)

Ex: 259.228.370-60 ou 25922837060 (CPF)
Ex: 65.935.950-9 ou 659359509 (RG)
Ex: CY4256890 (Passaporte)

Retorno

Códigos e Mensagens de Retorno

Código Mensagem
200 Sua compra foi APROVADA! Obrigado por comprar com a Koin Pós-Pago.
300 Infelizmente sua compra não foi aprovada. Por favor, utilize outra forma de pagamento.
302 Infelizmente sua compra não foi aprovada. Por favor, utilize outra forma de pagamento.
304 Infelizmente sua compra não foi aprovada. Por favor, utilize outra forma de pagamento ou, para mais informações, entre em contato com o SAC Koin (sac@koin.com.br).
312 Seu pedido foi recebido pela Koin e encontra-se em análise. Por favor aguarde, pois em breve você receberá a atualização do status por e-mail.
500 Erro de processamento! Por favor, tente novamente ou entre em contato com a KOIN.
601 Erro no valor do pedido. Por favor, entre em contato com a loja.
602 Não encontramos nenhum produto no pedido. Por favor, entre em contato com a loja.
603 O número do pedido é inválido. Por favor, entre em contato com a loja.
701 Infelizmente sua compra não foi aprovada pois excede o seu limite de crédito com a KOIN. Para mais informações, entre em contato com o SAC Koin (sac@koin.com.br).
704 Infelizmente sua compra não foi aprovada. Para mais informações, entre em contato com o SAC Koin (sac@koin.com.br).
901
902
Pedido cancelado na KOIN.
12100 Pedido estornado na KOIN.
998 Pedido já processado pela KOIN. Para verificar o status do pedido, acesse sua conta em www.koin.com.br ou entre em contato com SAC Koin (sac@koin.com.br). (Nesses casos o pedido não deverá ser considerado "Reprovado", o correto é utilizar a API de Consulta de Status para verificar o status do primeiro pedido).
999 Requisição Inválida (Será apresentado o parâmetro incorreto).
10101 Identificamos que o CPF informado já encontra-se cadastrado na KOIN. Por favor, finalize o pedido utilizando os demais dados já cadastrados. Para mais informações, entre em contato com o SAC Koin (sac@koin.com.br).
10103 Identificamos que o e-mail informado já encontram-se cadastrado na KOIN. Por favor, finalize o pedido utilizando os demais dados já cadastrados. Para mais informações, entre em contato com o SAC Koin (sac@koin.com.br).

Informações Retornadas

Parâmetro Tipo Descrição Exemplo
Code Integer Código retornado pela API 200
Message String Mensagem retornada pela API Sua compra foi APROVADA!
AdditionalInfo KeyValue Informações adicionais da resposta {
"Code":200,
"Message":"Sua compra foi APROVADA!",
"AdditionalInfo": [{ Aqui serão retornadas todas as informações enviadas no pedido}]
}

Exemplos

Exemplos de Requisição


/** API de Gerar Pedidos - Exemplo de requisição em PHP **/
	
    $transmitObject = array(
    'FraudId' => "dkf348lcu20ecvf8013gfckdksmd",
    'Reference' => 123456789,
    'Currency' => 'BRL',
    'Price' => 2999.99,
    'PaymentType' => 21,
    'DiscountPercent' => 0,
    'DiscountValue' => 0,
    'IncreasePercent' => 0,
    'IncreaseValue' => 0,
    	
    //Definindo dados do Pagador.
    'Buyer' => array(	
        'Name' => 'Teste Koin',
        'Email' => 'teste@koin.com.br',
        'BuyerStatus' => 1,
    	'Ip' => '123.123.12.12',
        // Definindo Documentos do Pagador (CPF obrigatório).	
        'Documents' => array(
            array('Key' => 'CPF', 'Value' => '259.228.370-60'), 
        ),
    	
        // Definindo Data Nascimento do Pagador (Obrigatória).	
        'AdditionalInfo' => array(
            array('Key' => 'Birthday', 'Value' => '1959-04-02'), 
        ),  
    	
        // Definindo Telefones do Pagador (Obrigatório enviar ao menos um telefone).
        'Phones' => array(
            array('AreaCode' => '11', 'Number' => '2309-6020', 'PhoneType' => 3), 
            array('AreaCode' => '11', 'Number' => '91234-5678', 'PhoneType' => 4), 
        ),
    	
        // Definindo Endereço de cadastro (Apenas o 'Complement' não é obrigatório).
        'Address' => array(
            'ZipCode' => '01310-200',
            'Street' => 'Av. Paulista',
            'Number' => '1728',
            'Complement' => 'Casa',
            'District' => 'Bela Vista',
            'City' => 'Sao Paulo',
            'State' => 'SP',
            'Country' => 'Brasil',
            'AddressType' => 1
            )
        ),
    		
        // Definindo demais Dados Cadastrais do Pagador.
        'RegistrationData' => array(
            'Gender' => 1,
            'MaritalStatus' => 1,
            'PlaceOfBirth' => 'Marília',
            'StateOfBirth' => 'SP',
            'Nationality' => 'Brasil',
            'MothersName' => 'Maria Rita de Cássia',
            'DocumentType' => 1,
            'DocumentNumber' => '65269241027',
            'IssuanceAuthority' => 'Detran',
            'IssuanceAuthorityState' => 'SP',
            'IssuanceDate' => '2018-12-22',
            'MonthlyIncome' => 2954.99,
            'Occupation' => 'Administrador',
            'JobTitle' => 'Gerente Financeiro'
            )
        ),
    	
        // Definindo dados de Entrega e Frete (Apenas o 'Complement' não é obrigatório).
        'Shipping' => array(
            'Price' => 10.00,
            'DeliveryDate' => '2019-03-05 00:00:00',
            'Address' => array(
                'ZipCode' => '01310-200',
                'Street' => 'Av. Paulista',
                'Number' => '1728',
                'Complement' => 'Casa',
                'District' => 'Bela Vista',
                'City' => 'Sao Paulo',
                'State' => 'SP',
                'Country' => 'Brasil',
                'AddressType' => 1
            )	
        ),
    	
        // Definindo informações dos itens.	
        'Items' => array(
            array(
                'Reference' => 'Cod_Item_123456',
                'Description' => 'Descricao do produto 1',
                'Category' => 'Passagem',
                'Quantity' => 1,
                'Price' => 1999.99            
                ),
            array(
                'Reference' => 'Cod_Item_987654',
                'Description' => 'Descricao do produto 2',
                'Category' => 'Hospedagem',
                'Quantity' => 1,
                'Price' => 1000.00 					
                )   
    	),
        // Definindo Parâmetros Adicionais.
        'AdditionalParameters' => array(
            'PartnerId' => '10',
            'IntermediateId' => 'ABC123',
            'SalesChannelId' => 3,
            'ExpirationDate' => '2019-09-05 12:00:00'
        ),	
        // Definindo Informações Adicionais.
        'AdditionalData' => array(
            'AirlineData' => array(
                'Legs' => array(
                    array(
                        'LegNumber' => '1',
                        'Origin' => 'CGH',
                        'Destination' => 'REC',	
                        'FlightNumber' => '1063',	
                        'DepartureTime' => '2019-04-06 06:20:00',	
                        'StopOverAllowed' => 'N',
                        'IdClass' => 'Y',	
                        'AirlineRefund' => 'Y'
                    ),
                    array(
                        'LegNumber' => '2',
                        'Origin' => 'REC',
                        'Destination' => 'CGH',	
                        'FlightNumber' => '1600',	
                        'DepartureTime' => '2019-04-13 08:34:00',	
                        'StopOverAllowed' => 'N',
                        'IdClass' => 'Y',
                        'AirlineRefund' => 'N'
                    )
                ),		
                'Passengers' => array(
                    array(
                        'PassengerName' => 'Nome Completo do Passageiro 1',
                        'PassengerEmail' => 'passageiro1@dominio.com',	
                        'PassengerPhone' => '552133665591',	
                        'PassengerBirthDate' => '1958-12-22',	
                        'PassengerRating' => 'Adult',	
                        'PassengerStatus' => 'Gold',
                        'PassengerNationality' => 'Brasil',
                        'PassengerDocuments' => array(
                            array('Key' => 'CPF', 'Value' => '396.469.778-80')
                        )
                    ),
                    array(
                        'PassengerName' => 'Nome Completo do Passageiro 2',
                        'PassengerEmail' => 'passageiro2@dominio.com',	
                        'PassengerPhone' => '552133665592',	
                        'PassengerBirthDate' => '1988-11-17',	
                        'PassengerRating' => 'Adult',	
                        'PassengerStatus' => 'Gold',
                        'PassengerNationality' => 'Brasil',
                        'PassengerDocuments' => array(
                            array('Key' => 'RG', 'Value' => '65.935.950-9')
                        )
                    ),
                    array(
                        'PassengerName' => 'Nome Completo do Passageiro 3',
                        'PassengerEmail' => 'passageiro3@dominio.com',	
                        'PassengerPhone' => '552133665593',	
                        'PassengerBirthDate' => '2005/10/13',	
                        'PassengerRating' => 'Student',	
                        'PassengerStatus' => 'Platina',
                        'PassengerNationality' => 'Brasil',
                        'PassengerDocuments' => array(
                            array('Key' => 'Passport', 'Value' => 'CY4256890')
                        )
                    )						
                )
            ),
            'LodgingData' => array(
                'LodgingName' => 'Pousada Porto e Mar',
                'CheckInDate' => '2019-04-06',
                'CheckOutDate' => '2019-04-13',
                'Duration' => '7',
                'LodgingRefund' => 'N',
                'LodgingAddress' => array(
                    'ZipCode' => '55590-000',
                    'Street' => 'Rua da Posteação',
                    'Number' => 's/n',
                    'Complement' => '',
                    'District' => 'Praça 13',
                    'City' => 'Porto de Galinhas',
                    'State' => 'PE',
                    'Country' => 'Brasil',
                ),
                'Lodgers' => array(
                    array(
                        'LodgerName' => 'Nome do Hospede 1',
                        'LodgerEmail' => 'hospede1@dominio.com',
                        'LodgerPhone' => '552133665591',
                        'LodgerDocuments' => array(
                            array('Key' => 'CPF', 'Value' => '836.189.158-70')
                        )
                    ),
                    array(
                        'LodgerName' => 'Nome do Hospede 2',
                        'LodgerEmail' => 'hospede2@dominio.com',
                        'LodgerPhone' => '552133665592',
                        'LodgerDocuments' => array(
                            array('Key' => 'CPF', 'Value' => '490.582.504-07')
                        )
                    )
                )
            )
        )
    );

    //Criando um JSON
    $jsonObject = json_encode($transmitObject);
    
    //Definindo a URL de requisição
    $url = "http://api.qa.koin.in/V1/TransactionService.svc/Request";
    
    //Chaves de autenticação - Teste
    //Solicite suas chaves de teste para a Equipe de Integração (integracao@koin.com.br)
    $consumerKey = "1BFCF567A63E4B6FB38F6A22FFA21FFE";  
    $secretKey = "50856FDA556747A7860C3295C25FEA26";
    
    //convertendo o formato do timezone para UTC 
    date_default_timezone_set("UTC");
    
    //Obtendo a hora do servidor
    $time = time();
    
    //Criando o hash de autenticação
    $binaryHash = hash_hmac('sha512', $url.$time, $secretKey, true);
    
    //Convertendo para Base64
    $hash = base64_encode($binaryHash);
    
    //Enviando a requisição
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonObject);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-Type:application/json; 
    charset=utf-8", "Content-Length:".strlen($jsonObject), 
    "Authorization: {$consumerKey},{$hash},{$time}"));
	
    //Recebendo resposta
    try {
    	
    	$response = curl_exec($ch);
    	curl_close ($ch);
    	
    	echo $response;
    	
    } catch (Exception $e) {
      echo "Ocorreu um erro : ",  $e->getMessage(), "\n";
    }
	
?>

/** API de Geração de Pedidos - Exemplo de instrução JSON **/

{
	"FraudId": "cfbec22f99d2f557e1426821c42ed3dd",
	"Reference": "123456789",
	"Currency":"BRL",
	"Price":199.90,
	"DiscountPercent": 0,
	"DiscountValue": 0,
	"IncreasePercent": 0,
	"IncreaseValue": 0,
	"PaymentType":21,
	"Buyer":{
		"Name":"Nome do Pagador",
		"Email": "emailpagador@email.com",
		"Documents":[{"Key":"CPF","Value":"123.456.798-91"}],
		"AdditionalInfo":[{"Key":"Birthday","Value":"1958-12-22"}],
		"Phones":[{"AreaCode":"11", "Number":"2309-6020", "PhoneType":2},
			  {"AreaCode":"11", "Number":"91234-5678", "PhoneType":3}],
		"Address":{
			"City":"São Paulo",
			"State":"SP",
			"Country":"Brasil",
			"District":"Bela Vista",
			"Street":"Av. Paulista",
			"Number":1728,
			"Complement":"7 andar",
			"ZipCode":"01310-200",
			"AddressType":1
			}
		},
	"Shipping":{
		"Address":{
			"City":"São Paulo",
			"State":"SP",
			"Country":"Brasil",
			"District":"Bela Vista",
			"Street":"Av. Paulista",
			"Number":1728,
			"Complement":"7 andar",
			"ZipCode":"01310-200",
			"AddressType":1
			},
		"Price":10.00,
		"DeliveryDate":"2018-11-07 00:00:00"
		},
	"Items": [{
		"Reference":"Cod_Item_123456",
		"Description":"Camiseta Selecao Brasileira",
		"Category":"Vestuario",
		"Quantity":1,
		"Price":189.90,
		"Attributes":[{"Key":"Cor","Value":"Amarela"},
			      {"Key":"Tamanho","Value":"M"}]
	}],
	"AdditionalParameters":{
		"PartnerId":"001",
		"ExpirationDate":"2018-11-07 00:00:00",		
		"Passengers":[
			{
			"PassengerName":"Nome Completo do Passageiro 1",
			"PassengerNationality":"Brasil",
			"PassengerDocuments":[{"Key":"CPF", "Value":"396.469.778-80"}]		
			},
			{
			"PassengerName":"Nome Completo do Passageiro 2",
			"PassengerNationality":"Brasil",
			"PassengerDocuments":[{"Key":"RG", "Value":"65.935.950-9"}]		
			},			
			{
			"PassengerName":"Nome Completo do Passageiro 3",
			"PassengerNationality":"Alemanha",
			"PassengerDocuments":[{"Key":"CPF", "Value":"CY4256890"}]		
			}			
		]
	}	
}

Exemplo de Retorno

			
/** API de Gerar Pedidos - Exemplo de Retorno - JSON **/

{
	"Code": 200,
	"Message": "Sua compra foi APROVADA! Obrigado por comprar com Koin Pós-Pago",
	"AdditionalInfo": [	]
}

Consultar Crédito

A API de Consultar Crédito é um complemento da API de Gerar Pedidos, ambas devem trabalhar em conjunto no checkout das lojas integradas com o Koin Select para que os clientes com restrições na base KOIN, não consigam finalizar suas compras utilizando nossa opção de pagamento.

Requisição

Para consultar o limite do cliente, basta enviar um JSON através de uma requisição POST para a KOIN, informando o CPF e o e-mail, que o limite disponível será retornado.

Com esta API também é possível consultar as opções de parcelamento do pedido, para isso, basta enviar na requisição o valor total da compra que, além do limite disponível, será retornado as opções de parcelamento. Entretanto, recomendamos que, para esta finalidade, utilize o serviço de Consultar Parcelas conforme orientado em Como utilizar a KOIN.

ATENÇÃO
Caso utilize esta API para consultar as opções de parcelamento, sempre que houver uma alteração no valor total do pedido, uma nova consulta deve ser realizada para que os valores das parcelas sejam atualizados. Caso contrário, os valores de cobrança e repasse serão incorretos.
IMPORTANTE
Todas as APIs disponibilizadas pela Koin necessitam de Autenticação.

URL de Requisição

Ambiente de Testes (Case Sensitive):

Ambiente de Produção (Case Sensitive):

Parâmetros

Veja abaixo as obrigatoriedades e as descrição dos parâmetros aceitos pela API de Consultar Crédito:

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
Cpf String Sim 14 CPF do Pagador.
(Pode ser enviado com ou sem máscara)

Ex: 259.228.370-60 ou 25922837060
Email String Sim 256 E-mail do Pagador.

Ex: joao.silva@dominio.com
Price Decimal Não 9.2 Valor total do pedido.
(Soma do itens + valor do frete)

Importante: Sugerimos que para consultar as opções de parcelamento utilize o serviço de Consultar Parcelas.

Ex: 250.99 (Utilizar ponto para separar casa decimal)

Retorno

Códigos e Mensagens de Retorno

Código Mensagem
10100 Consulta realizada com sucesso.
300 Limite não encontrado.
500 Erro de Requisição. Existem campos obrigatórios não enviados e/ou com formato inválido. Verifique as informações adicionais para mais detalhes.

Informações Retornadas

Parâmetro Exemplo Descrição
Code 10100 Código retornado pela API
Message Consulta realizada com sucesso. Mensagem retornada pela API
CreditLimitAvailable 500.00 Limite disponível para o cliente
installmentOptions Veja abaixo os detalhes Nó que retornará todas as informações das parcelas

installmentOptions

Parâmetro Exemplo Descrição
iof 3.22 Valor total do IOF. (Inserir máscara: "R$")
cetAM 23.01 CET ao mês. (Inserir máscara: "% a.m")
installments 3 Quantidade de parcelas.
rates 11.90 Percentual de juros ao mês. (Inserir máscara: "% a.m")
description 3 x de R$207.87 Descrição da quantidade de parcelas.
originalValue 500.00 Valor original do pedido. (Inserir máscara: "R$")
firstDueDate 2017-08-10 Vencimento da primeira parcela.
orderValue 623.61 Valor total do pedido, somando os juros. (Inserir máscara: "R$")
installmentValue 207.87 Valor de cada parcela. (Inserir máscara: "R$")
paymentType 23 ID que deverá ser enviado no parâmetro PaymentType da
API de Gerar Pedidos, para identificar a opção de parcelamento
selecionada pelo cliente.

Exemplos

Exemplo de Requisição


/** API de Consultar Limite - Exemplo de requisição em PHP **/

   /*Capturando informações para requisição*/ 
    
   $Cpf = '259.228.370-60'; 
   $Email = 'e-mail@dominio.com';	
   
   /*Montando o objeto de requisição */
   $transmitObject = array(
   'Cpf' => $Cpf, //Número do CPF
   'Email' => $Email //E-mail do Pagador
   );
   	
   /*Montando o objeto JSON a partir do objeto de requisição criado($transmitObject)*/
   
   //Criando um JSON
   $jsonObject = json_encode($transmitObject);
   //Definindo a URL de requisição para o ambiente de teste
   $url = "http://api.qa.koin.in/V1/AccountService.svc/Search";
   
   //Chaves de autenticação - Teste
   //Solicite suas chaves de teste para a Equipe de Integração (integracao@koin.com.br)
   $consumerKey = "1BFCF567A63E4B6FB38F6A22FFA21FFE"; 
   $secretKey = "50856FDA556747A7860C3295C25FEA26";
   //convertendo o formato do timezone para UTC 
   date_default_timezone_set("UTC");
   
   //Obtendo a hora do servidor
   $time = time();
     
   //Criando o hash de autenticação
   $binaryHash = hash_hmac('sha512', $url.$time, $secretKey, true);
   
   //Convertendo para Base64
   $hash = base64_encode($binaryHash);
   
   //Enviando a requisição
   $ch = curl_init();
   curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
   curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
   curl_setopt($ch, CURLOPT_URL, $url);
   curl_setopt($ch, CURLOPT_POST, true);
   curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonObject);
   curl_setopt($ch, CURLOPT_HTTPHEADER, array( "Content-Type:application/json; charset=utf-8", 
   "Content-Length:".strlen($jsonObject), "Authorization: {$consumerKey},{$hash},{$time}"));
   
   //Recebendo resposta.
   try {
   	$response = curl_exec($ch);
   	curl_close ($ch);
   	echo $response;
       } 
   	
   catch (Exception $e) {echo "Exceção: ",  $e->getMessage(), "\n";}
	
?>

Exemplo de Retorno

			
/** API de Consultar Crédito - Exemplo de Retorno - Sem Parcelas **/
		
{
   "CreditLimitAvailable": 1000.0,
   "Message": "Consulta realizada com sucesso.",
   "Code": 10100
}
			
			
/** API de Consultar Crédito - Exemplo de Retorno - Com Parcelas **/
		
{
	"CreditLimitAvailable": 1000.00,
	"Message": "Consulta realizada com sucesso.",
	"installmentOptions": [{
		"iof": "0",
		"cetAM": "0",
		"installments": "1",
		"rates": "0",
		"description": "A Vista",
		"originalValue": "500.00",
		"firstDueDate": "2017-08-10",
		"orderValue": "500.00",
		"installmentValue": "500.00",
		"paymentType": "21"
	}, {
		"iof": "2.61",
		"cetAM": "21.06",
		"installments": "2",
		"rates": "11.90",
		"description": "2 x de R$295.28",
		"originalValue": "500.00",
		"firstDueDate": "2017-08-10",
		"orderValue": "590.56",
		"installmentValue": "295.28",
		"paymentType": "22"
	}, {
		"iof": "3.22",
		"cetAM": "21.06",
		"installments": "3",
		"rates": "11.90",
		"description": "3 x de R$207.87",
		"originalValue": "500.00",
		"firstDueDate": "2017-08-10",
		"orderValue": "623.61",
		"installmentValue": "207.87",
		"paymentType": "23"
	}, {
		"iof": "3.86",
		"cetAM": "21.06",
		"installments": "4",
		"rates": "11.90",
		"description": "4 x de R$164.46",
		"originalValue": "500.00",
		"firstDueDate": "2017-08-10",
		"orderValue": "657.84",
		"installmentValue": "164.46",
		"paymentType": "19"
	}, {
		"iof": "4.53",
		"cetAM": "21.06",
		"installments": "5",
		"rates": "11.90",
		"description": "5 x de R$138.65",
		"originalValue": "500.00",
		"firstDueDate": "2017-08-10",
		"orderValue": "693.25",
		"installmentValue": "138.65",
		"paymentType": "15"
	}],
	"Code": 10100
}

Consultar Parcelas

A API de Consultar Parcelas também é um complemento da API de Gerar Pedidos, ambas devem trabalhar em conjunto no checkout das lojas integradas com o Koin Select e com o Koin Full, pois é através dela que é realizada a consulta das opções de parcelamento de um determinado pedido.

Requisição

Para consultar as opções de parcelamento, no momento em que o cliente selecionar a KOIN, basta enviar um JSON através de uma requisição POST informando o valor total do pedido que, as opções de parcelamento e seus valores serão retornados.

ATENÇÃO
Sempre que houver uma alteração no valor total do pedido, uma nova consulta deve ser realizada para que os valores das parcelas sejam atualizados. Caso contrário, os valores de cobrança e repasse serão incorretos.
IMPORTANTE
Todas as APIs disponibilizadas pela Koin necessitam de Autenticação.

URL de Requisição

Ambiente de Testes (Case Sensitive):

Ambiente de Produção (Case Sensitive):

Parâmetros

Veja abaixo as obrigatoriedades e as descrição dos parâmetros aceitos pela API de Consultar Parcelas:

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
Price Decimal Sim 9.2 Valor total do pedido.
(Soma do itens + valor do frete)

Ex: 250.99 (Utilizar ponto para separar casa decimal)

Retorno

Códigos e Mensagens de Retorno

Código Mensagem
10100 Consulta realizada com sucesso.
500 Erro de Requisição. Existem campos obrigatórios não enviados e/ou com formato inválido. Verifique as informações adicionais para mais detalhes.

Informações Retornadas

Parâmetro Exemplo Descrição
Code 10100 Código retornado pela API
Message Consultado realizada com sucesso. Mensagem retornada pela API
isInstalment True Informa se o valor e ou loja estão aptos para o parcelamento
installmentOptions Veja abaixo os detalhes Nó que retornará todas as informações das parcelas

installmentOptions

Parâmetro Descrição Exemplo
iof 3.22 Valor total do IOF. (Inserir máscara: "R$")
cetAM 23.01 CET ao mês. (Inserir máscara: "% a.m")
installments 3 Quantidade de parcelas.
rates 11.90 Percentual de juros ao mês. (Inserir máscara: "% a.m")
description 3 x de R$207.87 Descrição da quantidade de parcelas.
originalValue 500.00 Valor original do pedido. (Inserir máscara: "R$")
firstDueDate 2017-08-10 Vencimento da primeira parcela.
orderValue 623.61 Valor total do pedido, somando os juros. (Inserir máscara: "R$")
installmentValue 207.87 Valor de cada parcela. (Inserir máscara: "R$")
paymentType 23 ID que deverá ser enviado no parâmetro PaymentType da
API de Gerar Pedidos, para identificar a opção de parcelamento
selecionada pelo cliente.

Exemplos

Exemplo de Requisição


/** API de Consultar Parcelas - Exemplo de requisição em PHP **/
 
   /*Capturando informações para requisição*/ 
      
   $Price = '500.00';	
   
   /*Montando o objeto de requisição */
   $transmitObject = array(
   'Price' => $Price //Valor total do Pedido (com frete)
   );
   	
   /*Montando o objeto JSON a partir do objeto de requisição criado($transmitObject)*/
   
   //Criando um JSON
   $jsonObject = json_encode($transmitObject);
   //Definindo a URL de requisição para o ambiente de teste
   $url = "http://api.qa.koin.in/V1/TransactionService.svc/request/installment";
   
   //Chaves de autenticação - Teste
   //Solicite suas chaves de teste para a Equipe de Integração (integracao@koin.com.br)
   $consumerKey = "1BFCF567A63E4B6FB38F6A22FFA21FFE"; 
   $secretKey = "50856FDA556747A7860C3295C25FEA26";
   //convertendo o formato do timezone para UTC 
   date_default_timezone_set("UTC");
   
   //Obtendo a hora do servidor
   $time = time();
     
   //Criando o hash de autenticação
   $binaryHash = hash_hmac('sha512', $url.$time, $secretKey, true);
   
   //Convertendo para Base64
   $hash = base64_encode($binaryHash);
   
   //Enviando a requisição
   $ch = curl_init();
   curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
   curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
   curl_setopt($ch, CURLOPT_URL, $url);
   curl_setopt($ch, CURLOPT_POST, true);
   curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonObject);
   curl_setopt($ch, CURLOPT_HTTPHEADER, array( "Content-Type:application/json; charset=utf-8", 
   "Content-Length:".strlen($jsonObject), "Authorization: {$consumerKey},{$hash},{$time}"));
   
   //Recebendo resposta.
   try {
   	$response = curl_exec($ch);
   	curl_close ($ch);
   	echo $response;
       } 
   	
   catch (Exception $e) {echo "Exceção: ",  $e->getMessage(), "\n";}
	
?>

Exemplo de Retorno

			
/** API de Consultar Parcelas - Exemplo de Retorno - JSON **/
		
{
   "Message": "Consultada realizada com sucesso",
   "installmentOptions": [{
   	"iof": "0",
   	"cetAM": "0",
   	"installments": "1",
   	"rates": "0",
   	"description": "A Vista",
   	"originalValue": "500.0",
   	"firstDueDate": "2017-08-10",
   	"orderValue": "500.0",
   	"installmentValue": "500.0",
   	"paymentType": "21"
   }, {
   	"iof": "2.61",
   	"cetAM": "21.06",
   	"installments": "2",
   	"rates": "11.9",
   	"description": "2 x de R$295.28",
   	"originalValue": "500.0",
   	"firstDueDate": "2017-08-10",
   	"orderValue": "590.56",
   	"installmentValue": "295.28",
   	"paymentType": "22"
   }, {
   	"iof": "3.22",
   	"cetAM": "21.06",
   	"installments": "3",
   	"rates": "11.9",
   	"description": "3 x de R$207.87",
   	"originalValue": "500.0",
   	"firstDueDate": "2017-08-10",
   	"orderValue": "623.61",
   	"installmentValue": "207.87",
   	"paymentType": "23"
   }, {
   	"iof": "3.86",
   	"cetAM": "21.06",
   	"installments": "4",
   	"rates": "11.9",
   	"description": "4 x de R$164.46",
   	"originalValue": "500.0",
   	"firstDueDate": "2017-08-10",
   	"orderValue": "657.84",
   	"installmentValue": "164.46",
   	"paymentType": "19"
   }, {
   	"iof": "4.53",
   	"cetAM": "21.06",
   	"installments": "5",
   	"rates": "11.9",
   	"description": "5 x de R$138.65",
   	"originalValue": "500.0",
   	"firstDueDate": "2017-08-10",
   	"orderValue": "693.25",
   	"installmentValue": "138.65",
   	"paymentType": "15"
   }],
   "Code": 10100,
   "isInstalment": true
}

Autorizar Parcelamento

A API de Autorizar Parcelamento é um complemento da API de Gerar Pedidos, ambas devem trabalhar em conjunto no checkout das lojas integradas com o Koin OTAs ou Koin Recovery.

Requisição

Para consultar a disponibilidade e as opções de parcelamento de um determinado cliente, basta enviar um JSON através de uma requisição POST para a KOIN, informando CPF, E-mail, Valor Total do Pedido e a Data da utilização do serviço que a disponibilidade e as opções de parcelamento serão retornadas.

ATENÇÃO
Sempre que houver uma alteração nas informações consultadas (CPF, E-mail, Valor Total ou Data da Utilização do Serviço), uma nova consulta deve ser realizada para verificar a disponibilidade e opções de parcelamento de acordo com as novas informações.
IMPORTANTE
Todas as APIs disponibilizadas pela Koin necessitam de Autenticação.

URL de Requisição

Ambiente de Testes (Case Sensitive):

Ambiente de Produção (Case Sensitive):

Parâmetros

Veja abaixo as obrigatoriedades e as descrição dos parâmetros aceitos pela API de Autorizar Parcelamento:

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
Cpf String Sim 14 CPF do Pagador.
(Pode ser enviado com ou sem máscara)

Ex: 259.228.370-60 ou 25922837060
Email String Sim 300 E-mail do Pagador.

Ex: joao.silva@dominio.com
TotalPrice Decimal Sim 9.2 Valor total do pedido.

Ex: 250.99 (Utilizar ponto para separar casa decimal)
UseDate Date Sim 10 Data da utilização do serviço.

- OTAs: enviar data da viagem ou a partir de qual data será possível viajar;
- E-commerces convencionais: enviar previsão de entrega do produto;

Formato: yyyy-MM-dd
Ex: 2020-12-22
Ip String Sim 50 Endereço de IP do Pagador.

Ex: 123.456.789.01
Optin Boolean Sim - Indica se cliente aceitou ou não os Termos de Uso da KOIN.

Ex: "true" ou "false"
SalesChannelId Integer Sim 2 Código do Canal de Vendas, sendo:

3 = Checkout;
5 = Recuperação Checkout;

MaxInstallments Integer Não - Máximo de parcelas a ser oferecida ao cliente.

Ex: 6
Recovery Verificar Sim ¹ - Nó que recebe informações adicionais para recuperação.

¹ = Obrigatório quando a Koin for utilizada no processo de recuperação.


Recovery

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
ReasonCode String Sim 5 Código retornado na negativa do cartão.

Ex: "51"
ReasonMessage String Sim 300 Mensagem retornada na negativa do cartão.

Ex: "Transação não autorizada. Limite excedido/sem saldo."

Retorno

Códigos e Mensagens de Retorno

Código Mensagem
12200 Autorizado.
12300 Não autorizado.
12400 Loja não autorizada a utilizar este serviço, favor entrar em contato com a KOIN.
12500 Erro no Processamento: [aqui será informado o erro]
12999 Erro na Requisição: [aqui será informado o erro]

Informações Retornadas

Parâmetro Exemplo Descrição
Code 12200 Código retornado pela API
Message Autorizado. Mensagem retornada pela API
CreditLimitAvailable 5000.00 Limite disponível para o cliente.

(API retornará "-1" caso a loja não esteja autorizada a receber essa informação)
amountInstallments 10 Quantidade máxima de parcelas
installmentOptions Veja abaixo os detalhes Opções de Parcelamento

installmentOptions

Parâmetro Exemplo Descrição
iof 3.22 Valor total do IOF. (Inserir máscara: "R$")
cetAM 23.01 CET ao mês. (Inserir máscara: "% a.m")
installments 3 Quantidade de parcelas.
rates 11.90 Percentual de juros ao mês. (Inserir máscara: "% a.m")
description 3 x de R$207.87 Descrição da quantidade de parcelas.
originalValue 500.00 Valor original do pedido. (Inserir máscara: "R$")
firstDueDate 2017-08-10 Vencimento da primeira parcela.
orderValue 623.61 Valor total do pedido, somando os juros. (Inserir máscara: "R$")
installmentValue 207.87 Valor de cada parcela. (Inserir máscara: "R$")
paymentType 23 ID que deverá ser enviado no parâmetro PaymentType da
API de Gerar Pedidos, para identificar a opção de parcelamento
selecionada pelo cliente.

Exemplos

Exemplo de Requisição


/** API de Autorizar Parcelamento - Exemplo de requisição em PHP **/
   
    /*Montando o objeto de requisição */ 
     
    $transmitObject = array(
    'Cpf' => '259.228.370-60', //Número do CPF
    'Email' => 'e-mail@dominio.com', //E-mail do Pagador
    'TotalPrice' => '500.99', // Valor Total do Pedido
    'UseDate' => '2020-12-22', // Data da utilização do serviço
    'Ip' => '123.456.79.00', //IP do Pagador
    'Optin' => 'True', //Indica se cliente aceitou ou não os Termos de Uso da KOIN
    'SalesChannelId' => '5', //Indica o canal de vendas do pedido 
    'Recovery' => array(
    	'ReasonCode' => '51',
    	'ReasonMessage' => 'Transação não autorizada. Limite excedido/sem saldo.'
    	)
    );
    	
    /*Montando o objeto JSON a partir do objeto de requisição criado($transmitObject)*/
    
    //Criando um JSON
    $jsonObject = json_encode($transmitObject);   
    //Definindo a URL de requisição para o ambiente de teste
    $url = "http://api.qa.koin.in/Transaction/authorization";
    
    //Chaves de autenticação - Teste
    //Solicite suas chaves de teste para a Equipe de Integração (integracao@koin.com.br)
    $consumerKey = "1BFCF567A63E4B6FB38F6A22FFA21FFE"; 
    $secretKey = "50856FDA556747A7860C3295C25FEA26";   
    //convertendo o formato do timezone para UTC 
    date_default_timezone_set("UTC");
    
    //Obtendo a hora do servidor
    $time = time();
      
    //Criando o hash de autenticação
    $binaryHash = hash_hmac('sha512', $url.$time, $secretKey, true);
    
    //Convertendo para Base64
    $hash = base64_encode($binaryHash);
    
    //Enviando a requisição
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonObject);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array( "Content-Type:application/json; charset=utf-8", 
    "Content-Length:".strlen($jsonObject), "Authorization: {$consumerKey},{$hash},{$time}"));
    
    //Recebendo resposta.
    try {
    	$response = curl_exec($ch);
    	curl_close ($ch);
    	echo $response;
        } 
    	
    catch (Exception $e) {echo "Exceção: ",  $e->getMessage(), "\n";}
   
?>

Exemplo de Retorno

			
/** API de Autorizar Parcelamento - Exemplo de Retorno **/
		
{
   "Code": 12200
   "Message": "Autorizado",
   "CreditLimitAvailable": 5000.00,
   "amountInstallments": 5,
   "installmentOptions": [{
   	"iof": "0",
   	"cetAM": "0",
   	"installments": "1",
   	"rates": "0",
   	"description": "A Vista",
   	"originalValue": "500.00",
   	"firstDueDate": "2017-08-10",
   	"orderValue": "500.00",
   	"installmentValue": "500.00",
   	"paymentType": "21"
   }, {
   	"iof": "2.61",
   	"cetAM": "21.06",
   	"installments": "2",
   	"rates": "11.90",
   	"description": "2 x de R$295.28",
   	"originalValue": "500.00",
   	"firstDueDate": "2017-08-10",
   	"orderValue": "590.56",
   	"installmentValue": "295.28",
   	"paymentType": "22"
   }, {
   	"iof": "3.22",
   	"cetAM": "21.06",
   	"installments": "3",
   	"rates": "11.90",
   	"description": "3 x de R$207.87",
   	"originalValue": "500.00",
   	"firstDueDate": "2017-08-10",
   	"orderValue": "623.61",
   	"installmentValue": "207.87",
   	"paymentType": "23"
   }, {
   	"iof": "3.86",
   	"cetAM": "21.06",
   	"installments": "4",
   	"rates": "11.90",
   	"description": "4 x de R$164.46",
   	"originalValue": "500.00",
   	"firstDueDate": "2017-08-10",
   	"orderValue": "657.84",
   	"installmentValue": "164.46",
   	"paymentType": "19"
   }, {
   	"iof": "4.53",
   	"cetAM": "21.06",
   	"installments": "5",
   	"rates": "11.90",
   	"description": "5 x de R$138.65",
   	"originalValue": "500.00",
   	"firstDueDate": "2017-08-10",
   	"orderValue": "693.25",
   	"installmentValue": "138.65",
   	"paymentType": "15"
   }],
}
			
			
/** API de Autorizar Parcelamento - Exemplo de Retorno - Sem Crédito **/
		
{
   "Code": 12300,
   "Message": "Não autorizado",
   "CreditLimitAvailable": -1, //Loja não autorizada a receber o limite do cliente
   "amountInstallments": 0,
   "installmentOptions":[]
}

Consultar Status

Com a API de Consultar Status é possível acompanhar diretamente da área administrativa da Loja se o pedido foi Aprovado, Reprovado ou está Em Análise, automatizando a verificação e evitando que a mesma tenha que ser realizada manualmente na Conta Koin do Lojista.

Dica: Como a Koin não aceita pedidos repetidos, uma forma de evitá-los é sempre verificar se a Loja já não enviou o número do pedido da requisição anteriormente para a KOIN, ou seja:

  • Antes de enviar a requisição, utilize a API de Consultar Status para verificar se a Loja já não enviou esse número de pedido anteriormente;
  • Se a loja já tiver enviado o número de pedido para KOIN, basta gerar um novo número para o pedido e realizar a requisição;
  • Senão, basta enviar a requisição normalmente.
  • Requisição

    Para consultar o status de um pedido na KOIN, deve-se enviar o número do pedido através de um POST no formato JSON, ou seja, basta verificar os parâmetros que devem ser enviados, em Parâmetros, alimentar o objeto JSON com essas informações e enviar a requisição.

    IMPORTANTE
    Todas as APIs disponibilizadas pela Koin necessitam de Autenticação.

    URL de Requisição

    Ambiente de Testes (Case Sensitive):

    Ambiente de Produção (Case Sensitive):

    Parâmetros

    Veja abaixo as obrigatoriedades e as descrição dos parâmetros aceitos pela API de Consultar Status:

    Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
    Reference String Sim 300 Número do pedido a ser consultado.

    Ex: 27738

    Retorno

    Códigos e Status de Retorno

    Veja abaixo os códigos, status e descrições dos retornos dados pela API de Consultar Status:

    Código Status Descrição
    200 Aprovado O pedido foi aprovado pela Koin e a Loja está autorizada a enviar o produto.
    312 Pendente O pedido está sendo analisado pela KOIN, consulte seu status em breve.
    512 - Número do pedido não encontrado na KOIN.
    Demais códigos Reprovado O pedido foi reprovado pela KOIN.
    Dica: Para verificar todos os códigos de retorno acesse: Códigos e Mensagens de Retorno da API de Gerar Pedidos.

    Informações Retornadas

    Parâmetro Tipo Descrição Exemplo
    Status String Status do pedido retornado pela API Aprovado
    Code Int Código da mensagem retornado pela API 200
    Message String Mensagem retornada pela API Sua compra foi APROVADA! Obrigado por comprar com a Koin Pós-Pago.
    RequestDate DateTime Data em que o pedido foi gerado 2014-08-06 12:14:44
    AdditionalInfo Alpha Informações Adicionais
    Reference String Número do pedido consultado
    11919

    Exemplos

    Exemplo de Requisição

    
    /** API de Consulta de Status - Exemplo de requisição em PHP **/
     
       /*Capturando informações para requisição*/ 
       $Reference = '27738'; //Número do Pedido 
       	
       /*Montando o objeto de requisição*/
       $transmitObject = array('Reference' => $Reference);
       		
       /*Montando o objeto JSON a partir do objeto de requisição criado($transmitObject)*/
       	
       //Criando um JSON
       $jsonObject = json_encode($transmitObject);
       		
       //Definindo a URL de requisição para o ambiente de teste
       $url = "http://api-rest.qa.koin.in/Transaction/status";
       		
       //Chaves de autenticação - Teste
       //Solicite suas chaves de teste para a Equipe de Integração (integracao@koin.com.br)
       $consumerKey = "1BFCF567A63E4B6FB38F6A22FFA21FFE"; 
       $secretKey = "50856FDA556747A7860C3295C25FEA26";
       		
       //convertendo o formato de hora para UTC 
       date_default_timezone_set("UTC");
       		
       //Obtendo a hora do servidor
       $time = time();
           
       //Criando o hash de autenticação
       $binaryHash = hash_hmac('sha512', $url.$time, $secretKey, true);
       	
       //Convertendo para Base64
       $hash = base64_encode($binaryHash);
       	
       //Enviando a requisição
       $ch = curl_init();
       curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
       curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
       curl_setopt($ch, CURLOPT_URL, $url);
       curl_setopt($ch, CURLOPT_POST, true);
       curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonObject);
       curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-Type:application/json; 
       charset=utf-8", "Content-Length:".strlen($jsonObject), 
       "Authorization: {$consumerKey},{$hash},{$time}"));
       	
       //Recebendo resposta
       try {
       	$response = curl_exec($ch);
       	curl_close ($ch);
       	echo $response;
           } 
       catch (Exception $e) {echo "Exceção: ",  $e->getMessage(), "\n";}
       
       print $jsonObject;
    	
    ?>
    
    

    Exemplo de Retorno

    			
    /** API de Consultar Status - Exemplo de Retorno - JSON **/
    		
    {
       "Status":"Aprovado",
       "Code":200,
       "Message":"Sua compra foi APROVADA! Obrigado por comprar com Koin Pós-Pago.",
       "RequestDate":"2014-08-06 12:14:44",
       "AdditionalInfo": null,
       "Reference":"11919",
    }
    
    

    Informar Rastreio

    Parte do processo transacional da Koin está diretamente ligado à entrega do produto e a API de Informar Rastreio foi desenvolvida para otimizar o processo de pós-venda, sua integração não é obrigatória, porém, é recomendada pois automatiza o envio das informações de rastreio para a KOIN.

    Essas informações são utilizadas para acompanhar a entrega do pedido, pois a Koin somente realizará a cobrança quando certificar-se que o cliente já se encontra com o produto em mãos.

    ATENÇÃO
    As informações de rastreio serão solicitadas por outro meio caso não sejam enviadas através deste serviço, porém, este será um processo manual que levará tempo e, nesse período, a Koin bloqueará o repasse do valor para a loja até que a entrega do pedido seja confirmada.

    Requisição

    As informações de rastreio de um pedido, devem ser enviadas para Koin através de um POST no formato JSON, ou seja, basta verificar os parâmetros que devem ser enviados, em Parâmetros, alimentar o objeto JSON com essas informações e enviar a requisição.

    IMPORTANTE
    Todas as APIs disponibilizadas pela Koin necessitam de Autenticação.

    URL de Requisição

    Ambiente de Testes (Case Sensitive):

    Ambiente de Produção (Case Sensitive):

    Parâmetros

    Veja abaixo as obrigatoriedades e as descrição dos parâmetros aceitos pela API de Informar Rastreio:

    Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
    Reference String Sim 300 Número do pedido.

    Ex: 10049.
    TrackingCode String Sim 100 Código de rastreio do pedido.

    Ex: ABCDE12345BR
    CarrierCompany String Sim 300 Nome da transportadora.

    Ex: Correios
    EventStatus String Não 300 Status de envio do pedido

    Ex: Entregue
    ShippingNumber String Não 3 Número da remessa.

    Deverá ser informado para os pedidos que possuem mais de uma entrega.

    Ex: 001
    InvoiceKey String Não 44 Chave da NF-e da mercadoria.

    Ex: 331310115138720001705500100000737411945
    74169
    InvoiceValue Decimal Não 9.2 Valor da NF-e da mercadoria.

    Ex: 355.00
    AdditionalInfo String Não 200 Informações adicionais do pedido

    Ex: Problemas de logistíca poderão atrasar a entrega.
    EventDatetime DateTime Não Data e hora que o produto foi encaminhado.

    Formato: yyyy-MM-dd HH:mm:ss
    Ex: 2015-10-02 22:30:55

    Retorno

    Códigos e Mensagens de Retorno

    Código Mensagem
    11104 Erro de Requisição: Campos obrigatórios não enviados ou com formato inválido.
    13000 Processamento realizado com sucesso.
    13101 Erro de Requisição. Número do pedido inválido ou operação cancelada.

    Informações Retornadas

    Parâmetro Tipo Descrição Exemplo
    Code Int Código retornado pela API 13000
    Message String Mensagem retornada pela API Processamento realizado com sucesso.
    AdditionalInfo KeyValue Limite disponível do cliente {
    "Code":13000,
    "Message":"Processamento realizado com sucesso.",
    "AdditionalInfo": [{ Aqui serão retornadas todas as informações enviadas na requisição}]
    }

    Exemplos

    Exemplo de Requisição

    
    /** API de Informar Rastreio - Exemplo de requisição em PHP **/
    
       //Capturando informações para requisição    
       $Reference = '27738'; //Número do Pedido (obrigatório*)
       $EventDatetime = '2015-10-02 22:30:55'; //Data e hora que o produto foi encaminhado
       $EventStatus = 'Postado'; //Status de envio do pedido
       $ShippingNumber = '001'; //Número da remessa
       $InvoiceKey = ''; //Chave da NF-e da mercadoria
       $InvoiceValue = 355.00; //Valor da NF-e da mercadoria
       $CarrierCompany = 'Correios'; //Nome da transportadora (obrigatório*)
       $TrackingCode = 'ABCDE12345BR'; //Código de rastreio do pedido (obrigatório*)
       $AdditionalInfo = 'Problemas de logistíca poderão atrasar a entrega'; //Informações adicionais    
       /*Montando o objeto de requisição */
       
       $transmitObject = array(
       'Reference' => $Reference, 
       'EventDatetime' => $EventDatetime,
       'EventStatus' => $EventStatus,
       'ShippingNumber' => $ShippingNumber,
       'InvoiceKey' => $InvoiceKey,
       'InvoiceValue' => $InvoiceValue,
       'CarrierCompany' => $CarrierCompany,
       'TrackingCode' => $TrackingCode,
       'AdditionalInfo' => $AdditionalInfo
       );    
       /*Montando o objeto JSON a partir do objeto de requisição criado($transmitObject)*/
       
       error_reporting( E_ALL );
       ini_set('display_errors', true);
       $jsonObject = json_encode($transmitObject);
       echo json_last_error();    
       //Definindo a URL de requisição para o ambiente de teste	
       $url = "http://api-rest.qa.koin.in/Transaction/delivery";    
       //Chaves de autenticação - Testes
       //Solicite suas chaves de teste para a Equipe de Integração (integracao@koin.com.br)
       $consumerKey = "1BFCF567A63E4B6FB38F6A22FFA21FFE"; 
       $secretKey = "50856FDA556747A7860C3295C25FEA26";    
       //convertendo o formato do timezone para UTC 
       date_default_timezone_set("UTC");
       
       //Obtendo a hora do servidor
       $time = time();
         
       //Criando o hash de autenticação
       $binaryHash = hash_hmac('sha512', $url.$time, $secretKey, true);
       
       //Convertendo para Base64
       $hash = base64_encode($binaryHash);
       
       //Enviando a requisição
       $ch = curl_init();
       curl_setopt($ch, CURLOPT_HEADER, true);
       curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
       curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
       curl_setopt($ch, CURLOPT_URL, $url);
       curl_setopt($ch, CURLOPT_POST, true);
       curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonObject);
       curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-Type:application/json; 
       charset=utf-8", "Content-Length:".strlen($jsonObject), 
       "Authorization: {$consumerKey},{$hash},{$time}"));    
       //Recebendo resposta
       try {
       	$response = curl_exec($ch);
       	curl_close ($ch);
       	//echo $response;
       	var_dump($response);
           } 
       catch (Exception $e) {echo "Exceção: ",  $e->getMessage(), "\n";}
       
       print $jsonObject;
     
    ?>
    
    

    Exemplo de Retorno

    			
    /** API de Informar Rastreio - Exemplo de Retorno - JSON **/
    	  
    {
       "Code": 13100,
       "Message": "Processamento realizado com sucesso",
       "AdditionalInfo": []
    }
    
    

    Cancelar Pedidos

    A API de Cancelar Pedidos foi desenvolvida para automatizar o processo de Cancelamento Total ou Parcial de um pedido realizado com a Koin.

    Com este serviço integrado, a Loja poderá realizar o cancelamento de um pedido diretamente em seu sistema que ele sera automaticamente cancelado no sistema da Koin. Evitando assim a necessidade de acessar a o Portal da Koin para realizar o cancelamento do pedido.

    Requisição

    As informações para o cancelamento de um pedido devem ser enviadas para Koin através de um POST no formato JSON, ou seja, basta verificar os parâmetros que devem ser enviados, em Parâmetros, alimentar o objeto JSON com essas informações e enviar a requisição.

    IMPORTANTE
    Todas as APIs disponibilizadas pela Koin necessitam de Autenticação.

    URL de Requisição

    Ambiente de Testes (Case Sensitive):

    Ambiente de Produção (Case Sensitive):

    Parâmetros

    Veja abaixo as obrigatoriedades e a descrição dos parâmetros aceitos pela API de Cancelar Pedidos:

    Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
    Reference String Sim 100 Número do pedido que será cancelado.

    Ex: #ABC123
    Type Integer Sim 1 Tipo de Cancelamento.

    1 = Cancelamento Total
    2 = Cancelamento Parcial
    Value Decimal Sim* 9.2 Valor a ser cancelado.

    Ex: Para Cancelamento Total: null
    Para Cancelamento Parcial: 51.99
    AdditionalInfo String Sim 255 Motivo do Cancelamento.

    Ex: Comprador desistiu da compra.
    User String Sim 300 Nome ou e-mail do usuário que está
    realizando o cancelamento.

    Ex: José da Silva
    ou
    jose.silva@dominio.com.br
    BankData Verificar Não Nó que recebe os Dados Bancários do Comprador.

    BankData

    Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
    BankCode String Não 10 Código do Banco.

    Ex: 001.
    BankName String Não 100 Nome do Banco.

    Ex: Banco do Brasil.
    Agency String Não 50 Número da Agência Bancária.

    Ex: 1234-5.
    Account String Não 50 Número da Conta Bancária.

    Ex: 678901-2.
    AccountType Integer Não 1 Tipo da Conta Bancária, sendo:

    1 = Conta Corrente;
    2 = Conta Poupança.

    Retorno

    Códigos e Mensagens de Retorno

    Código Mensagem
    12100 Processamento realizado com sucesso. Pedido Cancelado.
    12101 Erro de Requisição. Número do pedido inválido.
    12103 Erro de Requisição. O pedido já está cancelado.
    12106 Erro de Requisição. Existem campos obrigatórios não enviados e/ou com formato inválido. Verifique as informações adicionais para mais detalhes.

    Informações Retornadas

    Parâmetro Tipo Descrição Exemplo
    Code Int Código retornado pela API 12100
    Message String Mensagem retornada pela API Processamento realizado com sucesso. Pedido Cancelado.
    AdditionalInfo Alpha Informações adicionais
    - Número do pedido
    - Tipo de Cancelamento
    - Valor
    - Motivo do Cancelamento
    {
    "Reference":"#ABC123",
    "Type":2
    "Value":50.00
    "AdditionalInfo":"Comprador desistiu da compra"
    }

    Exemplos

    Exemplo de Requisição

    
    /** API de Cancelar Pedidos - Exemplo de requisição em PHP **/
     
       /*Montando o objeto de requisição */   
       $transmitObject = array(
       'Reference' => '#ABC123', //Número do Pedido
       'Type' => 2, //Tipo de Cancelamento: 1 = Total / 2 = Parcial
       'Value' => 50.00, //Valor a ser deduzido do pedido (Obrigatório apenas quando Type = 2)
       'AdditionalInfo' => 'Comprador desistiu da compra', //Motivo do Cancelamento
       'User' => 'jose.silva@dominio.com.br', //Usuário que está realizando o cancelamento
       'BankData' => array(
       	'BankCode' => '001',
       	'BankName' => 'Banco do Brasil',
       	'Agency' => '1234-5',
       	'Account' => '678901-2',
       	'AccountType' => 1
       	)
       );
       	
       /*Montando o objeto JSON a partir do objeto de requisição criado($transmitObject)*/
       
       //Criando um JSON
       $jsonObject = json_encode($transmitObject);   
       //Definindo a URL de requisição para o ambiente de teste
       $url = "http://api-rest.qa.koin.in/Transaction/reverse";
       
       //Chaves de autenticação - Teste
       //Solicite suas chaves de teste para a Equipe de Integração (integracao@koin.com.br)
       $consumerKey = "1BFCF567A63E4B6FB38F6A22FFA21FFE"; 
       $secretKey = "50856FDA556747A7860C3295C25FEA26";   
       //convertendo o formato do timezone para UTC 
       date_default_timezone_set("UTC");
       
       //Obtendo a hora do servidor
       $time = time();
         
       //Criando o hash de autenticação
       $binaryHash = hash_hmac('sha512', $url.$time, $secretKey, true);
       
       //Convertendo para Base64
       $hash = base64_encode($binaryHash);
       
       //Enviando a requisição
       $ch = curl_init();
       curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
       curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
       curl_setopt($ch, CURLOPT_URL, $url);
       curl_setopt($ch, CURLOPT_POST, true);
       curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonObject);
       curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-Type:application/json; 
       charset=utf-8",  "Content-Length:".strlen($jsonObject), 
       "Authorization: {$consumerKey},{$hash},{$time}"));
       
       //Recebendo resposta.
       try {
       	$response = curl_exec($ch);
       	curl_close ($ch);
       	//echo $response;
       	var_dump($response);
           } 
       catch (Exception $e) {echo "Exceção: ",  $e->getMessage(), "\n";}
       
       print $jsonObject;
    	
    ?>
    
    

    Exemplo de Retorno

    			
    /** API de Cancelamento - Exemplo de retorno - JSON **/
    		
    {
       "Code":12100,
       "Message":"Processamento realizado com sucesso. Pedido Estornado.",
       "AdditionalInfo": ["Reference":"#ABC123",
       		   "AdditionalInfo": "Comprador desistiu da compra"
       		  ]
    }