NAV Navbar
curl
  • Introdução
  • Ambiente Sandbox
  • Autenticação
  • Checkout
  • Transações
  • Introdução

    Use a documentação do desenvolvedor para integrar uma infraestrutura de pagamentos em seu site ou aplicativo. A API KambaCheckout padrão trata de toda complexidade e permite um fluxo de trabalho único para aceitar pagamentos.

    Ponto de partida

    Esta documentação mostra os passos necessários para trabalhar com a API KambaCheckout:

    Notas Adicionais

    Você deve estar consciente em relação ao seguinte:

    A URL base da API:

    Solicitações HTTP

    Exemplo de solicitação HTTP:

    curl https://sandbox.usekamba.com/v1/foobar \
        -H "Content-Type: application/json" \
        -H "Authorization: Token zeQ8j8r2VfPSUfcKVTKHxAtt" \
        -d '{
            "foo_bar": "foobar"
        }'
    

    Todas as solicitações HTTP devem fornecer um cabeçalho Authorization: Token CHAVE_API e Content-Type: application/json quando necessário. O corpo das solicitações e respostas são codificadas em JSON.

    Solicitações devem ser enviadas sempre usando HTTPS nas URLs.

    Chaves de API

    Para receber as suas credenciais api_key, merchant_id entre em contacto connosco em info@usekamba.com. Use a chave de testes para testar suas integrações e mude para uma chave de produção quando desejar submeter a sua integração para um ambiente com clientes reais.

    Métodos de Pagamento

    KambaCheckout estará sempre adicionando novos métodos de pagamento locais. Atualmente suporta estes métodos de pagamento:

    Todos os métodos de pagamento quando permitidos são mostrados para o consumidor.

    Fluxo de pagamento por KambaCheckout padrão

    Por exemplo, a solicitação POST:

    
    curl https://sandbox.usekamba.com/v1/checkout \
        -H "Content-Type: application/json" \
        -H "Authorization: Token GeQ8j8r2VfPSUfcKVTKHxAtt" \
        -d '{
            "customer": {
                "name": "Primeiro Último",
                "phone_number": "924426615",
                "email": "cliente@email.com",
                "document_identity": {
                    "identity_type": "Bilhete de Identidade",
                    "identity_number": "123456789MJ001"
                }
            },
            "total": 10500,
            "currency": "AOA",
            "notes": "Alguma descrição...",
            "items":[{
                "name": "Curso Android para Desenvolvedores",
                "description": "Introdução ao desenvolvimento mobile com Java/Android",
                "quantity": 1,
                "price": 10500
            }],
            "shipment": {
                    "province": "Luanda",
                    "city": "Viana",
                    "district": "Condomínio 1000 Casas",
                    "street": "Rua nº 7",
                    "address": "Casa nº 424"
            },
            "redirect_url_success": "https://seusite.com/pagamento-processado"
        }'
    

    KambaCheckout retorna:

    {
        "id": "23ze8d9x-f03a-42f8-8464-442a679d23db",
        "created_at": "2014-03-27T15:18:09+0000"
    }
    

    O cliente envia uma solicitação para POST https://sandbox.usekamba.com/v1/checkout com a informação dos dados de pagamento para inicializar o processo de checkout (por exemplo, informação dos produtos a comprar ou os dados de um carrinho de compras com o total da quantia a pagar). KambaCheckout retorna a informação resultante com o identificador do checkout, por exemplo 23ze8d9x-f03a-42f8-8464-442a679d23db.

    O cliente direciona o comprador para o fluxo de pagamento, usando o identificador de checkout retornado na solicitação anterior. O exemplo abaixo mostra uma URL em Sandbox para que o usuário inicie um fluxo de pagamento.

    GET https://sandbox.usekamba.com/v1/checkout/pay?code=(insira o código identificador de checkout da resposta anterior aqui)

    Quando todos os detalhes do pagamento forem processados, KambaCheckout redireciona seu cliente de volta para o seu site usando a URL que você forneceu anteriormente em redirect_url_success. Caso não tenha fornecido nenhuma url de direcionamento, será mostrado a página padrão de pagamento com sucesso KambaCheckout. Se tudo correr bem, você receberá a notificação de pagamento recebido no aplicativo Kamba PRO e os detalhes do pagamento. Nossa plataforma carrega esse valor para a sua carteira na conta Comerciante.

    Integração em seu site ou aplicativo

    KambaCheckout fornece recursos visuais de fácil integração para seu site ou aplicativo na forma de etiqueta de pagamentos seguros e você deve incluir nossas imagens de botões pré-feitos em sua página de checkout ou conclusão de pedido.

    Ambiente Sandbox

    Nós fornecemos-lhe acesso a uma conta Comerciante para testes de integração com nossas APIs.

    Para iniciar os testes é necessário uma conta Comerciante no Sandbox e obter a sua chave de API. Você deve ter ainda um ou mais usuários para testar os endpoints da API (você não pode pagar algo para si mesmo não é?).

    Algumas informações importantes que você deve estar consciente sobre o Sandbox:

    Autenticação

    curl "https://sandbox.usekamba.com"
      -X GET
      -H "Authorization: Token ZVR4ZwjD2VQbDrDBrAIqqgtt"
    

    Por favor, note que as chaves de API estão ligadas à sua carteira, se você estiver usando uma conta Comerciante com vários aplicativos ou serviços clientes, o cabeçalho de autorização será o mesmo. Se por algum motivo você redefinir a sua chave de API, deve alterá-la em todos os aplicativos clientes que usam a sua conta.

    Obter a sua chave de API

    Você deve obter a sua chave enviando uma solicitação para info@usekamba.com. Lembre-se de manter a sua chave de API segura. Aqui estão algumas considerações que você deve evitar:

    Checkout

    Criar checkout

    Solicitação POST:

    curl https://sandbox.usekamba.com/v1/checkout \
        -H "Content-Type: application/json" \
        -H "Authorization: Token GeQ8j8r2VfPSUfcKVTKHxAtt" \
        -d '{
            "customer": {
                "name": "Primeiro Último",
                "phone_number": "924426615",
                "email": "cliente@email.com",
                "document_identity": {
                    "identity_type": "Bilhete de Identidade",
                    "identity_number": "123456789MJ001"
                }
            },
            "total": 10500,
            "currency": "AOA",
            "notes": "Alguma descrição...",
            "items":[{
                "name": "Curso Android para Desenvolvedores",
                "description": "Introdução ao desenvolvimento mobile com Java/Android",
                "quantity": 1,
                "price": 10500
            }],
            "shipment": {
                    "province": "Luanda",
                    "city": "Viana",
                    "district": "Condomínio 1000 Casas",
                    "street": "Rua nº 7",
                    "address": "Casa nº 424"
            },
            "redirect_url_success": "https://seusite.com/pagamento-processado"
        }'
    

    Resposta:

    {
        "id": "23ze8d9x-f03a-42f8-8464-442a679d23db",
        "created_at": "2014-03-27T15:18:09+0000",
    }
    

    POST https://sandbox.usekamba.com/v1/checkout

    Parâmetro Opcional? Descrição
    redirect_url_success Sim URL definida no cliente para qual direcionamos o comprador após um pagamento com sucesso
    items Não Uma lista com os itens na compra
    total Sim Total do pagamento
    notes Sim Descrição do pagamento
    customer Não Dados do cliente efetuando o pagamento
    currency Sim A moeda usada no pagamento

    Transações

    Exemplo do objeto JSON de uma transação.

    Uma transação representa o envio de dinheiro entre um remetente payer para um destinatário receiver. O identificador de uma transação criada com sucesso pertence a ambos. O identificador do remetente receiver pode pertencer à um usuário particular ou à um comerciante.

    Parâmetros Descrição
    id Identificador único da transação
    intent Intenção da transação
    amount Valor monetário da transação
    currency Nome da moeda
    status Estado da transação. Ex: paid
    payer_id Identificador único do remetente
    receiver_id Identificador único do destinatário
    description Descrição da transação
    transaction_type Tipo de transação. Sempre PAYMENT
    created_at Data de criação da transação

    Criar uma transação

    Exemplo de solicitação POST HTTP para obter uma transação:

    curl -X POST "https://sandbox.usekamba.com/private/v1.1/users/{user_id}/transactions" \
      -H "Authorization: Token ZVR4ZwjD2VQbDrDBrAIqqgtt" \
      -d "receiver_id=af724bac-28f9-4edf-a8f5-54a73da235ee" \
      -d "payer_id=fe99174f-6041-4z1d-a3eb-08c320e26591" \
      -d "amount=3500.00" \
      -d "description=2 pizzas!" \
      -d "intent=PAY_MERCHANT" \
      -d "checkout_id="ce99174f-6041-4z1d-a3eb-08c320e26591"
    

    Retorna o objeto JSON a seguir:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    "id": "1589de50-eb67-4a30-8628-bfec426277c3",
        "intent": "PAY_MERCHANT",
        "amount": 3500,
        "subtotal": 3500,
        "fee": 65,
        "from": {
            "id": "fe66174f-6041-4b1d-a3eb-08c320e26591",
            "firstname": "Amarildo",
            "lastname": "Lucas",
            "phone_number": "924426615",
            "email": "vmarildo@gmail.com"
        },
        "to": {
            "id": "07b543f1-d4ab-41e9-b213-6b6d72d1a26e",
            "firstname": "Fernando",
            "lastname": "Manuel",
            "phone_number": "935723275",
            "email": "fernandomanuelsancho@gmail.com"
        },
        "description": "Nota!",
        "transaction_type": "PAYMENT",
        "status": "PAID",
        "checkout_id": "ce66174f-6041-4b1d-a3eb-08c320e26591"
        "created_at": "2018-02-11T16:23:26.672Z"
    

    Envia dinheiro de um remetente para um destinatário. No caso do checkout após obter os dados de pagamento você deve enviar uma solicitação para o serviço do checkout enviando os dados do comprador e do checkout para realizar a cobrança.

    Solicitação HTTP

    Parâmetros de URL

    Parámetros Descrição
    user_id O ID do usuário remetente iniciando a transação

    Parâmetros para a solicitação HTTP

    Parâmetros Descrição
    intent Intenção da transação
    amount Valor monetário da transação
    currency Nome da moeda
    payer_id Identificador único do remetente
    receiver_id identificador único do destinatário
    description Descrição da transação
    checkout_id Identificador de checkout

    Estado HTTP e códigos de erro

    Parâmetros Descrição
    400 Transferência falhou
    403 Chave de API não autorizada