PT   EN

KOIN Checkout Flex

O Checkout Flex é a forma mais simples de integrar a KOIN em sua loja e começar a oferecer aos seus clientes a experiência do Pós-Pago e a oportunidade de parcelar suas compras no Boleto.

Para seu cliente, o Checkout Flex será apresentado como uma página intermediária, onde ele será pré-analisado e, quando aprovado, poderá escolher a melhor opção de parcelamento para sua compra. Quando necessário, também será possível solicitar os dados exigidos pela KOIN para finalizar um pedido, caso eles não sejam solicitados em sua loja (Endereço, Telefone e outros).

Como Funciona?
Veja abaixo como será o fluxo de compra utilizando o Checkout Flex:

  1. No checkout de sua loja, a KOIN será apresentada junto aos demais meios de pagamento;
  2. Quando selecionar a KOIN, o cliente visualizará uma breve descrição, os Termos de Uso e um botão para prosseguir (Não se preocupe com o conteúdo pois ele será gerado pelo nosso Snippet);
  3. Após aceitar os Termos de Uso e prosseguir com o pedido, realizaremos uma pré-análise do cliente e:
    • Quando reprovado, uma mensagem sugerindo que ele finalize a compra com outro meio de pagamento será apresentada;
    • Quando aprovado, o Checkout Flex será exibido dentro do checkout de sua própria loja;
  4. No Checkout Flex o cliente poderá escolher o parcelamento de sua compra e, quando necessário, preencher os dados exigidos pela KOIN que não são capturados em sua loja;
  5. Após preencher os dados e escolher a opção de parcelamento, o cliente retornará para o checkout de sua loja onde poderá finalizar o pedido;

Integrando o Checkout Flex
Veja abaixo o processo para a integração do Checkout Flex:

  1. No checkout de sua loja, disponibilize um espaço no HTML e insira nele apenas o elemento com o Snippet da KOIN;
  2. <div id="KoinTargetSnippet"></div>

  3. Para que o Snippet seja aberto, é necessário fornecer alguns dados e informar se o Checkout Flex deverá ou não solicitar ao cliente os dados exigidos para finalizar um pedido na KOIN (Endereço, Telefone e outros).

    O exemplo abaixo é a forma mais simples de integrar o Checkout Flex, basta copiá-lo para o HTML de sua loja e configurar os parâmetros de acordo com as informações de seu checkout:

  4. <form style="display: none;">
       <script src="https://resources.koin.com.br/scripts/checkoutintegration/scripts/koin_iframe.js" 
    	 id="koinCheckoutScript"
    	 data-token="1BFCF567A63E4B6FB38F6A22FFA21FFE"
    	 data-buyer-name="João da Silva"
    	 data-buyer-document-type="CPF" 
    	 data-buyer-document-value="259.228.370-60" 
    	 data-buyer-email="emailpagador@email.com"
    	 data-total-price="1500.00"		
    	 data-use-date="2018-08-17"
    	 data-hide-phone="true"
    	 data-hide-address="true">
       </script>
    </form>
    
    Caso as informações exigidas para finalizar um pedido na KOIN já sejam capturadas em sua loja, configure os parâmetros data-hide-phone e data-hide-address=true e, assim que o cliente finalizar o pedido, envie essas informações para a KOIN através do serviço de Finalizar Pedidos.

    Veja abaixo os possíveis cenários para abertura do Checkout Flex:

    • Loja possui o endereço do pagador mas não possui o telefone: data-hide-address=true, neste cenário o Checkout Flex irá solicitar apenas o telefone do pagador e exibir as opções de parcelamento;
    • Loja possui o telefone do pagador mas não possui o endereço: data-hide-phone=true, neste cenário o Checkout Flex irá solicitar apenas o endereço do pagador e exibir as opções de parcelamento;
    • Loja possui o endereço e o telefone do pagador: data-hide-phone e data-hide-address=true, neste cenário o Checkout Flex irá exibir apenas as opções de parcelamento;
    • Loja não possui os dados do pagador: Basta não inserir os parâmentros no formulário que o Checkout Flex ira solicitar todos os dados necessários e exibir as opções de parcelamento (Verifique todos os dados exigidos pela KOIN no serviço de Finalizar Pedidos );

    Após o cliente preencher os dados e escolher a opção de parcelamento, o Checkout Flex encaminha as informações diretamente para o nosso sistema que, por sua vez, retornará um TOKEN para identificação do pré-pedido, denominado KoinPreOrderToken;

    ATENÇÃO
    Sempre que houver uma alteração nas informações do Snippet (Nome, CPF, E-mail, Valor Total ou Data da Utilização), os parâmetros deverão ser atualizados para que uma nova análise seja realizada. Caso contrário, será apresentado um erro ao finalizar o pedido.

  5. Disponibilize no checkout de sua loja um input com o id KoinPreOrderToken, para que o Checkout Flex armazene o TOKEN retornado pela KOIN. Veja o exemplo:
  6. <input type="hidden" id="KoinPreOrderToken">

  7. Assim que o cliente finalizar a compra em sua loja, basta enviar as informações do pedido e o KoinPreOrderToken para a KOIN através do serviço de Finalizar Pedidos.
  8. Os pedidos finalizados com KOIN podem ser automaticamente Aprovados, Reprovados ou serem enviados para Análise Manual e, para os pedidos Em Análise, deve-se criar uma rotina que consulta e atualiza o status desses pedidos até que eles sejam Aprovados ou Reprovados. Para isso, basta utilizar o serviço de Consultar Status;

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ória 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}"));
	

Finalizar Pedidos

Conforme descrito em Integrando o Checkout, toda compra iniciada através do Checkout Flex gera um TOKEN de identificação em nosso sistema (KoinPreOrderToken).

Quando o cliente finalizar a compra, é através da API de Finalizar Pedidos que o KoinPreOrderToken e as demais informações do pedido deverão ser enviadas para KOIN.

Requisição

Para finalizar um pedido iniciado através do Checkout Flex, a loja deverá enviar o KoinPreOrderToken e as demais informações do pedido 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):

Parâmetros

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

Transaction

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
KoinPreOrderToken String Sim 300 TOKEN do pré-pedido retornado pelo Checkout Flex.

Ex: ABC12345
OrderID 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"
TotalPrice 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
Buyer Verificar Sim Nó que recebe as informações do Pagador.
Shipping Verificar Sim Nó que recebe as informações 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.

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
BirthDate Date Sim 10 Data de nascimento do pagador.

Formato: yyyy-MM-dd
Ex: 1958-12-22
Documents Verificar Sim Nó que recebe os documentos do pagador.
Phones Verificar Sim** Nó que recebe o telefone de contato do pagador.

** Obrigatório somente quando o Checkout Flex não capturar o telefone de contato do pagador ( data-hide-phone=true).

Importante: Quando o telefone for capturado pelo Checkout Flex este nó deverá ser removido da requisição.
Address Verificar Sim** Nó que recebe o endereço de cadastro do pagador.

** Obrigatório somente quando o Checkout Flex não capturar os dados de endereço do pagador ( data-hide-address=true).

Importante: Quando o endereço for capturado pelo Checkout Flex este nó deverá ser removido da requisição.

Documents

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

- Ao menos o CPF precisa ser enviado.

Ex: CPF
Number 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 clientes.

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
Type Integer Sim 1 Tipo do telefone de contato, sendo:

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

IMPORTANTE: O telefone de contato do pagador será exigido somente quando não for capturado pelo Checkout Flex (data-hide-phone=true).

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
Type Integer Sim 1 Tipo do endereço, sendo:

1 = Residencial;
2 = Comercial.
IMPORTANTE: O endereço do pagador será exigido somente quando não for capturado pelo Checkout Flex (data-hide-address=true).

Shipping

Parâmetros Tipo Obrig. Tamanho Descrição e Exemplo
Address Verificar Não** Nó que recebe o endereço de entrega do pedido.

** Obrigatório somente quando o endereço de entrega for diferente do endereço de cadastro.

Importante: Quando o endereço de entrega for igual ao de cadastro ou quando não houver endereço de entrega este nó deverá ser removido da requisição.
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: 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 Não Data e hora de expiração da oferta.

- OTAs: enviar data e hora que a reserva irá expirar para que a KOIN não aprove um pedido após o prazo;

Formato: yyyy-MM-dd HH:mm:ss
Ex: 2018-10-02 22:30:55
Passengers Verificar Não Nó que recebe as informações dos passageiros.

Passengers

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

Ex: João da Silva
PassengerNationality String Não 100 Nacionalidade do passageiro.

Ex: Brasil
PassengerDocuments Verificar Não Nó que recebe os documentos dos passageiros.

PassengerDocuments

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

- CPF
- RG
- Passport.

Ex: CPF
Number 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)

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 Exemplo Descrição
Code 200 Código retornado pela API
Message Pedido APROVADO! Mensagem retornada pela API
AdditionalInfo Resumo do pedido Nó que retornará o resumo do pedido
installmentOptions Veja os detalhes abaixo Nó que retornará a opção de parcelamento selecionada pelo cliente

installmentOptions

Parâmetro Exemplo Descrição
iof 4.53 Valor total do IOF. (Inserir máscara: "R$")
cetAM 21.06 CET ao mês. (Inserir máscara: "% a.m")
installments 5 Quantidade de parcelas.
rates 1.89 Percentual de juros ao mês. (Inserir máscara: "% a.m")
description 5 x de R$104.74 Descrição da quantidade de parcelas.
originalValue 500.00 Valor original do pedido. (Inserir máscara: "R$")
firstDueDate 2018-08-17 Vencimento da primeira parcela.
orderValue 523.70 Valor total do pedido, somando os juros. (Inserir máscara: "R$")
installmentValue 104.74 Valor de cada parcela. (Inserir máscara: "R$")

Exemplos

Exemplos de Requisição

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

{
	"KoinPreOrderToken": "ABC123",
	"OrderID": "123456789",
	"Currency":"BRL",
	"TotalPrice":199.90,
	"DiscountPercent": 0,
	"DiscountValue": 0,
	"IncreasePercent": 0,
	"IncreaseValue": 0,
	"Buyer":{
		"Name":"Nome do Pagador",
		"Email": "emailpagador@email.com",
		"BirthDate":"1958-12-22",
		"Documents":[{"Type":"CPF","Number":"123.456.798-91"}],
		"Phones":[{"AreaCode":"11", "Number":"2309-6020", "Type":2},
			  {"AreaCode":"11", "Number":"91234-5678", "Type":3}],
		"Address":{
			"City":"São Paulo",
			"State":"SP",
			"Country":"Brasil",
			"District":"Bela Vista",
			"Street":"Av. Paulista",
			"Number":1728,
			"Complement":"7 andar",
			"ZipCode":"01310-200",
			"Type":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",
			"Type":1
			},
		"Price":10.00,
		"UseDate":"2014-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":[{"Type":"CPF", "Number":"396.469.778-80"}]		
			},
			{
			"PassengerName":"Nome Completo do Passageiro 2",
			"PassengerNationality":"Brasil",
			"PassengerDocuments":[{"Type":"RG", "Number":"65.935.950-9"}]		
			},			
			{
			"PassengerName":"Nome Completo do Passageiro 3",
			"PassengerNationality":"Alemanha",
			"PassengerDocuments":[{"Type":"Passport", "Number":"CY4256890"}]		
			}			
		]
	}	
}
/** API de Finalizar Pedidos - Exemplo de requisição em PHP **/
	
$transmitObject = array(
'KoinPreOrderToken' => "ABC123",
'OrderID' => 123456789,
'Currency' => 'BRL',
'TotalPrice' => 249.99,
'DiscountPercent' => 0,
'DiscountValue' => 0,
'IncreasePercent' => 0,
'IncreaseValue' => 0,
	
//Definindo dados do pagador.
'Buyer' => array(	
	'Name' => 'Teste Koin',
	'Email' => 'teste@koin.com.br',
	'BirthDate' => '1959-04-02',
	
	// Definindo Documentos do pagador (CPF obrigatório).	
	'Documents' => array(
	   array('Type' => 'CPF', 'Number' => '259.228.370-60'), 
	),
	
	// Definindo Telefones do pagador (Obrigatório enviar ao menos um telefone).
	'Phones' => array(
	   array('AreaCode' => '11', 'Number' => '2309-6020', 'Type' => 3), 
	   array('AreaCode' => '11', 'Number' => '91234-5678', 'Type' => 4), 
	),
	
	// Definindo Endereço de cadastro (Apenas o 'Complement' não é obrigatório).
	'Address' => array(
			'City' => 'Sao Paulo',
			'State' => 'SP',
			'Country' => 'Brasil',
			'District' => 'Bela Vista',
			'Street' => 'Av. Paulista',
			'Number' => 1728,
			'Complement' => '7º andar',
			'ZipCode' => '01310-200',
			'Type' => 1
			)
	),
	
	// Definindo dados de Entrega e Frete (Apenas o 'Complement' não é obrigatório).
	'Shipping' => array(
		'Price' => 10.00,
		'UseDate' => '2014-03-05 00:00:00',
		'Address' => array(
				'City' => 'Sao Paulo',
				'State' => 'SP',
				'Country' => 'Brasil',
				'District' => 'Bela Vista',
				'Street' => 'Av. Paulista',
				'Number' => 1728,
				'Complement' => 'Casa',
				'ZipCode' => '01310-200',
				'Type' => 1
				),	
	),
	
	// Definindo informações dos itens (Apenas o 'Atributes' não é obrigatório).	
	'Items' => array(
		array(
			'Reference' => 'Cod_Item_123456',
			'Description' => 'Camiseta Selecao Brasileira',
			'Category' => 'Vestuario',
			'Quantity' => 1,
			'Price' => 199.99,
			'Attributes' => array( 'Key' => 'Tamanho','Value' => 'M')
		),
		array(
			'Reference' => 'Cod_Item_987654',
			'Description' => 'Calcao Futebol Master ',
			'Category' => 'Vestuario',
			'Quantity' => 1,
			'Price' => 40.00,
			'Attributes' => array( 'Key' => 'Tamanho','Value' => 'G')
		)   
	),
	// Definindo Parâmetros Adicionais.
	'AdditionalParameters' => array(
		'PartnerId' => '10',
		'ExpirationDate' => '2018-09-05 00:00:00',		
		'Passengers' => array(
			array(
				'PassengerName' => 'Nome Completo do Passageiro 1',
				'PassengerNationality' => 'Brasil',						
				'PassengerDocuments' => array(
					array('Type' => 'CPF', 'Number' => '396.469.778-80')
				)	
			),
			array(
				'PassengerName' => 'Nome Completo do Passageiro 2',
				'PassengerNationality' => 'Brasil',						
				'PassengerDocuments' => array(
					array('Type' => 'RG', 'Number' => '65.935.950-9')
				)
			),
			array(
				'PassengerName' => 'Nome Completo do Passageiro 3',
				'PassengerNationality' => 'Alemanha',						
				'PassengerDocuments' => array(
					array('Type' => 'Passport', 'Number' => 'CY4256890')
				)
			)						
		)	
	)	
);

	//Criando um JSON
	$jsonObject = json_encode($transmitObject);
	
	//Definindo a URL de requisição
	$url =  "http://api.qa.koin.in/api/frontend/checkout/preorder/complete";
	
	//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";}

	print $jsonObject;
	
?>

Exemplo de Retorno

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

{
	"Code": 200,
	"Message": "Sua compra foi APROVADA! Obrigado por comprar com KOIN Pós-Pago",
	"AdditionalInfo": [	]
	"installmentOptions": [{
		"iof": "4.53",
		"cetAM": "21.06",
		"installments": "5",
		"rates": "1.89",
		"description": "5 x de R$104.74",
		"originalValue": "500.0",
		"firstDueDate": "2018-08-17",
		"orderValue": "523.70",
		"installmentValue": "104.74",
	}],
}

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 Finalizar 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": []
    }

    Estornar Pedidos

    A API de Estornar Pedidos foi desenvolvida para automatizar o processo de Estorno Total ou Parcial de um pedido realizado com a KOIN.

    Com este serviço, a Loja poderá realizar o estorno de um pedido diretamente em seu sistema e o mesmo será, automaticamente, estornado na KOIN. Evitando assim que o Lojista tenha que acessar sua Conta KOIN para realizar o estorno de um pedido.

    Requisição

    As informações para o estorno 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 Estornar Pedidos:

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

    Ex: #ABC123
    Type Int SIM 1 Tipo de Estorno.

    1 = Estorno Total
    2 = Estorno Parcial
    Value Decimal SIM* 9.2 Valor a ser estornado.

    Ex: Para estorno Total: null
    Para estorno Parcial: 51.99
    AdditionalInfo String SIM 50 Motivo do Cancelamento.

    Ex: Comprador solicitou devolução do pedido.

    Retorno

    Códigos e Mensagens de Retorno

    Código Mensagem
    12100 Processamento realizado com sucesso. Pedido Estornado.
    12101 Erro de Requisição. Número do pedido inválido.
    12103 Erro de Requisição. O pedido já está cancelado.
    12104 Erro de Requisição. O pedido já está estornado.
    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 11100
    Message String Mensagem retornada pela API Processamento realizado com sucesso. Pedido Cancelado.
    AdditionalInfo Alpha Informações adicionais
    - Número do pedido
    - Tipo de estorno
    - Valor
    - Motivo do Cancelamento
    {
    "Reference":"#ABC123",
    "Type":2
    "Value":50.00
    "AdditionalInfo":"Comprador solicitou a devolução
    do produto X"
    }

    Exemplos

    Exemplo de Requisição

    /** API de Estornar Pedidos - Exemplo de requisição em PHP **/
     
    	/*Capturando informações para requisição*/ 
    	 
    	$Reference = '#ABC123'; 
    	$Type = 2; 
    	$Value = 50.00; 
    	$AdditionalInfo = utf8_encode('Comprador solicitou a devolução do produto X'); 
    	
    	/*Montando o objeto de requisição */
    
    	$transmitObject = array(
    	'Reference' => $Reference, //Número do pedido
    	'Type' => $Type, //Tipo do estorno: 1 = Total / 2 = Parcial
    	'Value' => $Value, //Valor do estorno Parcial(TYPE = 2)
    	'AdditionalInfo' => $AdditionalInfo //Motivo do estorno
    	);
    		
    	/*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.koin.com.br/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 Estorno - Exemplo de retorno - JSON **/
    		
    {
    	"Code":12100,
    	"Message":"Processamento realizado com sucesso. Pedido Estornado.",
    	"AdditionalInfo": ["Reference":"#ABC123",
    			   "AdditionalInfo": "Comprador solicitou a devolução do produto X"
    			  ]
    }