NinePay API
Introdução
Bem vindo a referência da API NinePay. É através desta API que você integra o seu sistema ao nosso. Nossa API é RESTful, e todas suas respostas são em JSON, no endpoint base:
https://payments.cefis.com.br/api/v1/
Ambientes
Além do ambiente de produção temos disponível o ambiente sandbox para a realização de testes de integração. Toda a comunicação com o ambiente sandbox deve ser feita através da url:
https://api.sandbox.cefispay.com.br/api/v1/
Autenticação
Todas as requisições que requerem autenticação, deverão informar no header Authorization o token de api enviado pela nossa equipe, observando sempre o ambiente desejado e no seguinte formato:
Authorization: Bearer <token>
Headers
Recomendamos que os cabeçalhos da requisições sejam corretamente adicionados para trabalhar com os tipos de dados enviados e recebidos da API:
- Todas as requisições devem contem o header
Content-Type: application/json, a menos que o endpoint específico defina diferente - Todas as requisições devem contem o header
Accept: application/json, a menos que o endpoint específico defina diferente
Hash de cartões
O hash de um cartão é uma versão criptografada de todos os dados do cartão do cliente, essa é a maneira mais segura de enviar os dados do cartão do seu cliente diretamente para a gente. Abaixo vamos detalhar como ele funciona e como obter um hash a partir dos dados inseridos pelo cliente. É importante ressaltar que esse fluxo deve ser executado no front-end, seja ele web ou mobile, e que os dados do cartão do cliente nunca devem ser enviados para o backend, já o hash do cartão pode ser enviado para o backend sem problemas.
Gerando uma encryption key
A encryption key consiste basicamente em uma chave pública RSA usada para encriptar os dados do cartão, essa chave só pode ser usada uma vez, então sempre que precisar encriptar um novo cartão você precisa gerar uma nova encryption key.
Para gerar uma encryption key é necessário fazer uma requisição POST para a rota /encryption_keys da API enviando como parâmetro seu
merchant_id, essa rota não necessita de autenticação, já que a requisição deverá ser feita diretamente do front-end.
A requisição deverá ter esse formato:
curl -X POST https://payments.cefis.com.br/api/v1/encryption_keys -H 'Content-Type: application/json' -d '{"merchant_id":"SEU_MERCHANT_ID"}'
Como resposta você receberá um objeto JSON no seguinte formato:
{
"id": 1111,
"public_key": "-----BEGIN PUBLIC KEY-----\n ... \n-----END PUBLIC KEY-----\n",
"ip_address": "000.000.000.000",
"created_at": "2017-07-03",
}
Encriptando os dados do cartão
Para encriptar os dados do cartão primeiro você precisa formatá-los de forma correta, para isso crie uma string JSON contendo todos os dados do cartão no seguinte formato:
{"card_number":"1111111111111111","card_holder_name":"Jose Silva","card_expiration_date":"11/2021","card_cvv":"111"}
Em seguida faça a criptografia RSA dessa string utilizando a chave pública (public_key) gerada no passo anterior, com padding do tipo PKCS1.
Após criptografar os dados converta a string resultante para base64 e você terá um resultado parecido com esse:
GprWNDlg+MKGgtr6y9wJgz7oOUxGuhhdX3EwydmoOvb+yNDWrjDKktDtWicReOrvSo0u5rsNvCqBFjyoMfaRXn4Qq3KdV8vuuFXubb4FT3OcSSVpu6ddaOjm2tf82+GKjdCy54Lgw4T0m9mWdLPveh/zkYP0+4lhHCFhBKX5EqBdR4918wP5oUV1KpzV4V94ldSA+Cy2n1NUxyUiSnv87H2m+HkdqKDIcX9X8KEtUmorC/EjTPzoeEdpRdj8t3ThcL73mirJvDcYthSdT/ADyaFQ2hMRMkKEVOQjUYMn76vzWyQkqsZ+HVQlxQMOBVHPh5yfrmi1HAVd1jLQuOK8wQ==
O último passo é concatenar o id da sua encryption key (recebido como resposta da requisição anterior) com a string em base64 que representa os dados do cartão, da seguinte forma:
encryption_key_id + "_" + base64_encrypted_card
O resultado será o seu card hash:
1111_GprWNDlg+MKGgtr6y9wJgz7oOUxGuhhdX3EwydmoOvb+yNDWrjDKktDtWicReOrvSo0u5rsNvCqBFjyoMfaRXn4Qq3KdV8vuuFXubb4FT3OcSSVpu6ddaOjm2tf82+GKjdCy54Lgw4T0m9mWdLPveh/zkYP0+4lhHCFhBKX5EqBdR4918wP5oUV1KpzV4V94ldSA+Cy2n1NUxyUiSnv87H2m+HkdqKDIcX9X8KEtUmorC/EjTPzoeEdpRdj8t3ThcL73mirJvDcYthSdT/ADyaFQ2hMRMkKEVOQjUYMn76vzWyQkqsZ+HVQlxQMOBVHPh5yfrmi1HAVd1jLQuOK8wQ==
Pronto, agora os dados do cartão do cliente já estão em um formato seguro para serem transportados pela rede, podendo agora ser enviados para o seu back-end dar sequência ao fluxo. Vale lembrar que cada card hash pode ser usado apenas uma vez e além disso tem uma validade máxima de 30 minutos após a geração da encryption key. Caso seja necessário utilizar o cartão mais de uma vez faça uma requisição para a rota de cartões e salve esse cartão vinculado ao usuário que o detém, assim você receberá um ID único que poderá ser usado para realizar mais transações com o mesmo cartão.
Authentication
Todas as requisições que requerem autenticação devem incluir no cabeçalho Authorization o token de API enviado pela nossa equipe. O token deve ser fornecido no seguinte formato:
Authorization: Bearer <token>
| Security Scheme Type: | apiKey |
|---|---|
| Header parameter name: | Authorization |