6414760195
shell ruby javascript
  • 480-244-0909
  • 470-765-8375
  • (603) 695-8444
  • (903) 734-6103
  • (787) 499-3434
  • 3096768355
  • SoftPay API

    Bem-vindo ao guia de referências da API da SoftPay! É através desta API que você integra o seu sistema ao nosso. Além disso, você também pode recriar as funcionalidades existentes na nossa Dashboard, que são feitas consumindo a API que está aqui descrita.

    Nossa API é RESTful, e todas suas respostas são em JSON, no endpoint base:

    /api.softpay.com.br

    A seguir, algumas convenções de nossa API:

    Paginação

    Há muitas rotas de listagem de entidades na API. Em todas elas é necessário lidar com um sistema de paginação para percorrer todas as instâncias. Esse sistema refere-se aos parâmetros count e page.
    Count representa quantos resultados por página deverão ser retornados — se não for informado um valor, o padrão é 10.
    Page é a página a ser retornada e se não for informado um valor, o padrão é 1.

    Autenticação

    Sempre que a sua aplicação chama algum de nossos endpoints, você deve passar como forma de autenticação a sua API Key, chave que pode ser encontrada na sua Dashboard.

    A API Key pode ser informada de três forma diferentes:
    1 - No corpo da requisição como valor do parâmetro api_key
    2 - Na url (query param) como valor do parâmetro api_key
    3 - Basic Auth com username igual à chave e senha igual a x (xis minúsculo)

    Código de respostas

    Código Significado
    200 Tudo ocorreu como deveria e sua requisição foi processada com sucesso.
    400 Algum parâmetro obrigatório não foi passado, ou os parâmetros passados não estão corretos.
    401 Falta de autorização para acessar este endpoint.
    404 Endpoint não encontrado, revise a URL passada.
    500 Erro interno da SoftPay, tente sua requisição novamente. Caso o erro continue, entre em contato com suporte@SoftPay.com.br

    Erros

    require 'kittn'
    
    api = Kittn::APIClient.authorize!('meowmeowmeow')
    api.kittens.get
    
    import kittn
    
    api = kittn.authorize('meowmeowmeow')
    api.kittens.get()
    
    curl "/api.SoftPay.com.br/v2/devices2"
      -H "api_key: 2KzoP2!oPpK0mcsDemSaoE@x#"
    
    const kittn = require('kittn');
    
    let api = kittn.authorize('meowmeowmeow');
    let kittens = api.kittens.get();
    

    Exemplo de retorno de erro da API SoftPay:

    
      {
        "errors": [
        	{ 
        	  "message": "api_key não presente",
        	  "parameter_name": "api_key", 
        	  "type": "invalid_parameter"
      	}
        ],
        "method": "GET",
        "url": "/devices2"
      }
    
    Código Significado
    invalid_parameter Quando algum parâmetro passado está incorreto/faltando.
    action_forbidden Quando o usuário não tem permissão para fazer determinada ação.
    internal_error Quando algum erro interno em nosso servidor ocorreu.
    not_found Quando o recurso procurado não foi encontrado/não existe.

    Clientes

    Este endpoint é utilizado para listar seus clientes.
    GET /api.softpay.com.br/v2/merchants

    Todos os clientes

    require 'kittn'
    
    api = Kittn::APIClient.authorize!('meowmeowmeow')
    api.kittens.get
    
    import kittn
    
    api = kittn.authorize('meowmeowmeow')
    api.kittens.get()
    
    curl GET "/api.softpay.com.br/v2/clients"
      -H "api_key: 2KzoP2!oPpK0mcsDemSaoE@x#"
    
    const kittn = require('kittn');
    
    let api = kittn.authorize('meowmeowmeow');
    let kittens = api.kittens.get();
    

    Exemplo de retorno da API SoftPay:

    [
      {
        "object": "customer",
        "id": 1,
        "document_number": "325.345.302-96",
        "document_type": "cpf",
        "name": "MARCELO SOUZA",
        "email": "exemplo@SoftPay.com.br",
        "role": "MASTER",
        "status": "approved",
        "device_activation_code": "301201254",
        "max_devices": 2,
        "born_at": "1991-10-03",
        "gender": "M",
        "rg": "47.524.326-4",
        "activity_field": "1 - Processamento de dados",
        "alias": "SoftPay",
        "corporate_constitution": "1996-10-03",
        "job_description": null,
        "nationality": "Brasileiro",
        "address": null,
        "phone": null,
        "contact": null,
        "fees": null,
        "bank_account": null,
        "created_at": "2017-10-10 10:10:09",
        "updated_at": "2017-10-10 10:10:12"
      },
      {
        "object": "customer",
        "id": 1,
        "document_number": "325.345.302-96",
        "document_type": "cpf",
        "name": "MARCELO SOUZA",
        "email": "exemplo@SoftPay.com.br",
        "role": "MASTER",
        "status": "approved",
        "device_activation_code": "301201254",
        "max_devices": 2,
        "born_at": "1991-10-03",
        "gender": "M",
        "rg": "47.524.326-4",
        "activity_field": "1 - Processamento de dados",
        "alias": "SoftPay",
        "corporate_constitution": "1996-10-03",
        "job_description": null,
        "nationality": "Brasileiro",
        "address": null,
        "phone": null,
        "contact": null,
        "fees": null,
        "bank_account": null,
        "created_at": "2017-10-10 10:10:09",
        "updated_at": "2017-10-10 10:10:12"
      },
    ]
    

    Retorna um Array contendo objetos de clientes, ordenadas a partir do cliente mais recente.

    Código Significado
    id ID de identificação do cliente.
    document_number Número do CPF ou CNPJ.
    document_type Tipo de documento: CPF ou CNPJ.
    name Nome do cliente.
    email Endereço de e-mail.
    role Regra de acesso no sistema SoftPay.
    status Status atual do cliente na SoftPay.
    device_activation_code Código de ativação dos dispositivos.
    max_devices Número de equipamentos permitido para o estabelecimento.
    born_at Data de Nasc. do responsável.
    gender Sexo do responsável.
    rg RG do responsável pelo estabelecimento.
    activity_field Ramo de atividade.
    alias Nome fantasia do estabelecimento.
    corporate_constitution Data de fundação do CNPJ.
    job_description Ramo do responsável.
    nationality Nacionalidade do responsável.
    address Endereço comercial do Estabelecimento.
    phone Telefone comercial do Estabelecimento.
    contact Objeto contendo os dados de contato do Estabelecimento.
    fees Objeto contendo as taxas acordadas no Estabelecimento.
    bank_account Objeto contendo os dados bancários.
    created_at Data de cadastro do estabelecimento
    updated_at Última atualização no cadastro do estabelecimento.

    Operações de saldo

    Este endpoint é utilizado para retornar um objeto saldo com: saldo disponível, à receber e transferido:

    GET /api.SoftPay.com.br/v2/recipient/balance

    Retornando saldo disponível

    require 'kittn'
    
    api = Kittn::APIClient.authorize!('meowmeowmeow')
    api.kittens.get
    
    import kittn
    
    api = kittn.authorize('meowmeowmeow')
    api.kittens.get()
    
    curl "/api.SoftPay.com.br/v2/recipient/balance"
      -H "api_key: 2KzoP2!oPpK0mcsDemSaoE@x#"
    
    const kittn = require('kittn');
    
    let api = kittn.authorize('meowmeowmeow');
    let kittens = api.kittens.get();
    

    Exemplo de retorno de erro da API SoftPay:

    
      {
        "object": "balance",
        "waiting_funds": { 
        	"amount": 1000
        },
        "available": { 
        	"amount": 982
        },
        "transferred": { 
        	"amount": 0
        }
      }
    

    Utilize a rota /recipient/balance para retornar um objeto com as informações de saldo da sua conta.

    Código Significado
    object Objeto 'balance' retornado.
    waiting_funds Saldo à receber da SoftPay.
    available Saldo disponível para saque.
    transferred Saldo transferido para sua conta bancária.

    Criando uma transação

    require 'kittn'
    
    api = Kittn::APIClient.authorize!('meowmeowmeow')
    api.kittens.get
    
    import kittn
    
    api = kittn.authorize('meowmeowmeow')
    api.kittens.get()
    
    curl POST "/api.SoftPay.com.br/v2/transactions"
      -H "api_key: 2KzoP2!oPpK0mcsDemSaoE@x#",
         "type: credit_card",
         "amount: 1500",
         "installment: 1",
         "SoftDescriptor: CAIOPNEU",
         "card[cardNumber]: 3021630274853621",
         "card[holderName]: MARCELO E DINIZ",
         "card[expirationDate]: 1123",
         "card[securityCode]: 316",
         "card[brand]: visa"
    
    const kittn = require('kittn');
    
    let api = kittn.authorize('meowmeowmeow');
    let kittens = api.kittens.get();
    

    Exemplo de retorno da API SoftPay:

    [
      {
        "object": "transaction",
        "id": 1,
        "cost": 367,
        "Installments": 1,
        "capture": "false",
        "authenticate": "false",
        "nsu": 03690145,
        "Tid": 6301201,
        "authorizationCode": 301201254,
        "paymentId": "fc31-4d6c-8555",
        "type": "credit_card",
        "amount": 1000,
        "status": "approved",
        "cardNumber": "406726******3102",
        "holderName": "MARCELO S DINIZ",
        "expirationDate": 0321,
        "saveCard": "false",
        "brand": "visa",
        "created_at": "2017-10-10 10:10:09",
        "updated_at": "2017-10-10 10:10:12"
      }
    ]
    

    Este endpoint é utilizado para criar uma transação.
    POST /api.SoftPay.com.br/v2/transactions

    Para fazer uma cobrança você deve usar a rota /transactions para criar a sua transação. Por enquanto, aceitamos apenas transação por cartão de crédito.

    Código Significado
    api_key Chave de acesso disponibilizada na sua dashboard.
    type Tipo de pagamento, sendo permitido apenas credit_card.
    amount Valor da transação, em centavos.
    installments Quantidade de parcelas, sendo 1 até 12.
    SoftDescriptor Informação a ser exibida na fatura do cliente.
    card[Number] Número do cartão de crédito.
    card[holderName] Nome impresso no cartão de crédito.
    card[expirationDate] Data de validade do cartão de crédito.
    card[securityCode] Código de 3 dígitos do verso do cartão.
    card[brand] Bandeira do cartão de crédito.

    Todas as transações

    Este endpoint é utilizado para consultar transações.
    GET /api.SoftPay.com.br/v2/transactions


    Retorna um Array contendo objetos de transações, ordenadas a partir da transação realizada mais recentemente.

    Todas as transações

    require 'kittn'
    
    api = Kittn::APIClient.authorize!('meowmeowmeow')
    api.kittens.get
    
    import kittn
    
    api = kittn.authorize('meowmeowmeow')
    api.kittens.get()
    
    curl GET "/api.SoftPay.com.br/v2/transactions"
      -H "api_key: 2KzoP2!oPpK0mcsDemSaoE@x#"
    
    const kittn = require('kittn');
    
    let api = kittn.authorize('meowmeowmeow');
    let kittens = api.kittens.get();
    

    Exemplo de retorno da API SoftPay:

    [
      {
        "object": "transaction",
        "id": 1,
        "card_id": "card_cj8eij7fr20zdua5yrs0jc0up",
        "status": "paid",
        "refuse_reason": null,
        "acquirer_response_code": 0,
        "acquirer_name": "SoftPay",
        "acquirer_id": 6,
        "authorization_code": 7,
        "soft_descriptor": "SoftPay",
        "tid": 03201,
        "nsu": 10032,
        "amount": 6000,
        "authorized_amount": 6000,
        "paid_amount": 6000,
        "refunded_amount": 0,
        "installments": 1,
        "cost": 180,
        "card_holder_name": "LUCAS R ALMEIDA",
        "card_first_digits": "455181",
        "card_last_digits": "7864",
        "card_brand": "VISA",
        "card_pin_mode": null,
        "payment_method": "credit_card",
        "capture_method": "emv",
        "referer": "api_key",
        "ip": null,
        "subscription_id": null,
        "created_at": "2017-10-05 13:23:21",
        "updated_at": "2017-10-05 13:23:23",
        "split_rules": null,
        "card": null
      },
      {
        "object": "transaction",
        "id": 1,
        "card_id": "card_cj8eij7fr20zdua5yrs0jc0up",
        "status": "paid",
        "refuse_reason": null,
        "acquirer_response_code": 0,
        "acquirer_name": "SoftPay",
        "acquirer_id": 6,
        "authorization_code": 7,
        "soft_descriptor": "SoftPay",
        "tid": 03201,
        "nsu": 10032,
        "amount": 6000,
        "authorized_amount": 6000,
        "paid_amount": 6000,
        "refunded_amount": 0,
        "installments": 1,
        "cost": 180,
        "card_holder_name": "LUCAS R ALMEIDA",
        "card_first_digits": "455181",
        "card_last_digits": "7864",
        "card_brand": "VISA",
        "card_pin_mode": null,
        "payment_method": "credit_card",
        "capture_method": "emv",
        "referer": "api_key",
        "ip": null,
        "subscription_id": null,
        "created_at": "2017-10-05 13:23:21",
        "updated_at": "2017-10-05 13:23:23",
        "split_rules": null,
        "card": null
      },
    ]
    
    Código Significado
    api_key Chave de acesso disponibilizada na sua dashboard.
    count Quantidade de transações a serem retornadas. Limite 1000.
    page Útil para implementação de uma paginação de resultados.
    date_created Filtro de data de criação da transação, podendo ser nulo.
    date_updated Filtro da última atualização da transação, podendo ser nulo.
    amount Filtro valor da transação, podendo ser nulo.
    authorized_amount Valor autorizado para cobrança.
    paid_amount Valor pago pelo cliente.
    refunded_amount Valor estornado para o cliente.
    installments Quantidade de parcelas.
    cost Valor cobrado pela SoftPay.
    card_holder_name Nome do portador do cartão.
    card_first_digits 6 primeiros dígitos do cartão.
    card_brand Bandeira do cartão.
    card_pin_mode Valores possíveis: online / offline.
    payment_method Valores possíveis: credit_card, debit_card.
    capture_method Valores possíveis: emv, ecommerce e boleto.
    referer Referência para controle.
    ip IP de onde partiu a requisição.
    subscription_id Número do pedido.
    created_at Data da criação da transação.
    updated_at Última atualização da transação.
    split_rules Objeto contendo as regras de divisão.
    card Objeto contendo os dados do cartão.

    Retornando uma transação

    require 'kittn'
    
    api = Kittn::APIClient.authorize!('meowmeowmeow')
    api.kittens.get
    
    import kittn
    
    api = kittn.authorize('meowmeowmeow')
    api.kittens.get()
    
    curl GET "/api.SoftPay.com.br/v2/transactions/$id"
      -H "api_key: 2KzoP2!oPpK0mcsDemSaoE@x#"
    
    const kittn = require('kittn');
    
    let api = kittn.authorize('meowmeowmeow');
    let kittens = api.kittens.get();
    

    Exemplo de retorno da API SoftPay:

    [
      {
        "object": "transaction",
        "id": 1,
        "card_id": "card_cj8eij7fr20zdua5yrs0jc0up",
        "status": "paid",
        "refuse_reason": null,
        "acquirer_response_code": 0,
        "acquirer_name": "SoftPay",
        "acquirer_id": 6,
        "authorization_code": 7,
        "soft_descriptor": "SoftPay",
        "tid": 03201,
        "nsu": 10032,
        "amount": 6000,
        "authorized_amount": 6000,
        "paid_amount": 6000,
        "refunded_amount": 0,
        "installments": 1,
        "cost": 180,
        "card_holder_name": "LUCAS R ALMEIDA",
        "card_first_digits": "455181",
        "card_last_digits": "7864",
        "card_brand": "VISA",
        "card_pin_mode": null,
        "payment_method": "credit_card",
        "capture_method": "emv",
        "referer": "api_key",
        "ip": null,
        "subscription_id": null,
        "created_at": "2017-10-05 13:23:21",
        "updated_at": "2017-10-05 13:23:23",
        "split_rules": null,
        "card": null
      }
    ]
    

    Retorna os dados de uma transação em específico, com as informações em um único objeto.

    Endpoint utilizado para consultar uma determinada transação:
    GET /api.SoftPay.com.br/v2/transactions/$id

    Código Significado
    api_key Chave de acesso disponibilizada na sua dashboard.
    id ID da transação que deseja consultar.

    Recebíveis

    Objeto contendo os dados de um recebível. O recebível (payable) é gerado automaticamente após uma transação ser paga. Para cada parcela de uma transação é gerado um recebível, que também pode ser dividido por recebedor (no caso de um split ter sido feito).

    Retornando recebíveis

    require 'kittn'
    
    api = Kittn::APIClient.authorize!('meowmeowmeow')
    api.kittens.get
    
    import kittn
    
    api = kittn.authorize('meowmeowmeow')
    api.kittens.get()
    
    curl GET "/api.SoftPay.com.br/v2/recipient/payables"
      -H "api_key: 2KzoP2!oPpK0mcsDemSaoE@x#"
    
    const kittn = require('kittn');
    
    let api = kittn.authorize('meowmeowmeow');
    let kittens = api.kittens.get();
    

    Exemplo de retorno da API SoftPay:

    [
      {
        "object": "payable",
        "id": 1,
        "split_rule_id": "sr_cj2e8c1t20479615zkz0t72tr",
        "status": "paid",
        "amount": 3000,
        "fee": 009,
        "anticipation_fee": null,
        "installment": 1,
        "payment_date": "2017-10-05 16:19:22",
        "original_payment_date": "2017-10-05 16:19:22",
        "type": "credit",
        "payment_method": "credit_card",
        "created_at": "2017-10-03 16:19:22",
        "updated_at": "2017-10-04 16:19:22",
      }
    ]
    

    Endpoint utilizado para consultar os payables:
    GET /api.SoftPay.com.br/v2/recipient/payables

    Código Significado
    api_key Chave de acesso disponibilizada na sua dashboard.
    object Tipo de objeto retornado.
    bulk_anticipation_id Código de antecipação do recebível.
    split_rule_id Código de identificação da regra de divisão.
    status Situação do recebível.
    amount Valor do recebível.
    bulk_anticipation_id Código de antecipação do payable.
    fee Valor cobrado pela SoftPay.
    anticipation_fee Custo de antecipação.
    installment Parcela da transação.
    payment_date Data de pagamento do recebível, se antecipado.
    original_payment_date Data de pagamento do recebível, sem antecipar.
    type Tipo de recebível.
    payment_method Forma de pagamento.
    created_at Data de criação do Payable.
    updated_at Data de atualização do Payable.

    Recebíveis de uma transação

    require 'kittn'
    
    api = Kittn::APIClient.authorize!('meowmeowmeow')
    api.kittens.get
    
    import kittn
    
    api = kittn.authorize('meowmeowmeow')
    api.kittens.get()
    
    curl GET "/api.SoftPay.com.br/v2/recipient/payables"
      -H "api_key: 2KzoP2!oPpK0mcsDemSaoE@x#"
    
    const kittn = require('kittn');
    
    let api = kittn.authorize('meowmeowmeow');
    let kittens = api.kittens.get();
    

    Exemplo de retorno da API SoftPay:

    [
      {
        "object": "payable",
        "id": 1,
        "split_rule_id": "sr_cj2e8c1t20479615zkz0t72tr",
        "status": "paid",
        "amount": 3000,
        "fee": 009,
        "anticipation_fee": null,
        "installment": 1,
        "payment_date": "2017-10-05 16:19:22",
        "original_payment_date": "2017-10-05 16:19:22",
        "type": "credit",
        "payment_method": "credit_card",
        "created_at": "2017-10-03 16:19:22",
        "updated_at": "2017-10-04 16:19:22",
      }
    ]
    

    Retorna um objeto recebível (payable) informando os dados de um pagamento referente a uma transação em específico.

    Rota utilizada para retornar os recebíveis de uma transação:
    GET /api.SoftPay.com.br/v2/recipient/payables/$id

    Código Significado
    api_key Chave de acesso disponibilizada na sua dashboard.
    transaction_id ID da transação.

    Agenda de recebíveis

    require 'kittn'
    
    api = Kittn::APIClient.authorize!('meowmeowmeow')
    api.kittens.get
    
    import kittn
    
    api = kittn.authorize('meowmeowmeow')
    api.kittens.get()
    
    curl GET "/api.SoftPay.com.br/v2/payables/receivables"
      -H "api_key: 2KzoP2!oPpK0mcsDemSaoE@x#"
    
    const kittn = require('kittn');
    
    let api = kittn.authorize('meowmeowmeow');
    let kittens = api.kittens.get();
    

    Exemplo de retorno da API SoftPay:

    [
      {
        "object": "receivables_schedule",
        "2017-10-18": {
            "debit": 2230,
            "credit": 3260,
            "refund": 3000,
            "total": 009
           }
        }
    ]
    

    Objeto contendo sua agenda de pagamentos. Utilize essa rota para visualizar a data de seus recebíveis (Crédito e Débito).

    Endpoint utilizado para retornar a agenda de recebíveis:
    GET /api.SoftPay.com.br/v2/payables/receivables

    Código Significado
    api_key Chave de acesso disponibilizada na sua dashboard.
    object Tipo de objeto retornado.
    date Data do pagamento. Retornado dentro do objeto
    debit Valor dos pagamentos dos recebíveis débito.
    credit Valor dos pagamentos dos recebíveis crédito.
    refund Valor dos pagamentos dos recebíveis estornados.
    total Total de todos os recebíveis.

    Dispositivos

    Utilize essa rota para visualizar todos os dispositivos autorizados a transacionar com a SoftPay.

    Endpoint utilizado para informações sobre dispositivos:
    /api.SoftPay.com.br/v2/devices

    Código Significado
    api_key Chave de acesso disponibilizada na sua dashboard.
    object Tipo de objeto retornado.
    serial_number Número de série do dispositivo
    status Status do dispositivo na base da SoftPay
    manufacturer Fabricante do dispositivo.
    model Modelo do dispositivo.
    ativo Se o dispositivo está liberado para transacionar.
    created_at Data de cadastro do dispositivo
    updated_at Última atualização do dispositivo