Informações e personalização da conta

Consulte a agência e o número da conta financeira da sua empresa na Raims. Você também pode conferir as condições comerciais para estimar os custos de recebimento na integração e configurar as imagens, as cores e o contato de suporte apresentados no checkout.

Recuperar número de conta

Use Recuperar número de conta, com GET /v1/accounts/account_number, para obter agency e account da conta financeira da própria empresa. A requisição usa a empresa identificada pela chave de API e não recebe parâmetros nem corpo.

Essa consulta exige uma chave de Produção e uma conta financeira aprovada e habilitada. O Sandbox não possui agência e conta financeira e retorna 403 DATA_ENVIRONMENT_NOT_SUPPORTED. O console desta documentação aceita somente chaves Sandbox; consulte os dados pelo servidor da sua integração, sem inserir uma chave de Produção na documentação ou no navegador.

Se a conta não estiver aprovada e habilitada, ou os dados não estiverem disponíveis, a resposta será 404 ACCOUNT_NUMBER_NOT_AVAILABLE. Confira a situação da conta no Dashboard antes de tentar novamente.

Preserve agência e conta como texto, incluindo zeros à esquerda e a formatação retornada. A consulta não cadastra uma conta nem altera o destino dos saques.

Consultar tarifas da conta

Use Consultar tarifas da conta, com GET /v1/accounts/fees. A resposta reúne as regras vigentes de Pix e boleto no plano selecionado pela empresa.

A consulta não altera o plano nem as tarifas. Os valores atuais também não informam qual tarifa foi aplicada a uma transação antiga. Para conferir uma tarifa já cobrada, consulte os lançamentos do Extrato.

Entender os valores

Cada meio de pagamento retorna a parcela percentual, o valor fixo e os limites de tarifa que estiverem configurados:

Um valor de 85 em um campo de centavos representa R$ 0,85. Um campo null indica que aquela parcela ou limite não está configurado. As parcelas percentual e fixa podem estar presentes na mesma regra.

Se pix ou boleto for null, não há uma regra vigente para esse meio no plano selecionado. Isso não significa que o recebimento seja gratuito. A presença de uma regra também não confirma que o meio esteja habilitado para receber pagamentos.

Personalização do checkout

Use Consultar personalização do checkout para conferir as imagens, as cores, o e-mail de suporte e os meios de pagamento padrão da empresa no ambiente da chave. Sandbox e Produção têm configurações separadas; uma alteração em um ambiente preserva a configuração do outro.

Para alterar as cores ou o contato, use Atualizar personalização do checkout. Envie hex_primary_color para a cor principal e hex_secondary_color para a cor de fundo, no formato #RRGGBB. Omitir um campo preserva seu valor. Em support_email, null ou texto vazio remove o contato de suporte. As cores precisam continuar preenchidas com valores válidos. Um corpo vazio mantém a configuração atual.

payment_method_types informa os meios padrão habilitados e disponíveis para o checkout. A atualização pela API não altera essa lista. Para escolher Pix e boleto, use

Conta, Configurações, Checkout de pagamentos.

O padrão de meios da conta se aplica quando a cobrança e o link não têm uma configuração própria. Alterar esse padrão pode mudar as opções das cobranças que o utilizam. Uma lista própria da cobrança continua valendo; o link pode restringir essas opções. Consulte Checkout e formas de pagamento.

Essas preferências não alteram valor, vencimento ou situação de uma cobrança e não confirmam pagamento. A consulta retorna a configuração atual; ela não informa qual aparência estava em uso em uma data passada.

Logo e ícone do checkout

O envio de cada imagem tem três etapas:

1. Use Preparar envio da logo ou Preparar envio do ícone. Informe o tipo, o tamanho em bytes, a largura e a altura do arquivo. PNG e JPEG são aceitos; o ícone precisa ser quadrado. Confira os limites nos parâmetros do endpoint correspondente.
2. Envie os bytes do arquivo para upload_url, com o método PUT. Use Content-Type e Content-Length conforme content_type e file_size da resposta. Não envie a chave de API Raims nesse endereço. A URL é temporária. Conclua o envio e a associação antes de expires_at, informado em segundos Unix UTC.
3. Use Atualizar personalização do checkout e informe o id recebido em logo_upload_id ou favicon_upload_id. Os dois campos são independentes. Use um envio de logo no campo da logo e um envio de ícone no campo do ícone, sempre na mesma empresa e ambiente.

Obter a URL ou concluir o PUT não altera a imagem apresentada no checkout. A associação pelo PATCH pode retornar 202 enquanto a imagem é verificada. Consulte a configuração para acompanhar logo.status e favicon.status:

url apresenta a imagem atual ou null quando não houver uma disponível. Durante o processamento ou após uma falha, a imagem anterior continua em uso, quando existir. A nova imagem passa a ser usada quando a alteração termina com status: ready.

Se precisar repetir o PATCH enquanto a imagem está em processamento, use o mesmo ID de envio. Um envio que falhou ou já foi substituído não pode ser aplicado novamente. Prepare um novo envio para trocar a imagem outra vez. Quando error_code estiver preenchido, confira o motivo:

Remover imagem do checkout

Para remover uma imagem, envie logo_upload_id: null ou favicon_upload_id: null. Omitir esses campos preserva as imagens atuais. Uma remoção também pode ficar em processamento; ela termina com status: absent. Essa configuração também pode ser feita pelo Dashboard, na seção de aparência do checkout.

Descartar envio não utilizado

Se desistir de um envio antes de associá-lo, use Descartar envio de imagem, com o mesmo id retornado na preparação. O descarte também aceita uma autorização expirada. A resposta deleted: true confirma que o envio foi descartado e não pode mais ser aplicado; repetir o descarte conserva esse resultado. Um envio já associado ao checkout não pode ser descartado por esse endpoint. Para remover a imagem, use o PATCH com o campo correspondente em null.

Empresa e ambiente

As consultas identificam a empresa pela chave de API. Você não precisa informar o identificador da empresa na requisição.

As tarifas são compartilhadas entre Sandbox e Produção. Uma chave Sandbox consulta as mesmas regras da empresa, enquanto os pagamentos de teste continuam separados das movimentações reais.

Proteja a chave no servidor da sua integração. Trate os erros pelo status HTTP e por error.code, conforme Códigos HTTP das respostas.