Instrodução

Bem vindo a documentação do protocolo de pagamento Convertize.

Para se integrar com nosso protocolo de pagamento você deverá desenvolver uma WebAPI (REST) seguindo todas as informações deste protocolo.

Exemplo: {BASE_URL}/{OPERATION_URI}

{BASE_URL} => URL base que aponta para sua WebAPI
{OPERATION_URI} => Endpoint especifico chamados pelo protocolo de pagamento Convertize

Authentication

Nosso sistema envia 2 headers de validação que é possível customizar via ambiente administrativo da Convertize, segue exemplo abaixo:

X-CONVERTIZE-APPKEY: APPKEY
X-CONVERTIZE-APPTOKEN: APPTOKEN

Parcelamento

Consulta Parcelamento

import requests

r = requests.get('{BASE_URL}/installments?amount={amount}&bin={bin}&store={store}', headers={
  'X-CONVERTIZE-APPKEY': API_KEY,
  'X-CONVERTIZE-APPTOKEN': APPTOKEN,
})

curl "{BASE_URL}/installments?amount={amount}&bin={bin}&store={store}"
  -H "X-CONVERTIZE-APPKEY: {APPKEY}"
  -H "X-CONVERTIZE-APPTOKEN: {APPTOKEN}"

O comando acima deverá retonar um JSON conforme estrutura abaixo:

{
  "installments": [
    {"interest_rate":0.0, "total":119.99, "parcel":1, "value":119.99},
    {"interest_rate":0.0, "total":119.99, "parcel":2, "value":59.99},
  ]
}

Neste endpoint nosso protocolo espera que você retorne quais as formas de parcelamento para uma forma de pagamento.

HTTP Request

GET {BASE_URL}/installments?amount={amount}&bin={bin}&store={store}

Request Headers

Parameter	Value
X-CONVERTIZE-APPKEY	{X-CONVERTIZE-APPKEY}
X-CONVERTIZE-APPTOKEN	{X-CONVERTIZE-APPTOKEN}
Content-Typen	application/json

Request Parameters

Parameter	Type	Description
amount	integer	Valor total do pagamento em centavos
bin	integer	Bin do cartão (6 primeiros digitos)
store	string	Nome do ambiente na Convertize

Response Body

Parameter	Type	Description
installments	array[]	list com os parcelamentos
=>installment	object	Dados do parcelamento
=>=>interest_rate	decimal(16,2)	Valor do juros no parcelamento
=>=>parcel	integer	Número da parcela
=>=>value	decimal(16,2)	Valor da parcela
=>=>total	decimal(16,2)	Valor total da do parcelamento

Pagamento

Formas de Pagamento

import requests

r = requests.get('{BASE_URL}/payments', headers={
  'X-CONVERTIZE-APPKEY': API_KEY,
  'X-CONVERTIZE-APPTOKEN': APPTOKEN,
})

curl "{BASE_URL}/payments"
  -H "X-CONVERTIZE-APPKEY: {APPKEY}"
  -H "X-CONVERTIZE-APPTOKEN: {APPTOKEN}"

O comando acima deverá retonar um JSON conforme estrutura abaixo:

{
  "payments": [
    "Amex",
    "Cabal",
    "Diners",
    "Discover",
    "Elo",
    "Hiper",
    "Hipercard",
    "Jcb",
    "Visa",
    "Mastercard",
    "Visaelectron",
    "Maestro",
    "Boleto",
    "PrivateLabel"
  ]
}

Neste endpoint nosso protocolo espera que você retorne quais as formas de pagamento sua WebAPI suporta.

HTTP Request

GET {BASE_URL}/payments

Response Body

Parameter	Type	Description
payments	array[]	list com os nomes das formas de pagamento suportadas pela sua WebAPI

Formas de pagamentos disponível

Parameter	Type	Description
Amex	Credit Card	American Express
Cabal	Credit Card	Cabal
Diners	Credit Card	Dinners
Discover	Credit Card	Discover
Elo	Credit Card	Elo
Hiper	Credit Card	Hiper
Hipercard	Credit Card	Hipercard
Jcb	Credit Card	Discover
Visa	Credit Card	Visa
Mastercard	Credit Card	Master Card
Visaelectron	Debit Card	Visa Electron
Maestro	Debit Card	Maestro
Boleto	Boleto	Boleto Bancário
PrivateLabel	PrivateLabel	Cartão Privado

Criar Pagamento

import requests

r = requests.post('{BASE_URL}/payments', headers={
  'X-CONVERTIZE-APPKEY': API_KEY,
  'X-CONVERTIZE-APPTOKEN': APPTOKEN,
}, data={JSON})

curl "{BASE_URL}/payments"
  -H "X-CONVERTIZE-APPKEY: {APPKEY}"
  -H "X-CONVERTIZE-APPTOKEN: {APPTOKEN}"
  -X POST -d '{JSON}'

Exemplo do {JSON} para envio no body:

{
  "id": "8b5bf004-cb12-419a-a551-22b1cbab5078",
  "nsu": 1,
  "amount": 100,
  "payment_method": "Visa",
  "card": {
    "brand": "Visa",
    "number": "4551870000000183",
    "exp_month": "10",
    "exp_year": "2019",
    "holder_name": "TESTE CIELO",
    "security_code": "123"
  },
  "installments": 1,
  "request": {
    "ip_address": "127.0.0.1",
    "session_id": "wim2gfti63d4e9dcgvdnqdb7mwytahkf",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/68.0.3",
    "device_finger_print": "a5eb67bc403ed1021b91c20f1cb4c6a0"
  },
  "buyer": {
    "id": "bcb5d867-3a11-4ea2-b79e-0193e9152b2e",
    "name": "Comprador Teste",
    "document_number": "04136081820",
    "document_type": "CPF",
    "email": "compradorteste@convertize.com.br",
    "phone": "1140107676",
    "billing_address": {
      "city": "RIBEIRÃO PRETO",
      "state": "SP",
      "street": "R BERNARDINO DE CAMPOS",
      "number": "1001",
      "neighborhood": "HIGIENOPOLIS",
      "country": "BRA",
      "zipcode": "14015130"
    }
  },
  "cart": {
    "delivery_address":{
      "city": "RIBEIRÃO PRETO",
      "state": "SP",
      "street": "R BERNARDINO DE CAMPOS",
      "number": "1001",
      "neighborhood": "HIGIENOPOLIS",
      "country": "BRA",
      "zipcode": "14015130"
    },
    "items": [
      {
        "id", 1, 
        "ean_13": "1234567890123", 
        "reference_code": 1, 
        "name": "Produto de Teste",
        "quantity": 1,
        "unit": 100,
        "total": 100,
        "discount": 0
      }
    ],
    "shipping_total": 0
  }
}

O comando acima deverá retonar um JSON conforme estrutura abaixo:

{
  "id": "8b5bf004-cb12-419a-a551-22b1cbab5078",
  "status": "APPROVED",
  "payment_id": "TESTE-97feb5bb-dcdc-4f56-859c-a3df2bfc0cf8",
  "nsu": "12345678",
  "tid": "123125123ASD12312",
  "redirect_url": null,
  "boleto_url": null,
  "code": null,
  "message": "Pagamento autorizado com sucesso",
  "token": null
}

Neste endpoint nosso protocolo espera que você receba as informações de pagamento faça o processamento e crie uma estrutura para consulta de status futuras.

HTTP Request

POST {BASE_URL}/payments

Request Headers

Parameter	Value
X-CONVERTIZE-APPKEY	{X-CONVERTIZE-APPKEY}
X-CONVERTIZE-APPTOKEN	{X-CONVERTIZE-APPTOKEN}
Content-Typen	application/json

Request Body

Parameter	Type	Description
id	uuid	ID da transação na Convertize
nsu	integer	Número sequencial único da transação
amount	integer	Valor total do pagamento em centavos
payment_method	string	Nome da forma de pagamento, Veja a lista
card	object	Dados do cartão
=> brand	string	Bandeira do Cartão
=> number	string	Número do Cartão
=> exp_month	string	Mes de Validade do Cartão
=> exp_year	string	Ano de Validade do Cartão
=> holder_name	string	Nome do Cartão
=> security_code	string	Código de segurança do Cartão
installments	integer	Número de parcelas
request	object	Dados do request do usuário
=> ip_address	string	Endereço de IP do comprador
=> session_id	string	Id da sessão do comprador
=> user_agent	string	User Agent do comprador
=> device_finger_print	string	Fingerprint representa caracteristicas do dispositivo usado para fazer o pedido
buyer	object	Dados do comprador
=> id	uuid	ID do comprador na Convertize
=> name	string	Nome do comprador
=> document_number	string	Número do documento do comprador
=> document_type	string	Tipo do documento do comprador
=> email	string	E-mail do comprador
=> phone	string	Telefone do comprador
=> billing_address	object	Dados do endereço de entrega
=>=> city	string	Cidade do endereço de pagamento
=>=> state	string	Estado do endereço de pagamento
=>=> street	string	Rua do endereço de pagamento
=>=> number	string	Número do endereço de pagamento
=>=> neighborhood	string	Bairro do endereço de pagamento
=>=> country	string	Pais do endereço de pagamento
=>=> zipcode	string	Zipcode (CEP) do endereço de pagamento
cart	object	Dados do carrinho
=> delivery_address	object	Dados do endereço de entrega
=>=> city	string	Cidade do endereço de entrega
=>=> state	string	Estado do endereço de entrega
=>=> street	string	Rua do endereço de entrega
=>=> number	string	Número do endereço de entrega
=>=> neighborhood	string	Bairro do endereço de entrega
=>=> country	string	Pais do endereço de entrega
=>=> zipcode	string	Zipcode (CEP) do endereço de entrega
=>items	array of object	Lista de objetos com dados dos items
=>=>id	integer	ID do item na Convertize
=>=>ean_13	string	EAN 13 do item na Convertize
=>=>reference_code	string	Código de Referência do item na Convertize
=>=>name	string	Nome do item
=>=>quantity	integer	Quantidade deste item no carrinho
=>=>unit	integer	Preço Unitário do item em centavos
=>=>total	integer	Preço Unitário do item em centavos
=>=>discount	integer	Desconto total do item em centavos
=>shipping_total	integer	Valor total do frete em centavos
notification_url	string	Url para notificação com o status das transações
return_url	string	Url de retorno (usada somente no fluxo com redirect)

Response Body

Parameter	Type	Description
id	uuid	ID da transação na Convertize
status	string	Status da transação (APPROVED, DENIED, AUTHENTICATING ou APPROVED_PENDING_CAPTURE)
payment_id	string	ID de do pagamento gerado pela sua WebAPI
nsu	string	Número sequencial unico
tid	string	ID da transação
redirect_url	string	URL de authenticação usando em pagamentos com redirecionamentos
boleto_url	string	URL do boleto usado somente em pagamentos com Boleto
code(optional)	string	Código de erro
message(optional)	string	Mensagem de erro
token(optional)	string	Token referente ao cartão ou forma de pagamento

Consulta Pagamento

import requests

r = requests.get('{BASE_URL}/payments/{ID}', headers={
  'X-CONVERTIZE-APPKEY': API_KEY,
  'X-CONVERTIZE-APPTOKEN': APPTOKEN,
})

curl "{BASE_URL}/payments/{ID}"
  -H "X-CONVERTIZE-APPKEY: {APPKEY}"
  -H "X-CONVERTIZE-APPTOKEN: {APPTOKEN}"

Neste exemplo nosso protocolo envia no Request Parameter a variavel {ID} (Id do pagamento na Convertize):

{ID} (Id do pagamento na Convertize) = 8b5bf004-cb12-419a-a551-22b1cbab5078

O comando acima deverá retonar um JSON conforme estrutura abaixo:

{
  "id": "8b5bf004-cb12-419a-a551-22b1cbab5078",
  "status": "APPROVED",
  "payment_id": "TESTE-97feb5bb-dcdc-4f56-859c-a3df2bfc0cf8",
  "nsu": "12345678",
  "tid": "123125123ASD12312",
  "redirect_url": null,
  "boleto_url": null,
  "code": null,
  "message": "Pagamento autorizado com sucesso",
  "token": null
}

Neste endpoint nosso protocolo usa para consultar um status de uma transação em sua WebAPI.

HTTP Request

GET {BASE_URL}/payments/{id}

Request Parameters

Parameter	Description
id	ID da transação na Convertize

Request Headers

Parameter	Value
X-CONVERTIZE-APPKEY	{X-CONVERTIZE-APPKEY}
X-CONVERTIZE-APPTOKEN	{X-CONVERTIZE-APPTOKEN}
Content-Typen	application/json

Response Body

Parameter	Type	Description
id	uuid	ID da transação na Convertize
status	string	Status da transação (APPROVED, DENIED, AUTHENTICATING ou APPROVED_PENDING_CAPTURE)
payment_id	string	ID de do pagamento gerado pela sua WebAPI
nsu	string	Número sequencial unico
tid	string	ID da transação
redirect_url	string	URL de authenticação usando em pagamentos com redirecionamentos
boleto_url	string	URL do boleto usado somente em pagamentos com Boleto
code(optional)	string	Código de erro
message(optional)	string	Mensagem de erro
token(optional)	string	Token referente ao cartão ou forma de pagamento

Cancela Pagamento

import requests

r = requests.post('{BASE_URL}/payments/{ID}/cancel', headers={
  'X-CONVERTIZE-APPKEY': API_KEY,
  'X-CONVERTIZE-APPTOKEN': APPTOKEN,
}, data={JSON})

curl "{BASE_URL}/payments/{ID}/cancel"
  -H "X-CONVERTIZE-APPKEY: {APPKEY}"
  -H "X-CONVERTIZE-APPTOKEN: {APPTOKEN}"
  -X POST -d '{JSON}'

Neste exemplo nosso protocolo envia no Request Parameter a variavel {ID} (Id do pagamento na Convertize):

{ID} (Id do pagamento na Convertize) = 8b5bf004-cb12-419a-a551-22b1cbab5078

Exemplo do {JSON} enviado no body:

{
  "id": "8b5bf004-cb12-419a-a551-22b1cbab5078"
}

O comando acima deverá retonar um JSON conforme estrutura abaixo:

{
  "id": "8b5bf004-cb12-419a-a551-22b1cbab5078",
  "status": "CANCELED",
  "code": null,
  "message": "Pagamento cancelado com sucesso",
}

Neste endpoint nosso protocolo usa para cancelar uma transação em sua WebAPI.

HTTP Request

POST {BASE_URL}/payments/{id}/cancel

Request Parameters

Parameter	Description
id	ID da transação na Convertize

Request Headers

Parameter	Value
X-CONVERTIZE-APPKEY	{X-CONVERTIZE-APPKEY}
X-CONVERTIZE-APPTOKEN	{X-CONVERTIZE-APPTOKEN}
Content-Typen	application/json

Request Body

Parameter	Description
id	ID da transação na Convertize

Response Body

Parameter	Type	Description
id	uuid	ID da transação na Convertize
status	string	Status da transação (CANCELED)
code(optional)	string	Código de erro
message(optional)	string	Mensagem de erro

Captura Pagamento

import requests

r = requests.post('{BASE_URL}/payments/{ID}/capture', headers={
  'X-CONVERTIZE-APPKEY': API_KEY,
  'X-CONVERTIZE-APPTOKEN': APPTOKEN,
}, data={JSON})

curl "{BASE_URL}/payments/{ID}/capture"
  -H "X-CONVERTIZE-APPKEY: {APPKEY}"
  -H "X-CONVERTIZE-APPTOKEN: {APPTOKEN}"
  -X POST -d '{JSON}'

Neste exemplo nosso protocolo envia no Request Parameter a variavel {ID} (Id do pagamento na Convertize):

{ID} (Id do pagamento na Convertize) = 8b5bf004-cb12-419a-a551-22b1cbab5078

Exemplo do {JSON} enviado no body:

{
  "id": "8b5bf004-cb12-419a-a551-22b1cbab5078"
}

O comando acima deverá retonar um JSON conforme estrutura abaixo:

{
  "id": "8b5bf004-cb12-419a-a551-22b1cbab5078",
  "status": "CAPTURED",
  "code": null,
  "message": "Pagamento capturado com sucesso",
}

Neste endpoint nosso protocolo usa para capturar uma transação em sua WebAPI.

HTTP Request

POST {BASE_URL}/payments/{id}/capture

Request Parameters

Parameter	Description
id	ID da transação na Convertize

Request Headers

Parameter	Value
X-CONVERTIZE-APPKEY	{X-CONVERTIZE-APPKEY}
X-CONVERTIZE-APPTOKEN	{X-CONVERTIZE-APPTOKEN}
Content-Typen	application/json

Request Body

Parameter	Description
id	ID da transação na Convertize

Response Body

Parameter	Type	Description
id	uuid	ID da transação na Convertize
status	string	Status da transação (CAPTURED)
code(optional)	string	Código de erro
message(optional)	string	Mensagem de erro