Guias

Criar subconta

POST https://api.safe2pay.com.br/v2/marketplace/add

Cria uma subconta vinculada ao seu marketplace. Autentique com o header X-API-KEY da conta marketplace. A resposta é sempre HTTP 200, verifique o campo HasError. Em caso de sucesso, ResponseDetail retorna os dados da subconta criada, incluindo os tokens de integração (Token, TokenSandbox, SecretKey, SecretKeySandbox).

Pessoa física e jurídica

Exemplo JSON

{
  "Name": "João da Silva",
  "Identity": "96260191073",
  "Email": "[email protected]",
  "ResponsibleBirthDate": "1990-05-10",
  "ResponsiblePhone": "51999999999",
  "Address": {
    "ZipCode": "90620-110",
    "Street": "Av. Ipiranga",
    "Number": "1200",
    "District": "Azenha",
    "Complement": "Sala 302"
  }
}
{
  "Name": "Empresa Exemplo LTDA",
  "CommercialName": "Loja Exemplo",
  "Identity": "74910037000193",
  "Email": "[email protected]",
  "WebsiteUrl": "https://www.exemplo.com.br",
  "ResponsibleName": "Maria Souza",
  "ResponsibleIdentity": "96260191073",
  "ResponsibleBirthDate": "1985-11-22",
  "ResponsiblePhone": "51999999999",
  "TechName": "Carlos Pereira",
  "TechIdentity": "60447379003",
  "TechEmail": "[email protected]",
  "Address": {
    "ZipCode": "90620-110",
    "Street": "Av. Ipiranga",
    "Number": "1200",
    "District": "Azenha",
    "Complement": "Conjunto 45",
    "Reference": "Próximo ao shopping"
  }
}
📘

Pessoa Física

Para CPF, ResponsibleName e ResponsibleIdentity são preenchidos automaticamente com Name e Identity quando omitidos.

Empresa

CampoTipoObrigatórioDescrição e limites
NamestringSimRazão social (PJ) ou nome completo (PF).
CommercialNamestringNãoNome fantasia.
IdentitystringSimCPF (11 dígitos) ou CNPJ (14 posições) válido. CNPJ alfanumérico é aceito. Pontuação é removida automaticamente.
EmailstringSimE-mail válido da empresa.
WebsiteUrlstringNãoMáximo de 2083 caracteres.

Responsável legal e técnico

CampoTipoObrigatórioDescrição e limites
ResponsibleNamestringSim para CNPJPara CPF, assume Name quando omitido.
ResponsibleIdentitystringSim para CNPJCPF válido (11 dígitos). Para CPF, assume Identity quando omitido.
ResponsibleBirthDatedateSimData de nascimento do responsável. Não pode ser futura nem anterior a 120 anos.
ResponsiblePhonestringNãoTelefone com DDD (10 ou 11 dígitos).
TechName / TechIdentity / TechEmailstringCondicionalResponsável técnico — disponível apenas para CNPJ. Se um dos três for informado, os três se tornam obrigatórios (TechIdentity = CPF válido; TechEmail = e-mail válido).

Endereço (Address)

CampoTipoObrigatórioDescrição e limites
ZipCodestringSimCEP. Cidade, estado e país são preenchidos automaticamente a partir dele.
StreetstringSimAté 150 caracteres (excedente é truncado). Acentos são removidos.
NumberstringSimAté 15 caracteres (truncado).
DistrictstringSimAté 60 caracteres (truncado).
ComplementstringNãoAté 150 caracteres (truncado).
ReferencestringNãoAté 150 caracteres (truncado).

Dados bancários (BankData) - opcional

Se o bloco for informado, valem as regras abaixo. A conta bancária é validada contra o histórico de transferências
recusadas.

Exemplo JSON 

{
  "BankData": {
    "Bank": { "Code": "260" },
    "AccountType": { "Code": "CC" },
    "BankAgency": "0001",
    "BankAgencyDigit": "",
    "BankAccount": "5780057",
    "BankAccountDigit": "5"
  }
}

Campos

CampoTipoObrigatórioDescrição e l
Bank.CodestringSimCódigo do banco (ex.: "001", "260", "341").
AccountType.CodestringSimTipo da conta (ex.: "CC" = Conta Corrente).
BankAgencystringSimSomente números, até 10 caracteres, diferente de "0".
BankAgencyDigitstringNão1 caractere numérico. Banco do Brasil (001) aceita também X.
BankAccountstringSimSomente números, até 15 caracteres, diferente de "0".
BankAccountDigitstringNão1 caractere numérico. Banco do Brasil (001) aceita também X.

Sobretaxa (MerchantSplit) - opcional

Exemplo JSON 

{
  "MerchantSplit": [
    {
      "PaymentMethodCode": "6",
      "IsSubaccountTaxPayer": true,
      "Taxes": [
        { "TaxTypeName": "1", "Tax": 1.90 }
      ]
    }
  ]
}
{
  "MerchantSplit": [
    {
      "PaymentMethodCode": "2",
      "IsSubaccountTaxPayer": false,
      "Taxes": [
        { "TaxTypeName": "1", "Tax": 3.50 }
      ]
    }
  ]
}

Campos

CampoTipoObrigatórioDescrição e limites
PaymentMethodCodestringSimCódigo do método/serviço (ver tabela de códigos em Configuração de sobretaxa). Deve existir e estar habilitado no marketplace. Não pode se repetir no array.
IsSubaccountTaxPayerbooleanNãotrue: a subconta paga a taxa Safe2Pay além da sobretaxa. false (default): a taxa Safe2Pay está embutida no valor informado.
Taxes[].TaxTypeNamestringSim"1" Percentual, "2" Valor (R$). Não pode se repetir no mesmo método.
Taxes[].TaxnumberSimValor da sobretaxa. Percentual: máximo 100. Sem repasse (IsSubaccountTaxPayer: false), deve ser maior ou igual à taxa que a Safe2Pay cobra de você.
📘

Defaults quando MerchantSplit é omitido

A subconta é criada com a configuração padrão de Repasse (código 26): ela paga a taxa de transferência da Safe2Pay, sem sobretaxa. As regras por método de Nota Fiscal somente em Valor, marketplaceisento) estão em Configuração de sobretaxa.

Frequência de repasse (MerchantPaymentDate) - opcional

CampoTipoObrigatórioDescrição e limites
PlanFrequence.CodestringSim (se o bloco for informado)
  • "7" diário
  • "6" semanal
  • "1" mensal
  • Default quando o bloco é omitido: diário.
PaymentDayintegerCondicional
  • Semanal ("6"): dia da semana de 2 a 6 (segunda a sexta).
  • Mensal ("1"): dia do mês de 1 a 31.
  • Diário ("7"): não in

Exemplos completos

{
    "Name": "TECIDOS FARIA DUARTE",
    "CommercialName": "TECIDOS FARIA DUARTE",
    "Identity": "74910037000193",
    "ResponsibleName": "Responsável",
    "ResponsibleIdentity": "862.811.180-81",
    "ResponsibleBirthDate": "1985-07-30",
    "ResponsiblePhone": "51999999999",
    "Email": "[email protected]",
    "BankData": {
        "Bank": {
            "Code": "260"
        },
        "AccountType": {
            "Code": "CC"
        },
        "BankAgency": "0001",
        "BankAgencyDigit": "",
        "BankAccount": "5780057",
        "BankAccountDigit": "5"
    },
    "Address": {
        "ZipCode": "90670090",
        "Street": "Logradouro",
        "Number": "123",
        "Complement": "Complemento",
        "District": "Higienopolis",
        "CityName": "Porto Alegre",
        "StateInitials": "RS",
        "CountryName": "Brasil"
    },
    "IsPanelRestricted": true, // Liberar acesso ao painel para a subconta, se true bloqueia, se false libera.
    "IsTransferCheckingAccountDisabled": false, // Desabilitar o repasse de valores da safe2pay para a conta bancária cadastrada na subconta.
    //Split estático e meios de pagamentso liberados para a subconta
    "MerchantSplit": [
        {
            "PaymentMethodCode": "1", //Boleto
            "IsSubaccountTaxPayer": false,
            "Taxes": [
                {
                    "TaxTypeName": "2",
                    "Tax": "2.20"
                }
            ]
        },
        {
            "PaymentMethodCode": "2", //Crédito
            "IsSubaccountTaxPayer": false,
            "Taxes": [
                {
                    "TaxTypeName": "1",
                    "Tax": "3.30"
                }
            ]
        },
        {
            "PaymentMethodCode": "6", //Pix
            "IsSubaccountTaxPayer": false,
            "Taxes": [
                {
                    "TaxTypeName": "2",
                    "Tax": "1.99"
                }
            ]
        },
        {
            "PaymentMethodCode": "15", //Antecipação
            "IsSubaccountTaxPayer": false,
            "Taxes": [
                {
                    "TaxTypeName": "1",
                    "Tax": "3.50"
                }
            ]
        },
        {
            "PaymentMethodCode": "16", //Antifraude - Custo de 0,50
            "IsSubaccountTaxPayer": false,
            "Taxes": [
                {
                    "TaxTypeName": "2",
                    "Tax": "0"
                }
            ]
        },
        {
            "PaymentMethodCode": "26", //Repasse - a subconta paga a taxa da Safe2Pay e mais R$ 1,00 de sobretaxa
            "IsSubaccountTaxPayer": true,
            "Taxes": [
                {
                    "TaxTypeName": "2",
                    "Tax": "1.00"
                }
            ]
        }
    ]
}
{
    "MerchantSplit": [
        {
            "PaymentMethodCode": "1", //Boleto
            "IsSubaccountTaxPayer": false,
            "Taxes": [
                {
                    "TaxTypeName": "2",
                    "Tax": "2.20"
                }
            ]
        },
        {
            "PaymentMethodCode": "2", //Crédito
            "IsSubaccountTaxPayer": false,
            "Taxes": [
                {
                    "TaxTypeName": "1",
                    "Tax": "3.30"
                }
            ]
        },
        {
            "PaymentMethodCode": "6", //Pix
            "IsSubaccountTaxPayer": false,
            "Taxes": [
                {
                    "TaxTypeName": "2",
                    "Tax": "1.99"
                }
            ]
        },
        {
            "PaymentMethodCode": "15", //Antecipação
            "IsSubaccountTaxPayer": false,
            "Taxes": [
                {
                    "TaxTypeName": "1",
                    "Tax": "3.50"
                }
            ]
        },
        {
            "PaymentMethodCode": "16", //Antifraude - Custo de 0,50
            "IsSubaccountTaxPayer": false,
            "Taxes": [
                {
                    "TaxTypeName": "2",
                    "Tax": "0"
                }
            ]
        },
        {
            "PaymentMethodCode": "26", //Repasse - a subconta paga a taxa da Safe2Pay e mais R$ 1,00 de sobretaxa
            "IsSubaccountTaxPayer": true,
            "Taxes": [
                {
                    "TaxTypeName": "2",
                    "Tax": "1.00"
                }
            ]
        }
    ]
}
{
    //A subconta paga a taxa de repasse da Safe2Pay e o marketplace não cobra sobretaxa.
    //Esta é a mesma configuração aplicada automaticamente quando o PaymentMethodCode 26 não é informado.
    "MerchantSplit": [
        {
            "PaymentMethodCode": "26", //Repasse
            "IsSubaccountTaxPayer": true,
            "Taxes": [
                {
                    "TaxTypeName": "2",
                    "Tax": "0"
                }
            ]
        }
    ]
}
{
    //O marketplace assume a taxa de repasse da Safe2Pay e recebe a NFS-e.
    //O valor informado já inclui a taxa da Safe2Pay: se ela for de R$ 2,50, a sobretaxa é de R$ 1,50.
    "MerchantSplit": [
        {
            "PaymentMethodCode": "26", //Repasse
            "IsSubaccountTaxPayer": false,
            "Taxes": [
                {
                    "TaxTypeName": "2",
                    "Tax": "4.00"
                }
            ]
        }
    ]
}
{
    //Sem o objeto MerchantSplit, a subconta é criada apenas com a taxa de repasse padrão:
    //ela paga a taxa da Safe2Pay e não há sobretaxa.
    //Para a subconta transacionar, configure os meios de pagamento pelo endpoint de alteração ou pelo painel.
    "Name": "SUBCONTA EXEMPLO",
    "CommercialName": "SUBCONTA EXEMPLO",
    "Identity": "00000000000",
    "ResponsibleName": "Responsável Exemplo",
    "ResponsibleIdentity": "00000000000",
    "ResponsibleBirthDate": "1985-07-30",
    "ResponsiblePhone": "550000000000",
    "Email": "[email protected]",
    "BankData": {
        "Bank": {
            "Code": "999"
        },
        "AccountType": {
            "Code": "CC"
        },
        "BankAgency": "0000",
        "BankAgencyDigit": "",
        "BankAccount": "0000000",
        "BankAccountDigit": "0"
    },
    "Address": {
        "ZipCode": "00000000",
        "Street": "Rua Exemplo",
        "Number": "0",
        "Complement": "Complemento Exemplo",
        "District": "Bairro Exemplo",
        "CityName": "Cidade Exemplo",
        "StateInitials": "XX",
        "CountryName": "País Exemplo"
    },
    "IsPanelRestricted": true,
    "IsTransferCheckingAccountDisabled": false
}
{
    "Name": "SUBCONTA EXEMPLO",
    "CommercialName": "SUBCONTA EXEMPLO",
    "Identity": "00000000000",
    "ResponsibleName": "Responsável Exemplo",
    "ResponsibleIdentity": "00000000000",
    "ResponsibleBirthDate": "1985-07-30",
    "ResponsiblePhone": "550000000000",
    "Email": "[email protected]",
    "BankData": {
        "Bank": {
            "Code": "999"
        },
        "AccountType": {
            "Code": "CC"
        },
        "BankAgency": "0000",
        "BankAgencyDigit": "",
        "BankAccount": "0000000",
        "BankAccountDigit": "0"
    },
    "Address": {
        "ZipCode": "00000000",
        "Street": "Rua Exemplo",
        "Number": "0",
        "Complement": "Complemento Exemplo",
        "District": "Bairro Exemplo",
        "CityName": "Cidade Exemplo",
        "StateInitials": "XX",
        "CountryName": "País Exemplo"
    },
    "IsPanelRestricted": true,
    "IsTransferCheckingAccountDisabled": true,
    "MerchantPaymentDate": {
        "PaymentDay": 20,
        "PlanFrequence": {
            "Code": 1
        }
    },
    "MerchantSplit": [
        {
            "PaymentMethodCode": "1",
            "IsSubaccountTaxPayer": false,
            "Taxes": [
                {
                    "TaxTypeName": "2",
                    "Tax": "2.20"
                }
            ]
        },
        {
            "PaymentMethodCode": "2",
            "IsSubaccountTaxPayer": false,
            "Taxes": [
                {
                    "TaxTypeName": "1",
                    "Tax": "6.00"
                }
            ]
        },
        {
            "PaymentMethodCode": "6",
            "IsSubaccountTaxPayer": false,
            "Taxes": [
                {
                    "TaxTypeName": "2",
                    "Tax": "3.60"
                }
            ]
        },
        {
            "PaymentMethodCode": "26", //Repasse - frequência mensal não gera cobrança de taxa nem sobretaxa
            "IsSubaccountTaxPayer": true,
            "Taxes": [
                {
                    "TaxTypeName": "2",
                    "Tax": "0"
                }
            ]
        }
    ]
}

Updated about 10 hours ago

Did this page help you?