Casos de Uso - Api Expert

Aqui você encontra alguns casos práticos mais comus para o uso da API de Pagamentos Rakim Expert e seus diferentes fluxos de liquidação e processamento.

Criando um Pagamento Autorizado

A criação de um pagamento autorizado, também chamado de captura de pagamento consiste no processamento e efetivação do pagamento no momento do envio da requisição.

Esse é o fluxo mais utilizado nas aplicações-cliente do mercado.

Para você criar um pagamento autorizado será necessário utilizar o parâmetro capture como true (verdadeiro) na requisição.

A seguir o exemplo de requisição para captura de pagamento no JSON abaixo:

{
  "amount": 1035,
  "payment": {
    "type": "credit",
    "installments": 1,
    "capture": true,
    "softdescriptor": "PAG*TESTE",
    "card": {
      "holder": "TESTE HOLDER",
      "number": "5201561050025011",
      "expiry_month": "09",
      "expiry_year": "2024",
      "brand": "mastercard",
      "cvv": "123"
    }
  },
  "customer": {
    "name": "Comprador Teste",
    "document": "99999999999",
    "email": "example@test.com",
    "phone": "11999999999",
    "birthdate": "1969-12-31",
    "billing_address": {
      "street": "Rua teste",
      "number": "1",
      "district": "Bairro teste",
      "complement": "Complemento teste",
      "zipcode": "99999999",
      "city": "São Paulo",
      "state": "SP",
      "country": "BRA"
    }
  }
}

Criando um Pagamento Pré-Autorizado

A criação de um pagamento pré-autorizado, também chamado de pré-captura de pagamento, consiste no processamento prévio do pagamento, reservando o valor da transação enviado, bloqueando o limite do cartão do cliente pagante.

Uma vez bloqueado o valor do limite do cartão, este não poderá ser utilizado pelos próximos 7 dias.

Contudo você precisará CAPTURAR o valor bloqueado se quiser cobrar efetivamente esta transação do Cliente Pagante.

Veja a seguir uma esquematização da pré-captura de pagamento:

Esquematização da Pré-Captura de Pagamento

Geralmente nessa modalidade de pagamento são utilizados para operações que exigem garantia do pagamento ou a segurança do pagamento, como hotelaria e aluguel de carros.

Importante: A pré-captura será cancelada automaticamente caso você não realize a captura em até 7 dias posterior a criação do pagamento pré-autorizado.

A seguir veja um exemplo de requisição para pré-captura de pagamento:

{
  "amount": 1035,
  "payment": {
    "type": "credit",
    "installments": 1,
    "capture": false,
    "softdescriptor": "PAG*TESTE",
    "card": {
      "vault": "2beaeb98-391d-41d9-8685-61464f3c0789"
    }
  },
  "customer": {
    "name": "Comprador Teste",
    "document": "99999999999",
    "email": "example@test.com",
    "phone": "11999999999",
    "birthdate": "1969-12-31",
    "billing_address": {
      "street": "Rua teste",
      "number": "1",
      "district": "Bairro teste",
      "complement": "Complemento teste",
      "zipcode": "99999999",
      "city": "São Paulo",
      "state": "SP",
      "country": "BRA"
    }
  }
}

OBS: você não pode Capturar um valor maior que o valor previamente Pré-Capturado na criação do pagamento.

Criando um Pagamento com Cofre de Cartão

A criação de pagamentos com cofre de cartão consiste na utilização de um TOKEM do Cartão armazenado no cofre para realizar uma pré-autorização ou autorização de pagamentos sem o envio dos dados do cartão abertos na requisição.

Esse método de criação de pagamentos é seguro e evita que os dados do cartão sejam capturados indevidamente na sua aplicação. Também pode ser implementado a funcionalidade COMPRA COM UM CLIQUE, onde você armazena apenas o TOKEM do cartão na sua aplicação.

Entretanto, para a criação do pagamento utilizando essa modalidade é necessário realizar a tokenização prévia dos dados cartão através do endpoint Como Criar um Cofre de Cartão

Veja no exemplo abaixo a requisição JSON para captura de pagamento com cofre de cartão:

{
  "amount": 1035,
  "payment": {
    "type": "credit",
    "installments": 1,
    "capture": true,
    "softdescriptor": "PAG*TESTE",
    "card": {
      "vault": "2beaeb98-391d-41d9-8685-61464f3c0789"
    }
  },
  "customer": {
    "name": "Comprador Teste",
    "document": "99999999999",
    "email": "example@test.com",
    "phone": "11999999999",
    "birthdate": "1969-12-31",
    "billing_address": {
      "street": "Rua teste",
      "number": "1",
      "district": "Bairro teste",
      "complement": "Complemento teste",
      "zipcode": "99999999",
      "city": "São Paulo",
      "state": "SP",
      "country": "BRA"
    }
  }
}

OBS: Você pode utilizar o TOKEM do Cartão para pagamentos de pré-captudos e/ou capturados.

Criando um Pagamento com Split

A criação de pagamento com o split consiste no processo de indicação dos Recebedores finais, alterando a liquidação.

O fluxo de aprovação da transação não está vinculado no fluxo de liquidação. O sistema captura a transação no Recebedor primary e promove a liquidação para os demais participantes da transação secondary

Você pode utilizar um pagamento com split tanto em uma pré-autorização ou na autorização.

Essa modalidade de pagamento é utilizada quando um segundo recebedor (secondary) recebe uma parte da transação como Comissão de venda ou Garantia por exemplo.

Por exemplo, ao fazer a venda de um produto online, você pode dividir uma parte do pagamento para a transportadora do pedido e uma parte para a fornecedora do pedido, conseguindo assim, alterar o fluxo de liquidação no momento da criação do pagamento.

Esta opção tem uma gama enorme de aplicabilidades, dependendo do fluxo da sua aplicação.

O fluxo abaixo demostra o processo realizado:

Obs: A transação com Split de Pagamento só pode ser realizada para Lojas previamente cadastradas na plataforma e desde que essas lojas estajam sob sua gestão ou que você mesmo as tenha criado pelo ending point Criar Estabelecimento

Considerações sobre o Split de Pagamento

Considere como PRIMARY, o participante principal onde a transação será registrada como origem do pagamento e que recebrá um pedaço da transação na liquidação.
Considere como SECONDARY, todos os demais participantes secundários no split que vão receber algum pedaço da transação na liquidação;
Só é possível criar um split com um unico primary - participante primário;
O participante primário não pode receber menos que 1% do pagamento;
A soma dos valores divididos no split não pode ser diferente do valor líquido da transação;

No Json abaixo você tem um exemplo de requisição de Transação com Split de Recebedores e com suas respectivas partes:

{
  "amount": 1035,
  "payment": {
    "type": "credit",
    "installments": 1,
    "capture": true,
    "card": {
      "holder": "TESTE HOLDER",
      "number": "5201561050025011",
      "expiryMonth": "09",
      "expiryYear": "2024",
      "brand": "mastercard",
      "cvv": "123"
    }
  },
  "customer": {
    "name": "Comprador Teste",
    "document": "99999999999",
    "email": "example@test.com",
    "phone": "11999999999",
    "birthdate": "1969-12-31",
    "billingAddress": {
      "street": "Rua teste",
      "number": "1",
      "district": "Bairro teste",
      "complement": "Complemento teste",
      "zipcode": "99999999",
      "city": "São Paulo",
      "state": "SP",
      "country": "BRA"
    }
  },
  "splits": [
    {
      "recipientToken": "9b7ba208a0e54094b9c06ef479acf4b29ddc1d3a",
      "merchantType": "PRIMARY",
      "chargeFee": true,
      "type": "PERCENTAGE",
      "amountSplit": 6000
    },
    {
      "recipientToken": "4a723333747e4aa3ac10f12fa65af89e5057d651",
      "merchantType": "SECONDARY",
      "type": "PERCENTAGE",
      "chargeFee": false,
      "discountGrossAmount": false,
      "amountSplit": 4000
    },
    {
      "recipientToken": "4a723333747e4aa3ac10f12fa65af89e5057d633",
      "merchantType": "SECONDARY",
      "type": "AMOUNT",
      "chargeFee": false,
      "discountGrossAmount": false,
      "amountSplit": 200
    }
  ]
}

Criando um Pagamento com Split Tardio

A criação de pagamento com o split tardio consiste no processo de indicação dos Recebedores finais, alterando a liquidação.

Você pode utilizar um pagamento com split tanto em uma pré-autorização ou na autorização.

A diferença está na possibilidade de indicar os participantes secondary posteriormente a captura da transação.

Esse processo é amplamente utilizado na venda de pacotes turisticos, onde o operador vende um pacote com multiplos fornecedores, mas não sabe quem prestará o serviço final. A informação só chega ao opertador DEPOIS do serviço prestado. Dessa forma o sistema captura a transação em nome do Operador Turistico e alguns dias depois promove a informação dos prestadores (secondary), liquidando a transação com a parte que cabe a cada prestador do serviço.

Veja a seguir o fluxo de processo:

Fluxo do Split Tardio do Pagamento

Sendo assim, observando o esquema, percebe-se a necessidade de realizar a requisição de criação do pagamento e a requisição de ativação do split tardio.

Caso você crie um pagamento como o Split Tardio e por NÃO defina posteriormente os participantes secondary através do endpoint de Ativação do Split Tardio , a liquidação da transação não será efetivada até que o estabelecimento onde a transação ocorreu primary promova a informação dos participantes secondary

A seguir veja um exemplo de requisição para criação de pagamentos com split de pagamento tardio:

{
  "amount": 1035,
  "payment": {
    "type": "credit",
    "installments": 1,
    "capture": true,
    "delayed_split": true,
    "softdescriptor": "PAG*TESTE",
    "card": {
      "holder": "TESTE HOLDER",
      "number": "5201561050025011",
      "expiry_month": "09",
      "expiry_year": "2024",
      "brand": "mastercard",
      "cvv": "123"
    }
  },
  "customer": {
    "name": "Comprador Teste",
    "document": "99999999999",
    "email": "example@test.com",
    "phone": "11999999999",
    "birthdate": "1969-12-31",
    "billing_address": {
      "street": "Rua teste",
      "number": "1",
      "district": "Bairro teste",
      "complement": "Complemento teste",
      "zipcode": "99999999",
      "city": "São Paulo",
      "state": "SP",
      "country": "BRA"
    }
  }
}

Após a criação do pagamento é necessário a ativação do split de pagamento, veja a seguir um exemplo de requisição:

{
  "orderId": "6183f4ac7ad8d",
  "splits": [
    {
      "recipientToken": "9b7ba208a0e54094b9c06ef479acf4b29ddc1d3a",
      "merchantType": "PRIMARY",
      "chargeFee": true,
      "type": "PERCENTAGE",
      "amountSplit": 6000
    },
    {
      "recipientToken": "4a723333747e4aa3ac10f12fa65af89e5057d651",
      "merchantType": "SECONDARY",
      "type": "PERCENTAGE",
      "chargeFee": false,
      "discountGrossAmount": false,
      "amountSplit": 4000
    },
    {
      "recipientToken": "4a723333747e4aa3ac10f12fa65af89e5057d633",
      "merchantType": "SECONDARY",
      "type": "AMOUNT",
      "chargeFee": false,
      "discountGrossAmount": false,
      "amountSplit": 200
    }
  ]
}

Vale ressaltar que devem ser consideradas algumas observações:

Caso a soma dos percentuais dos participantes do split tardio for maior que 100%, a ativação do split tardio não será realizada e continuará pendente de ativação.
Caso a soma dos percentuais dos participantes do split tardio for menor que 100%, a ativação do split tardio será realizada e o participante primário receberá o resto percentual que sobrou do split criado.
Caso a taxa cobrada da plataforma pela autorização do pagamento for em cima do líquido do participante e o desconto dela sobre o participante resultar em um valor líquido a receber negativo, a ativação do split tardio não será realizada e continuará pendente de ativação.
Caso a taxa cobrada da plataforma não for informada para ser paga por nenhum dos participantes através do parâmetro chargeFee, ela será cobrada pelo participante primário da ativação do split.

Além de considerar os casos acima, reveja as Considerações do Split do Pagamento para se integrar ao endpoint de ativação do split.