Bem-vindo ao guia de referências da API da Marlim.co! Nossa API é RESTful e é através dela que você integra o seu sistema ao nosso.
\n\nSe você tiver alguma sugestão, reclamação ou dúvida sobre qualquer procedimento, por favor entre em contato conosco. Estamos em constante aprimoramento e te ouvir é muito importante para nós.
\n\nTodas as chamadas a nossa API são utilizando o método POST e todas as respostas retornam em formato JSON, no endpoint base:
\n\n https://api.marlim.co/\n\nnull, undefined ou string vazia. Caso você passe um parâmetro com algum desses 3 valores, irá retornar um erro. Se o parâmetro não for obrigatório e você não quiser que ele seja computado, basta remover da request.Sempre que a sua aplicação chama algum de nossos endpoints, você deve passar como forma de autenticação a sua API Key adicionada ao Header da requisição, utilizando o seguinte formato:
\n\n api_key: sua_api_key_value\n\nPara transacionar com a Marlim.co você tem acesso a duas Chaves de API distintas, uma para teste e outra para produção. Dessa forma, o endpoint é o mesmo, sendo possível diferenciar o ambiente apenas escolhendo a chave apropriada para o tipo de operação que você deseja fazer.
\n\nNossa API usa como retorno os códigos HTTP padrão para indicar tanto o sucesso de uma requisição, quanto para indicar falha. Segue:
\n\n| 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. |
403 | O valor passado no parâmetro está incorreto. |
404 | Endpoint ou algum valor não encontrado. |
405 | Método não autorizado. |
500 | Erro interno da Marlim.co, tente novamente. Caso continue, entre em contato conosco. |
Todos os erros retornam um objeto ERRORS com duas propriedades: type e message como forma de auxiliar a identificar o possível motivo do erro, como no exemplo abaixo:
{\n \"errors\": {\n \"type\": \"card_brand\",\n \"message\": \"This card brand is not accepted or an incorrect value has been passed.\"\n }\n }\n\nÀ partir de 01/09/2021 entrará no ar a v2 da nossa API. Enquanto que a v1 entrará em depreciação em 01/01/2022, retornando o código 404 (Not Found) nos antigos endpoints.
Deve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"urlencoded","urlencoded":[{"description":"Valor a ser cobrado. Deve ser passado em centavos. Ex: R$ 1.000,00 = 100000.
\nValores aceitos:
\n\n• visa
\n• mastercard
\n• amex
\n• elo
\n• hipercard\n
Para facilitar o Front-End, opcionalmente você pode passar esse parâmetro para retornar os valores parceados em Real Brasileiro (BRL).
\nA Marlim fornece ao seu cliente a opção de parcelar a compra de moedas estrangeiras em até 12x. Utilize esse endpoint para retornar os valores das parcelas e as taxas ao mês.
\n\n| Atributo | Obrigatório | Tipo |
|---|---|---|
amount | sim | int32 |
card_brand | sim | string |
pt_br | não | boolean |
Deve ser passado no HEADER da requisição.
","type":"text"}],"body":{"mode":"urlencoded","urlencoded":[{"description":"Valores aceitos:
\n\n• remittance (remessa)
\n• currency_exchange (papel moeda)
\n
Valor a ser cobrado. Deve ser passado em centavos. Ex: R$ 1.000,00 = 100000.
\nNúmero de parcelas da transação, sendo mínimo: 1 e Máximo: 12.
\nID da transação na sua plataforma.
\nPATH URL no browser do cliente pagador que origina a transação.
\nValor transacionado da moeda estrangeira. Ex: 500 Dólares Americanos, deve ser passado como 50000 (mesmo formato do amount, em centavos)
\nValores aceitos:
\n\n• AED
\n• ARS
\n• AUD
\n• BRL
\n• CAD
\n• CHF
\n• CLP
\n• CNY
\n• COL
\n• DKK
\n• EUR
\n• GBP
\n• ILS
\n• JPY
\n• MXN
\n• NOK
\n• NZD
\n• PEN
\n• RUB
\n• SEK
\n• USD
\n• UYU
\n• ZAR
\n
Valor líquido da transação: (valor do câmbio + IOF), sem contar as taxas de adquirência. OBS: O Valor máximo permitido por transação é de 6000000 (R$ 60.000,00)
\nHash de um cartão criptografado manualmente usando uma chave pública. Caso inclua um card_id ou os dados do cartão esse campo torna-se dispensável.
\nAo realizar uma transação, retornamos o card_id do cartão, para que nas próximas transações ele possa ser utilizado como forma de identificar os dados de pagamento. Exemplo de utilização: One-click buy. Caso inclua os dados do cartão, ou um card_hash esse campo torna-se dispensável.
\nNome do portador do cartão
\nNúmero do cartão
\nData de validade do cartão. Somente números no formato MMAA
\nCódigo verificador do cartão
\nIdentificador do cliente em sua plataforma.
\nNome do cliente
\nNúmero do documento do cliente.
\nIMPORTANTE: Se o comprador for de nacionalidade Brasileira (customer.address.country === 'br'), deve ser passado o CPF do mesmo. Caso seu cliente seja estrangeiro, deve ser passado o número identificador (national identification number).
\nE-mail do cliente
\nNúmero de telefone do cliente.
\nIMPORTANTE: Se o comprador for de nacionalidade Brasileira (customer.address.country === 'br'), deve ser passado no formato +55DDXXXXXXXXX. Caso seu cliente seja estrangeiro, deve ser passado no padrão regex /^\\+(?:[0-9] ?){6,14}[0-9]$/]]
\nNacionalidade do cliente, no formato sigla do país. Só serão aceitos o formato ISO 3166-1 alfa-2 (duas-letras) Ex: br, us, uy.... Máximo: 2 caracteres.
\nEstado do atual endereço do cliente, no formato sigla do estado. Ex: SP, RJ, MG... Máximo: 2 caracteres.
\nCidade do endereço do cliente. Máximo: 50 caracteres.
\nBairro do endereço do cliente. Máximo: 45 caracteres.
\nNome da Rua do endereço do cliente. (Não é necessário passar número nem complemento). Máximo: 54 caracteres.
\nCEP (clientes nacionais) ou ZIP (clientes estrangeiros) do cliente. Somente números - Máximo: 9 caracteres.
\nDescrição que aparecerá na fatura do seu cliente. Máximo de 13 caracteres, sendo alfanuméricos e espaços.
\nEndpoint do seu sistema que receberá informações a cada atualização da transação.
\nParametro opicional da data de abertura do cadastro do usuário na sua plataforma no formato ISODateTime. Ex: 2023-01-01T00:00:00.000Z
","type":"text"},{"key":"customer_first_transaction_date","value":"dateTime","description":"Parametro opicional da data da primeira operação concretizada (paga) na sua plataforma, independente de ter sido processada pela Marlim ou não, no formato ISODateTime. Ex: 2023-02-01T00:00:00.000Z
","type":"text"},{"key":"customer_last_transaction_date","value":"dateTime","description":"Parametro opicional da data da última operação concretizada (paga) na sua plataforma, independente de ter sido processada pela Marlim ou não, no formato ISODateTime. Ex: 2023-02-01T00:00:00.000Z
","type":"text"},{"key":"customer_paid_proposals","value":"int32","description":"Parametro opicional da quantidade de propostas concretizadas (pagas) pelo cliente na sua plataforma, independente de ter sido processada pela Marlim ou não. Ex: 150
","type":"text"}]},"url":"https://api.marlim.co/v2/transactions","description":"Para fazer uma cobrança você deve utilizar essa rota e criar a sua transação.
\n\nÉ possível utilizar um card_hash, card_id ou todos os dados do cartão diretamente. A primeira opção é a mais indicada, por fatores de segurança. Toda vez que for realizado uma transação com sucesso em nossos sistemas será retornado um card_id que poderá ser utilizado em compras futuras. Assim utilizando o card_hash na primeira compra e um card_id nas compras futuras você incrementa ainda mais a segurança dos dados do seu cliente.
A Marlim é uma empresa PCI Compliance, ou seja, somos auditados para seguir todas as regras de segurança de mercado que visam proteger os dados dos cartões dos seus clientes. Caso seu sistema não esteja habilitado para criar o card_hash, você pode transacionar tranquilamente com os dados abertos de cartão, uma vez que nossos sistemas criptografam todos os dados e somente nosso Adquirente (quem processa o pagamento junto ao Banco Emissor) é que tem acesso aos dados reais do cartão.
No link a seguir da nossa documentação, descrevemos o passo a passo de como criar um card_hash :Como criar um Card Hash Key
| Atributo | Obrigatório | Tipo |
|---|---|---|
type | sim | string |
amount | sim | int32 |
installments | sim | string |
item_id | sim | string |
item_url | não | string |
currency_amount | sim | int32 |
currency_abbreviation | sim | string |
net_value | sim | int32 |
card_hash | sim | string |
card_id | sim | string |
card_holder_name | sim | string |
card_number | sim | string |
card_expiration_date | sim | string |
card_cvv | sim | string |
customer | sim | object |
customer[external_id] | sim | string |
customer[name] | sim | string |
customer[document_number] | sim | string |
customer[email] | sim | string |
customer[phone_number] | sim | string |
customer[address] | sim | object |
customer[address][country] | sim | string |
customer[address][state] | sim | string |
customer[address][city] | sim | string |
customer[address][neighborhood] | sim | string |
customer[address][street] | sim | string |
customer[address][zipcode] | sim | string |
soft_descriptor | sim | string |
postback_url | não | string |
Como forma de melhoria na taxa de aprovação/conversão dos clientes, foram criados alguns parâmetros extras que podem ser enviados na request de criação de transação. Essa lista pode crescer ao longo do tempo, abaixo segue a lista de itens que já foram criados e já estão disponiveis para implementação na API:
\n\n| Atributo | Tipo | Descrição |
|---|---|---|
customer_registration_date | dateTime | Data de abertura do cadastro do usuário na sua plataforma no formato ISODateTime. |
customer_first_transaction_date | dateTime | Data da primeira operação concretizada (paga) na sua plataforma, independente de ter sido processada pela Marlim ou não, no formato ISODateTime. |
customer_last_transaction_date | dateTime | Data da última operação concretizada (paga) na sua plataforma, independente de ter sido processada pela Marlim ou não, no formato ISODateTime. |
customer_total_transactions | int32 | Quantidade de propostas efetivadas (pagas) pelo cliente na sua plataforma, desconsiderando aquelas que tenham sido processadas pela Marlim. Exemplo: Se o CPF na sua base possui 3 compras efetivadas e pagas via PIX, e 10 compras efetivadas e pagas via Marlim, o valor do parâmetro a ser enviado deve ser 3 (referentes às operações pagas via PIX). |
🚨 O formato ISODateTime que a Marlim espera é: YYYY-MM-DDTHH:mm:sssZ, por exemplo: 2023-01-01T00:00:000Z. Algo similar ao método toISOString() do Javascript (new Date().toISOString()).
Todo o processo de mudança de status de uma transação é assíncrono. Por isso, é importante que você passe um postback_url durante o processo de criação de uma transação para que sua aplicação receba todas as mudanças de status (similar a webhooks). Esses status, possuem 2 contextos: old_status (o status anterior) e current_status (o status mais atual). Abaixo, a tabela com os valores possíveis de status.
| Valor | Significado |
|---|---|
processing | A request entrou em uma fila de requisições e a transação está em processo de autorização. |
paid | Transação paga. Foi autorizada e capturada com sucesso. |
review | Transação está em processo de revisão manual pelos nossos especialistas. O valor foi apenas autorizado e reservado no cartão, mas ainda não foi capturado. |
refused | Transação recusada pelo Banco Emissor. |
rejected | Transação não autorizada pelo Antifraude Marlim. |
refunded | Transação estornada. |
chargeback | Transação sofreu chargeback. |
Abaixo, um exemplo do objeto de atualização do status de uma transação passado pela Marlim via POST para a sua aplicação:
\n\n{\n marlim_post_back: {\n transaction_id: '31071980',\n fingerprint: 'hJP62s5a1fzHE00n4c0pys1efavn73qyzbul7t12',\n event: 'transaction_status_changed',\n old_status: 'review',\n desired_status: 'paid',\n current_status: 'paid',\n status: 'paid',\n acquirer_id: 'mqq9yyncja8vuxsjn2bivc76',\n authorization_code: '123123',\n date_created: '2020-01-01T00:10:00.000Z',\n date_updated: '2020-01-01T02:30:00.000Z',\n amount: '856618',\n paid_amount: '856618',\n refunded_amount: '0',\n postback_url: 'https://seusite.com/postback_url',\n ip: '999.999.999.999',\n card_holder_name: 'Harry J. Potter',\n card_last_digits: '2122',\n card_brand: 'visa'\n item_id: '123456789',\n }\n}\n\n🚨 Todos os valores enviados via postback_url são formatados como tipo String
Em caso de uma transação ser recusada pelo Banco Emissor é retornado o status refused com a propriedade acquirer_status_code contendo o código dessa recusa. Como cada bandeira de cartão bem como o banco emissor pode ter um código diferente, a Marlim agrupa o contexto dessa recusa de acordo com a tabela abaixo. No futuro podem ser incluídos novos códigos, uma vez que esse controle está com as bandeiras e os bancos.
| Prefixo | Significado |
|---|---|
0000 | Transação autorizada, capturada ou estornada. |
1000 | Transação não aprovada pelo banco. |
1011 | Dados incorretos do cartão. |
1016 | Cartão sem saldo. |
5000 | Erro bancário genérico. O cliente deve entrar em contato com o Banco Emissor. |
Exemplo de uso:
Cliente deseja comprar USD 1.000 (mil dólares) a uma taxa de 4,50 (valor com IOF) em 3x no cartão VISA.
currency_amount : 100000 (total em moeda: USD 1.000)
net_value : 450000 (USD 1.000 x 4,50 do IOF: R$ 4.500,00)
amount : 503919 (total contando as parcelas: R$ 5.039,19)
Para que o seu E-commerce funcione corretamente com o Antifraude da Marlim, é importante você passar o valor do PATH URL do browser do cliente pagador que origina a transação no parâmetro item_url.
Geralmente é o último item em window.location.pathname no browser. Por exemplo se URL do pedido do seu cliente for:https://seusite.com/pedido/123456789deve ser passado o valor 123456789.
Além disso, deve ser instalado um pequeno script da Marlim no HEAD do seu site, seguindo essa parte na nossa documentação:Device Fingerprint (DFP)
Deve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"raw","raw":"{\n \"card_hash\": \"fc417fdc29d7ba484ecb4ba9e40966a1_Q2FyZCBOb3RlOiA0OTAxNzIwMDgwMzQ0NDQ4CkNhcmQgSG9sZGVyIE5hbWU6IEx1a2UgU2t5c2F3a2VyCkNhcmQgRXhwaXJhdGlvbiBEYXRlOiAxMTIyCkNhcmQgQ1ZWOiAxMjM=\",\n \"type\": \"remittance\",\n \"amount\": 503919,\n \"installments\": \"3\",\n \"item_id\": \"Horcrux\",\n \"item_url\": \"123456789\",\n \"currency_amount\": 1000,\n \"currency_abbreviation\": \"GBP\",\n \"net_value\": 450000,\n \"customer\":{\n \"external_id\": \"Horcrux_Expelliarmus\",\n \"name\": \"Harry James Potter\",\n \"document_number\": \"13590862858\",\n \"email\": \"harry@potter.com\",\n \"phone_number\": \"+5511999118811\",\n \"address\": {\n \"country\":\"br\",\n \"state\":\"WC\",\n \"city\":\"Godrics Hollow\",\n \"neighborhood\":\"Village\",\n \"street\":\"Order of the Phoenix\",\n \"zipcode\": \"38706400\"\n }\n },\n \"soft_descriptor\": \"J. K. Rowling\",\n \"customer_registration_date\": \"2023-02-01T00:00:00.000Z\",\n \"customer_first_transaction_date\": \"2023-02-02T00:00:00.000Z\",\n \"customer_last_transaction_date\": \"2024-01-01T00:00:00.000Z\",\n \"customer_paid_proposals\": 150\n}","options":{"raw":{"language":"json"}}},"url":"https://api.marlim.co/v2/transactions"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"status\": \"paid\",\n \"date_created\": \"2024-01-01T00:00:00.000Z\",\n \"amount\": 503919,\n \"paid_amount\": 503919,\n \"installments\": \"3\",\n \"transaction_id\": \"31071980\",\n \"authorization_code\": \"99887766\",\n \"nsu\": \"31071980\",\n \"card_id\": \"card_ckAuklyxr6y8tue9tfak1c463\",\n \"card_fingerprint\": \"ckhxex28q3dsqg828zqt8prou\"\n}"},{"id":"a2d6a2be-deb9-4ebb-bc5f-073129bacd71","name":"200 | CARD_ID","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"},{"description":"Deve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"raw","raw":"{\n \"card_id\": \"card_ckAuklyxr6y8tue9tfak1c463\",\n \"type\": \"currency_exchange\",\n \"amount\": 503919,\n \"installments\": \"3\",\n \"item_id\": \"Horcrux\",\n \"item_url\": \"123456789\",\n \"currency_amount\": 1000,\n \"currency_abbreviation\": \"GBP\",\n \"net_value\": 450000,\n \"customer\":{\n \"external_id\": \"Horcrux_Expelliarmus\",\n \"name\": \"Harry James Potter\",\n \"document_number\": \"13590862858\",\n \"email\": \"harry@potter.com\",\n \"phone_number\": \"+5511999118811\",\n \"address\": {\n \"country\":\"br\",\n \"state\":\"WC\",\n \"city\":\"Godrics Hollow\",\n \"neighborhood\":\"Village\",\n \"street\":\"Order of the Phoenix\",\n \"zipcode\": \"38706400\"\n }\n },\n \"soft_descriptor\": \"J. K. Rowling\",\n \"customer_registration_date\": \"2023-02-01T00:00:00.000Z\",\n \"customer_first_transaction_date\": \"2023-02-02T00:00:00.000Z\",\n \"customer_last_transaction_date\": \"2024-01-01T00:00:00.000Z\",\n \"customer_paid_proposals\": 150\n}","options":{"raw":{"language":"json"}}},"url":"https://api.marlim.co/v2/transactions"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"status\": \"paid\",\n \"date_created\": \"2024-01-01T00:00:00.000Z\",\n \"amount\": 503919,\n \"paid_amount\": 503919,\n \"installments\": \"3\",\n \"transaction_id\": \"31071980\",\n \"authorization_code\": \"99887766\",\n \"nsu\": \"31071980\",\n \"card_id\": \"card_ckAuklyxr6y8tue9tfak1c463\",\n \"card_fingerprint\": \"ckhxex28q3dsqg828zqt8prou\"\n}"},{"id":"0024255a-8794-47ec-b4f4-967218a39824","name":"200 | DADOS DO CARTÃO","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"},{"description":"Deve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"raw","raw":"{\n \"card_holder_name\": \"Harry J. Potter\",\n \"card_number\": \"4556366941062122\",\n \"card_expiration_date\": \"0399\",\n \"card_cvv\": \"111\",\n \"type\": \"currency_exchange\",\n \"amount\": 503919,\n \"installments\": \"3\",\n \"item_id\": \"Horcrux\",\n \"item_url\": \"123456789\",\n \"currency_amount\": 1000,\n \"currency_abbreviation\": \"GBP\",\n \"net_value\": 450000,\n \"customer\":{\n \"external_id\": \"Horcrux_Expelliarmus\",\n \"name\": \"Harry James Potter\",\n \"document_number\": \"13590862858\",\n \"email\": \"harry@potter.com\",\n \"phone_number\": \"+5511999118811\",\n \"address\": {\n \"country\":\"br\",\n \"state\":\"WC\",\n \"city\":\"Godrics Hollow\",\n \"neighborhood\":\"Village\",\n \"street\":\"Order of the Phoenix\",\n \"zipcode\": \"38706400\"\n }\n },\n \"soft_descriptor\": \"J. K. Rowling\",\n \"customer_registration_date\": \"2023-02-01T00:00:00.000Z\",\n \"customer_first_transaction_date\": \"2023-02-02T00:00:00.000Z\",\n \"customer_last_transaction_date\": \"2024-01-01T00:00:00.000Z\",\n \"customer_paid_proposals\": 150\n}","options":{"raw":{"language":"json"}}},"url":"https://api.marlim.co/v1/transactions"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"status\": \"paid\",\n \"date_created\": \"2024-01-01T00:00:00.000Z\",\n \"amount\": 503919,\n \"paid_amount\": 503919,\n \"installments\": \"3\",\n \"transaction_id\": \"31071980\",\n \"authorization_code\": \"99887766\",\n \"nsu\": \"31071980\",\n \"card_id\": \"card_ckAuklyxr6y8tue9tfak1c463\",\n \"card_fingerprint\": \"ckhxex28q3dsqg828zqt8prou\"\n}"},{"id":"a7b8c04a-830d-4487-8022-935661eaa6fd","name":"400 | FALTANDO CAMPO","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"},{"description":"Deve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"raw","raw":"{\n \"card_holder_name\": \"Harry J. Potter\",\n \"card_number\": \"4556366941062122\",\n \"card_expiration_date\": \"0399\",\n \"card_cvv\": \"111\",\n \"type\": \"currency_exchange\",\n \"amount\": 503919,\n \"item_id\": \"Horcrux\",\n \"item_url\": \"123456789\",\n \"currency_amount\": 1000,\n \"currency_abbreviation\": \"GBP\",\n \"net_value\": 450000,\n \"customer\":{\n \"external_id\": \"Horcrux_Expelliarmus\",\n \"name\": \"Harry James Potter\",\n \"document_number\": \"13590862858\",\n \"email\": \"harry@potter.com\",\n \"phone_number\": \"+5511999118811\",\n \"address\": {\n \"country\":\"br\",\n \"state\":\"WC\",\n \"city\":\"Godrics Hollow\",\n \"neighborhood\":\"Village\",\n \"street\":\"Order of the Phoenix\",\n \"zipcode\": \"38706400\"\n }\n },\n \"soft_descriptor\": \"J. K. Rowling\",\n \"customer_registration_date\": \"2023-02-01T00:00:00.000Z\",\n \"customer_first_transaction_date\": \"2023-02-02T00:00:00.000Z\",\n \"customer_last_transaction_date\": \"2024-01-01T00:00:00.000Z\",\n \"customer_paid_proposals\": 150\n}","options":{"raw":{"language":"json"}}},"url":"https://api.marlim.co/v2/transactions"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"errors\": {\n \"type\": \"parameter\",\n \"message\": \"The parameter [ installments ] is missing.\"\n }\n}"}],"_postman_id":"c07ee1e3-73d0-4fb6-8660-f02bd4627ed0"},{"name":"Transações (General)","id":"32449904-6178-4bb2-b5ac-375b708a0d34","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[],"body":{"mode":"urlencoded","urlencoded":[]},"url":"https://api.marlim.co/v2/transactions/general","description":"Utilize esse endpoint caso você seja o responsável pelas taxas de Adquirência.
\n\nA única diferença na request entre esse endpoint e o recurso deTransações Padrão da Marlimé que os valores passados em net_value e amount devem ser os mesmos (ou seja o valor final que você irá cobrar do seu cliente), uma vez que a Marlim não terá necessidade de fazer o cálculo das taxas de Adquirência durante a cobrança.
Ao utilizar esse endpoint, também será retornado um novo parâmetro amount_to_receive, tanto no response síncrono quanto nos assíncronos (webhooks / postback_url).
Esse parâmetro é referente ao valor que será depositado na conta bancária relativo a essa transação.
Deve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"urlencoded","urlencoded":[]},"url":"https://api.marlim.co/v2/transactions/:transaction_id/status","description":"Além de receber um POST a cada mudança de status de uma transação (via postback_url), você também pode consultar todos os status que já ocorreram em uma transação específica através da rota :transaction_id/status.
| Variábel | Obrigatório | Tipo |
|---|---|---|
| transaction_id | sim | string |
ID da transação
\nDeve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"urlencoded","urlencoded":[]},"url":"https://api.marlim.co/v2/transactions/9999123/status"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"[\n\t{\n\t\t\"old_status\": \"authorized\",\n\t\t\"desired_status\": \"paid\",\n\t\t\"current_status\": \"paid\",\n\t\t\"date_updated\": \"2020-01-01T10:00:00.000Z\"\n\t},\n\t{\n\t\t\"old_status\": \"processing\",\n\t\t\"desired_status\": \"authorized\",\n\t\t\"current_status\": \"authorized\",\n\t\t\"date_updated\": \"2020-01-01T00:00:00.000Z\"\n\t}\n]"},{"id":"f4591d9c-de6e-4f31-8e99-70f584134674","name":"200 | TRANSAÇÃO ESTORNADA","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/x-www-form-urlencoded"},{"description":"Deve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"urlencoded","urlencoded":[]},"url":"https://api.marlim.co/v2/transactions/9999123/status"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"[\n {\n \"old_status\": \"paid\",\n \"desired_status\": \"refunded\",\n \"current_status\": \"refunded\",\n \"date_updated\": \"2020-01-01T20:00:00.000Z\"\n },\n {\n \"old_status\": \"authorized\",\n \"desired_status\": \"paid\",\n \"current_status\": \"paid\",\n \"date_updated\": \"2020-01-01T10:00:00.000Z\"\n },\n {\n \"old_status\": \"processing\",\n \"desired_status\": \"authorized\",\n \"current_status\": \"authorized\",\n \"date_updated\": \"2020-01-01T00:00:00.000Z\"\n }\n]"},{"id":"f81da313-f50d-4d04-9cbb-a82662473f24","name":"200 | TRANSAÇÃO RECUSADA","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/x-www-form-urlencoded"},{"description":"Deve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"urlencoded","urlencoded":[]},"url":"https://api.marlim.co/v2/transactions/9999123/status"},"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"[\n {\n \"old_status\": \"processing\",\n \"desired_status\": \"authorized\",\n \"current_status\": \"refused\",\n \"date_updated\": \"2020-01-01T10:00:00.000Z\"\n }\n]"},{"id":"31af8174-91b5-4412-8ab0-2a79a790a669","name":"400 | TRANSAÇÃO NÃO ENCONTRADA","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/x-www-form-urlencoded"},{"description":"Deve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"urlencoded","urlencoded":[]},"url":"https://api.marlim.co/v2/transactions/1111112/status"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"errors\": {\n \"type\": \"transaction_id\",\n \"message\": \"The ID: 1111112 was not found.\"\n }\n}"}],"_postman_id":"1b781904-c3a3-41f1-8c2c-65a754808b5b"},{"name":"Criar Cartão","id":"775f46bb-8200-4a62-ab73-63d6ccead9f7","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/x-www-form-urlencoded"},{"description":"Deve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"urlencoded","urlencoded":[{"description":"Número do cartão
\nData de validade do cartão. Somente números no formato MMAA
\nNome do portador do cartão
\nCódigo verificador do cartão
\nEssa rota é para salvar cartões de crédito com segurança no vault da Marlim.co a fim de utilizá-los em compras futuras. Com ela você salva os dados do cartão e recebe um hash com a propriedade card_id.
| Parâmetro | Obrigatório | Tipo |
|---|---|---|
| card_number | sim | string |
| card_expiration_date | sim | string |
| card_holder_name | sim | string |
| card_cvv | sim | string |
Deve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"raw","raw":"{\n \"card_number\": \"4556366941062122\",\n \"card_expiration_date\": \"1223\",\n \"card_holder_name\": \"Ronaldinho Gaúcho\",\n \"card_cvv\": \"111\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.marlim.co/v2/cards"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"card_id\": \"card_ckAuklyxr6y8tue9tfak1c463\",\n \"date_created\": \"2023-01-01T00:00:00.000Z\",\n \"date_updated\": \"2023-01-01T00:00:00.000Z\",\n \"card_holder_name\": \"Ronaldinho Gaúcho\",\n \"card_brand\": \"visa\",\n \"card_first_digits\": \"455636\",\n \"card_last_digits\": \"2122\",\n \"card_expiration_date\": \"1223\",\n \"valid\": true\n}"},{"id":"59e7be24-0402-4676-a2c9-effae07c9786","name":"400 | NÚMERO INVÁLIDO","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"},{"description":"Deve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"raw","raw":"{\n \"card_number\": \"455636694106212\",\n \"card_holder_name\": \"Ronaldinho Gaúcho\",\n \"card_cvv\": \"111\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.marlim.co/v2/cards"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"errors\": {\n \"type\": \"card_number\",\n \"message\": \"Card number digits are missing.\"\n }\n}"}],"_postman_id":"775f46bb-8200-4a62-ab73-63d6ccead9f7"},{"name":"Retornar Cartão","id":"b5e42aa1-f956-4189-bf35-c1ea16289679","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/x-www-form-urlencoded"},{"description":"Deve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"urlencoded","urlencoded":[]},"url":"https://api.marlim.co/v2/cards/:card_id","description":"Essa rota é utilizada quando se deseja retornar alguns dados do cartão. Apenas o ID do cartão é necessário passado no PATH da URL.
\n| Variábel | \nObrigatório | \nTipo | \n
|---|---|---|
| card_id | \nsim | \nstring | \n
ID do cartão
\nDeve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"urlencoded","urlencoded":[]},"url":"https://api.marlim.co/v2/cards/card_ckAuklyxr6y8tue9tfak1c463"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"card_id\": \"card_ckAuklyxr6y8tue9tfak1c463\",\n \"date_created\": \"2023-01-01T00:00:00.000Z\",\n \"date_updated\": \"2023-01-01T00:00:00.000Z\",\n \"card_holder_name\": \"Ronaldinho Gaúcho\",\n \"card_brand\": \"visa\",\n \"card_first_digits\": \"455636\",\n \"card_last_digits\": \"2122\",\n \"card_expiration_date\": \"1223\",\n \"valid\": true\n}"}],"_postman_id":"b5e42aa1-f956-4189-bf35-c1ea16289679"},{"name":"Estornos","id":"1f5bb44e-c1c5-4a66-92c8-bdda3e074adf","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/x-www-form-urlencoded"},{"description":"Deve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"urlencoded","urlencoded":[]},"url":"https://api.marlim.co/v2/transactions/:transaction_id/refund","description":"Essa rota é utilizada quando se deseja estornar uma transação. Apenas o transaction_id da transação é necessário para a efetivação do estorno passado no PATH do endpoint.
Somente transações com o status paid, podem ser estornadas.
| Variábel | Obrigatório | Tipo |
|---|---|---|
| transaction_id | sim | string |
Deve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"urlencoded","urlencoded":[]},"url":{"raw":"https://api.marlim.co/v2/transactions/:transaction_id/refund","protocol":"https","host":["api","marlim","co"],"path":["v2","transactions",":transaction_id","refund"],"variable":[{"key":"transaction_id","value":"12345678"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"status\": \"refunded\",\n \"date_created\": \"1998-07-31T00:00:00.000Z\",\n \"date_updated\": \"1998-07-31T00:00:00.000Z\",\n \"paid_amount\": 503919,\n \"refunded_amount\": 503919,\n \"card_last_digits\": \"1234\",\n \"card_brand\": \"visa\",\n \"customer\": {\n \"name\": \"Harry James Potter\",\n \"email\": \"harry@potter.com\",\n \"phone_number\": \"+5511999118811\",\n \"document_number\": \"12345678900\",\n \"address\": {\n \"country\":\"hp\",\n \"state\":\"WC\",\n \"city\":\"Godrics Hollow\",\n \"neighborhood\":\"Village\",\n \"street\":\"Order of the Phoenix\",\n \"zipcode\": \"38706400\"\n }\n }\n}"}],"_postman_id":"1f5bb44e-c1c5-4a66-92c8-bdda3e074adf"},{"name":"Link de Pagamento","id":"2832f7a1-46b7-4076-90d9-fd059baea1d1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/x-www-form-urlencoded"},{"description":"Deve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"urlencoded","urlencoded":[{"description":"ID da transação na sua plataforma.
\nDescrição que aparecerá na fatura do seu cliente. Máximo de 13 caracteres, sendo alfanuméricos e espaços.
\nValores aceitos:
\n\n• AED
\n• ARS
\n• AUD
\n• BRL
\n• CAD
\n• CHF
\n• CLP
\n• CNY
\n• COL
\n• DKK
\n• EUR
\n• GBP
\n• ILS
\n• JPY
\n• MXN
\n• NOK
\n• NZD
\n• PEN
\n• RUB
\n• SEK
\n• USD
\n• UYU
\n• ZAR
\n
Valor transacionado da moeda estrangeira. Ex: 500 Dólares Americanos, deve ser passado como 50000 (em centavos)
\nValor líquido da transação: (valor do câmbio + IOF), sem contar as taxas de adquirência. OBS: O Valor máximo permitido por transação é de 6000000 (R$ 60.000,00)
\nNome do cliente
\nNúmero do documento do cliente.
\nIMPORTANTE: Se o comprador for de nacionalidade Brasileira (customer.address.country === 'br'), deve ser passado o CPF do mesmo. Caso seu cliente seja estrangeiro, deve ser passado o número identificador (national identification number).
\nNúmero de telefone do cliente.
\nIMPORTANTE: Se o comprador for de nacionalidade Brasileira (customer.address.country === 'br'), deve ser passado no formato +55DD9XXXXXXXX. Caso seu cliente seja estrangeiro, deve ser passado no padrão regex /^\\+(?:[0-9] ?){6,14}[0-9]$/]]
\nE-mail do cliente
\nIdentificador do cliente em sua plataforma.
\nNacionalidade do cliente, no formato sigla do país. Só serão aceitos o formato ISO 3166-1 alfa-2 (duas-letras) Ex: br, us, uy...
\nEstado do atual endereço do cliente, no formato sigla do estado. Ex: SP, RJ, MG...
\nCidade do endereço do cliente.
\nBairro do endereço do cliente.
\nNome da Rua do endereço do cliente. (Não é necessário passar número nem complemento).
","key":"customer[address][street]","type":"text","value":"string"},{"key":"customer_registration_date","value":"dateTime","description":"Parametro opicional da data de abertura do cadastro do usuário na sua plataforma no formato ISODateTime. Ex: 2023-01-01T00:00:00.000Z
","type":"text"},{"key":"customer_first_transaction_date","value":"dateTime","description":"Parametro opicional da data da primeira operação concretizada (paga) na sua plataforma, independente de ter sido processada pela Marlim ou não, no formato ISODateTime. Ex: 2023-02-01T00:00:00.000Z
","type":"text"},{"key":"customer_last_transaction_date","value":"dateTime","description":"Parametro opicional da data da última operação concretizada (paga) na sua plataforma, independente de ter sido processada pela Marlim ou não, no formato ISODateTime. Ex: 2023-02-01T00:00:00.000Z
","type":"text"},{"key":"customer_paid_proposals","value":"int32","description":"Parametro opicional da quantidade de propostas concretizadas (pagas) pelo cliente na sua plataforma, independente de ter sido processada pela Marlim ou não. Ex: 150
","type":"text"}]},"url":"https://api.marlim.co/v2/link_payment","description":"Para criar um novo Link de Pagamento deve ser usada essa rota.
\n\n| Atributo | Obrigatório | Tipo |
|---|---|---|
item_id | sim | string |
soft_descriptor | sim | string |
currency_abbreviation | sim | string |
currency_amount | sim | int32 |
net_value | sim | int32 |
customer | sim | object |
customer[name] | sim | string |
customer[document_number] | sim | string |
customer[phone_number] | sim | string |
customer[email] | sim | string |
customer[external_id] | sim | string |
customer[address] | sim | object |
customer[address][country] | sim | string |
customer[address][state] | sim | string |
customer[address][city] | sim | string |
customer[address][neighborhood] | sim | string |
customer[address][street] | sim | string |
Como forma de melhoria na taxa de aprovação/conversão dos clientes, foram criados alguns parâmetros extras que podem ser enviados na request de criação do Link de Pagamento. Essa lista pode crescer ao longo do tempo, abaixo segue a lista de itens que já foram criados e já estão disponiveis para implementação na API:
\n\n| Atributo | Tipo | Descrição |
|---|---|---|
customer_registration_date | dateTime | Data de abertura do cadastro do usuário na sua plataforma no formato ISODateTime. |
customer_first_transaction_date | dateTime | Data da primeira operação concretizada (paga) na sua plataforma, independente de ter sido processada pela Marlim ou não, no formato ISODateTime. |
customer_last_transaction_date | dateTime | Data da última operação concretizada (paga) na sua plataforma, independente de ter sido processada pela Marlim ou não, no formato ISODateTime. |
customer_paid_proposals | int32 | Quantidade de propostas concretizadas (pagas) pelo cliente na sua plataforma, independente de ter sido processada pela Marlim ou não. |
📌 O formato ISODateTime que a Marlim espera é: YYYY-MM-DDTHH:mm:sssZ, por exemplo: 2023-01-01T00:00:000Z. Algo similar ao método toISOString() do Javascript (new Date().toISOString()).
Deve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"raw","raw":"{\n \"item_id\": \"Horcrux\",\n \"currency_amount\": 1000,\n \"currency_abbreviation\": \"GBP\",\n \"net_value\": 450000,\n \"customer\":{\n \"external_id\": \"Horcrux_Expelliarmus\",\n \"name\": \"Harry James Potter\",\n \"document_number\": \"123123123\",\n \"email\": \"harry@potter.com\",\n \"phone_number\": \"+449999123456\",\n \"address\": {\n \"country\":\"uk\",\n \"state\":\"WC\",\n \"city\":\"Godrics Hollow\",\n \"neighborhood\":\"Village\",\n \"street\":\"Order of the Phoenix\"\n }\n },\n \"soft_descriptor\": \"J. K. Rowling\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.marlim.co/v2/link_payment"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"payment_hash\": \"123ABCdef4\",\n \"payment_url\": \"https://link.marlim.co/123ABCdef4\",\n \"item_id\": \"Horcrux\",\n \"net_value\": 450000,\n \"current_status\": \"waiting_payment\",\n \"date_created\": \"2020-01-01T00:00:00.000Z\"\n}"}],"_postman_id":"2832f7a1-46b7-4076-90d9-fd059baea1d1"},{"name":"Dados do Link de Pagamento","id":"21f29431-302d-4360-83f7-d979e27500a7","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/x-www-form-urlencoded"},{"description":"Deve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"urlencoded","urlencoded":[]},"url":"https://api.marlim.co/v2/link_payment/:payment_hash","description":"Essa rota é utilizada quando se deseja retornar os dados de um link de pagamento. Apenas o HASH do link é necessário passado no PATH da URL.
\n\n| Variábel | \nObrigatório | \nTipo | \n \n \n
|---|---|---|
| payment_hash | \nsim | \nstring | \n
Hash da URL de Pagamento
\nDeve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"urlencoded","urlencoded":[]},"url":"https://api.marlim.co/v2/link_payment/123ABCdef4"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"item_id\": \"Horcrux\",\n \"currency_amount\": \"1000\",\n \"date_created\": \"2020-06-18T01:27:27.034Z\",\n \"currency_abbreviation\": \"GBP\",\n \"net_value\": 450000,\n \"customer\": {\n \"external_id\": \"Horcrux_Expelliarmus\",\n \"name\": \"Harry James Potter\",\n \"document_number\": \"123123123\",\n \"email\": \"harry@potter.com\",\n \"phone_number\": \"+449999123456\",\n \"address\": {\n \"country\":\"uk\",\n \"state\":\"WC\",\n \"city\":\"Godrics Hollow\",\n \"neighborhood\":\"Village\",\n \"street\":\"Order of the Phoenix\"\n }\n },\n \"soft_descriptor\": \"J. K. Rowling\",\n \"postback_url\": \"https://yoursite.com/callback\",\n \"current_status\": \"waiting_payment\"\n}"}],"_postman_id":"21f29431-302d-4360-83f7-d979e27500a7"},{"name":"Conciliação","id":"a49bf782-ed67-467e-add5-1dce60925225","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/x-www-form-urlencoded"},{"description":"Deve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"urlencoded","urlencoded":[{"key":"date_created","value":"date-time","description":"É importante notar que a filtragem por data utiliza ISO datetime (timestamp com milissegundos) para representá-la. EXEMPLO: em Javascript new Date().toISOString(), que retornará algo no formato 2021-09-23T00:00:00.000Z
Parâmetro extra que pode ser passado caso seja necessário retornar as transações da conciliação do dia.
Valor default: false
Essa rota é utilizada quando se deseja retornar os dados referente a Conciliação Bancária em uma data específica. O response conterá os dados relacionados a conta bancária bem como o resumo das transações (Pagas e Estornadas). Se o parâmetro date_created não for passado na request, o response será da última operação de conciliação gravada no nosso sistema.
À partir de 21/03/2023 foi iniciada uma nova versão dessa API. Nessa nova versão é possível retornar somente os dados bancários no payload de response ou também as transações utilizando o parâmetro with_transactions. O Payload de response de transferências também está um pouco diferente, retornando agora em um Array.
Com essa nova versão, caso seja enviado uma data anterior a 21/03/2023, poderá ser retornado uma mensagem de que a Conciliação nesta data está sendo criada, com isso é só fazer novamente a mesma chamada alguns minutos depois para receber o payload normalmente. Nos exemplos ao lado, procure por 01/03/23.
\n\nÀ partir de 25/06/2024 foi criado um update da API de Conciliação para clientes que não antecipam com a Marlim. Nessa nova versão, será retornado um parâmetro extra no array de transações payable_details, que possuem 3 valores de acordo com a tabela abaixo:
| Significado | |
|---|---|
installment | Parcela referente ao total de pagamentos que a transação irá gerar. |
installment_value | Valor que será transferido para a conta bancária referente ao montante da transação. |
total_already_transferred | Total que já foi transferido para a conta bancária referente ao montante da transação. |
Com essa nova versão, caso seja enviado uma data anterior a 25/06/2024, poderá ser retornado uma mensagem de que a Conciliação nesta data está sendo criada, com isso é só fazer novamente a mesma chamada alguns minutos depois para receber o payload normalmente. Nos exemplos ao lado, procure por Sem Antecipação.
\n\n| Atributo | Obrigatório | Tipo |
|---|---|---|
date_created | não | date-time |
with_transactions | não | boolean |
Deve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"https://api.marlim.co/v2/conciliation"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"paid_transactions_amount\": 3300000,\n \"refunded_transactions_amount\": 0,\n \"transfer_estimated_amount\": 3300000,\n \"transfer_reference_date\": \"2023-06-22\",\n \"transfers\": [\n {\n \"transfer_amount\": 3300000,\n \"transfer_type\": \"ted\",\n \"transfer_status\": \"transferred\",\n \"transfer_bank_response\": \"Confirmado\",\n \"transfer_date_created\": \"2023-06-22T08:00:00.000Z\",\n \"transfer_date_updated\": \"2023-06-22T08:00:00.000Z\",\n \"transfer_funding_date\": \"2023-06-22T15:00:00.000Z\",\n \"transfer_funding_estimated_date\": \"2023-06-23T00:00:00.000Z\",\n \"transfer_id\": 12345678\n }\n ]\n}"},{"id":"0ab7f852-38bf-4432-a8d2-974fe7795c69","name":"200 | COM TRANSAÇÕES","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"},{"description":"Deve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"raw","raw":"{\n \"date_created\": \"2023-06-22T00:00:00.000Z\",\n \"with_transactions\": true\n}","options":{"raw":{"language":"json"}}},"url":"https://api.marlim.co/v2/conciliation"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"paid_transactions_amount\": 3300000,\n \"refunded_transactions_amount\": 0,\n \"transfer_estimated_amount\": 3300000,\n \"transfer_reference_date\": \"2023-06-22\",\n \"transfers\": [\n {\n \"transfer_amount\": 3300000,\n \"transfer_type\": \"ted\",\n \"transfer_status\": \"transferred\",\n \"transfer_bank_response\": \"Confirmado\",\n \"transfer_date_created\": \"2023-06-22T08:00:00.000Z\",\n \"transfer_date_updated\": \"2023-06-22T08:00:00.000Z\",\n \"transfer_funding_date\": \"2023-06-22T15:00:00.000Z\",\n \"transfer_funding_estimated_date\": \"2023-06-23T00:00:00.000Z\",\n \"transfer_id\": 12345678\n }\n ],\n \"paid_transactions\": [\n {\n \"transaction_id\": \"999777666\",\n \"date_created\": \"2023-06-21T14:29:07.334Z\",\n \"date_updated\": \"2023-06-21T14:31:07.334Z\",\n \"paid_amount\": 1100000,\n \"net_value\": 1000000,\n \"installments\": \"3\",\n \"authorization_code\": \"HRP399\",\n \"item_id\": \"Horcrux\",\n \"customer_name\": \"HARRY JAMES POTTER\",\n \"customer_document_number\": \"123123123\",\n \"customer_email\": \"harry@potter.com\",\n \"customer_phone_number\": \"+449999123123\",\n \"card_brand\": \"visa\",\n \"card_last_digits\": \"2122\",\n \"card_expiration_date\": \"0399\"\n },\n {\n \"transaction_id\": \"999777555\",\n \"date_created\": \"2023-06-21T14:29:07.334Z\",\n \"date_updated\": \"2023-06-21T14:31:07.334Z\",\n \"paid_amount\": 1200000,\n \"net_value\": 1100000,\n \"installments\": \"3\",\n \"authorization_code\": \"HJG299\",\n \"item_id\": \"PhilosopherStone\",\n \"customer_name\": \"HERMIONE JEAN GRANGER\",\n \"customer_document_number\": \"345345345\",\n \"customer_email\": \"hermione@granger.com\",\n \"customer_phone_number\": \"+449999234234\",\n \"card_brand\": \"visa\",\n \"card_last_digits\": \"2123\",\n \"card_expiration_date\": \"0499\"\n },\n {\n \"transaction_id\": \"999777444\",\n \"date_created\": \"2023-06-21T14:29:07.334Z\",\n \"date_updated\": \"2023-06-21T14:31:07.334Z\",\n \"paid_amount\": 1300000,\n \"net_value\": 1200000,\n \"installments\": \"3\",\n \"authorization_code\": \"RBW199\",\n \"item_id\": \"ChamberOfSecrets\",\n \"customer_name\": \"RONALD BILIUS WEASLEY\",\n \"customer_document_number\": \"456456456\",\n \"customer_email\": \"ronald@weasley.com\",\n \"customer_phone_number\": \"+449999345345\",\n \"card_brand\": \"visa\",\n \"card_last_digits\": \"2124\",\n \"card_expiration_date\": \"0599\"\n }\n ],\n \"refunded_transactions\": []\n}"},{"id":"706241dd-ec02-4b2b-b341-488520e9b0a1","name":"200 | 01/03/23","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"},{"description":"Deve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"raw","raw":"{\n \"date_created\": \"2023-03-01T00:00:00.000Z\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.marlim.co/v2/conciliation"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"status\": \"processing\",\n \"message\": \"The conciliation for the date '2023-03-01' is being processed. Please try again in 30 minutes.\"\n}"},{"id":"1de91e81-5ce0-48df-8aef-d2c5a308cc21","name":"200 | SEM ANTECIPAÇÃO","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"},{"description":"Deve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"raw","raw":"{\n \"date_created\": \"2024-06-25T00:00:00.000Z\",\n \"with_transactions\": true\n}","options":{"raw":{"language":"json"}}},"url":"https://api.marlim.co/v2/conciliation"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"paid_transactions_amount\": 1099999,\n \"refunded_transactions_amount\": 0,\n \"transfer_estimated_amount\": 1099999,\n \"transfer_reference_date\": \"2024-06-25\",\n \"transfers\": [\n {\n \"transfer_amount\": 1099999,\n \"transfer_type\": \"ted\",\n \"transfer_status\": \"transferred\",\n \"transfer_bank_response\": \"Confirmado\",\n \"transfer_date_created\": \"2024-06-25T08:00:00.000Z\",\n \"transfer_date_updated\": \"2024-06-25T08:00:00.000Z\",\n \"transfer_funding_date\": \"2024-06-25T15:00:00.000Z\",\n \"transfer_funding_estimated_date\": \"2024-06-26T00:00:00.000Z\",\n \"transfer_id\": 12345678\n }\n ],\n \"paid_transactions\": [\n {\n \"transaction_id\": \"999777666\",\n \"date_created\": \"2024-05-24T14:29:07.334Z\",\n \"date_updated\": \"2024-05-24T14:31:07.334Z\",\n \"paid_amount\": 1100000,\n \"net_value\": 1000000,\n \"installments\": \"3\",\n \"authorization_code\": \"HRP399\",\n \"item_id\": \"Horcrux\",\n \"customer_name\": \"HARRY JAMES POTTER\",\n \"customer_document_number\": \"123123123\",\n \"customer_email\": \"harry@potter.com\",\n \"customer_phone_number\": \"+449999123123\",\n \"card_brand\": \"visa\",\n \"card_last_digits\": \"2122\",\n \"card_expiration_date\": \"0399\",\n \"payable_details\": {\n \"installment\": \"1\",\n \"installment_value\": 333333,\n \"total_already_transferred\": 0\n }\n },\n {\n \"transaction_id\": \"999777555\",\n \"date_created\": \"2024-04-24T14:29:07.334Z\",\n \"date_updated\": \"2024-04-24T14:31:07.334Z\",\n \"paid_amount\": 1200000,\n \"net_value\": 1100000,\n \"installments\": \"3\",\n \"authorization_code\": \"HJG299\",\n \"item_id\": \"PhilosopherStone\",\n \"customer_name\": \"HERMIONE JEAN GRANGER\",\n \"customer_document_number\": \"345345345\",\n \"customer_email\": \"hermione@granger.com\",\n \"customer_phone_number\": \"+449999234234\",\n \"card_brand\": \"visa\",\n \"card_last_digits\": \"2123\",\n \"card_expiration_date\": \"0499\",\n \"payable_details\": {\n \"installment\": \"2\",\n \"installment_value\": 366666,\n \"total_already_transferred\": 366666\n }\n },\n {\n \"transaction_id\": \"999777444\",\n \"date_created\": \"2024-03-24T14:29:07.334Z\",\n \"date_updated\": \"2024-03-24T14:31:07.334Z\",\n \"paid_amount\": 1300000,\n \"net_value\": 1200000,\n \"installments\": \"3\",\n \"authorization_code\": \"RBW199\",\n \"item_id\": \"ChamberOfSecrets\",\n \"customer_name\": \"RONALD BILIUS WEASLEY\",\n \"customer_document_number\": \"456456456\",\n \"customer_email\": \"ronald@weasley.com\",\n \"customer_phone_number\": \"+449999345345\",\n \"card_brand\": \"visa\",\n \"card_last_digits\": \"2124\",\n \"card_expiration_date\": \"0599\",\n \"payable_details\": {\n \"installment\": \"3\",\n \"installment_value\": 400000,\n \"total_already_transferred\": 800000\n }\n }\n ],\n \"refunded_transactions\": []\n}"}],"_postman_id":"a49bf782-ed67-467e-add5-1dce60925225"},{"name":"Card Hash Key","id":"2fc0e007-90ef-4247-adb7-c0bc1d7da34d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/x-www-form-urlencoded"},{"description":"Deve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"body":{"mode":"urlencoded","urlencoded":[]},"url":"https://api.marlim.co/v2/card_hash_key","description":"O card_hash representa uma versão criptografada das dados card_holder_name, card_number, card_expiration_date e card_cvv.
Nesta seção você vai aprender mais sobre como o hash é criado, e quais algoritmos utilizar.
\n\nO card_hash consiste de uma string gerada a partir dos dados do cartão de crédito. Essa string é encriptada por RSA usando uma chave pública que deve ser requisitada ao servidor da Marlim a cada novo card_hash gerado. Essa chave é invalidada e destruída assim que o servidor lê as informações contidas no card_hash, e por isso só pode ser utilizada uma única vez. Ela também é temporária, expirando 30 minutos após ter sido gerada.
Abaixo, um exemplo da rota que deverá ser utilizada para obtenção de uma chave pública de encriptação dos dados do cartão de seu cliente:
\nREQUEST
\ncurl -X GET -G \"https://api.marlim.co/v2/card_hash_key\" \\\n-H \"Content-Type: application/json\" \\\n-H \"api_key: api_key_value\" \\\n\nRESPONSE
\n{\n \"public_key_id\": \"fc417fdc29d7ba484ecb4ba9e40966a1\",\n \"public_key\": \"-----BEGIN RSA PUBLIC KEY-----\\nMIICCgKCAgEAmxxkyU71w+0bmVc4 ... uBK5I5eXJNJq4bgnZEXtF2sCAwEAAQ==\\n-----END RSA PUBLIC KEY-----\\n\",\n \"created_at\": 1668978045960,\n \"expires_at\": 1668979845960\n}\n\nAbaixo, uma tabela com o significado de cada propriedade retornada na request:
\n| Propriedade | Significado |
|---|---|
public_key_id | Id retornado e que será utilizado para compor o card_hash, logo, é importante que você o reserve. |
public_key | Chave pública utilizada para criptografar os dados do cartão. |
created_at | UnixTimestamp da criação da chave. |
expires_at | UnixTimestamp de expiração da chave. |
Agora você vai ter que criar uma QueryString com valores URLEncoded para os parâmetros do cartão de crédito. Vamos pegar os seguintes dados abaixo como exemplo:
Dados do cartão
\n\"card_number\": \"4901720080344448\",\n\"card_holder_name\": \"Luke Skywalker\",\n\"card_expiration_date\": \"1122\",\n\"card_cvv\": \"123\",\n\nA QueryString ficará composta na seguinte forma:
Querystring Data
\ncard_number=4901720080344448&card_holder_name=Luke Skywalker&card_expiration_date=1122&card_cvv=123\n\nAgora você vai fazer uma criptografia pública com RSA e o padding RSA_PKCS1_OAEP_PADDING usando a public_key que você recebeu na request passando a QueryString construída.
Após criptografar esses dados você deve converter o resultado para base64. Como resultado você terá:
\nHash criado a partir de RSA e RSA_PKCS1_OAEP_PADDING
\nQ2FyZCBOb3RlOiA0OTAxNzIwMDgwMzQ0NDQ4CkNhcmQgSG9sZGVyIE5hbWU6IEx1a2UgU2t5c2F3a2VyCkNhcmQgRXhwaXJhdGlvbiBEYXRlOiAxMTIyCkNhcmQgQ1ZWOiAxMjM=\n\nAgora com o public_key_id vindo da request inicial, e os dados criptografados convertidos para base64, seu card_hash deverá ser formatado da seguinte maneira: card_hash = public_key_id + \"_\" + encrypted_string_base64, com o resultado na seguinte forma:
O HASH final do Cartão (card_hash)
\nfc417fdc29d7ba484ecb4ba9e40966a1_Q2FyZCBOb3RlOiA0OTAxNzIwMDgwMzQ0NDQ4CkNhcmQgSG9sZGVyIE5hbWU6IEx1a2UgU2t5c2F3a2VyCkNhcmQgRXhwaXJhdGlvbiBEYXRlOiAxMTIyCkNhcmQgQ1ZWOiAxMjM=\n\nFique atento ao UNDERLINE entre o public_key_id e o encrypted_string_base64.Acima citamos o formato utilizando ASPAS durante a concatenação somente para ilustração.
Com o HASH em mãos, crie uma transação na Marlim, utlizando a string gerada no parâmetro card_hash, seguindo o exemplo abaixo:
REQUEST
\ncurl -X POST \"https://api.marlim.co/v2/transactions\" \\\n-H \"Content-Type: application/json\" \\\n-H \"api_key: api_key_value\" \\\n-d '{\n \"net_value\": 1000000,\n \"amount\": 1039501,\n \"installments\": \"1\",\n \"type\": \"remittance\",\n \"currency_amount\": 150000,\n \"currency_abbreviation\": \"EUR\",\n \"item_id\": \"#123456789\",\n \"item_url\": \"123456789\",\n \"card_hash\": \"fc417fdc29d7ba484ecb4ba9e40966a1_Q2FyZCBOb3RlOiA0OTAxNzIwMDgwMzQ0NDQ4CkNhcmQgSG9sZGVyIE5hbWU6IEx1a2UgU2t5c2F3a2VyCkNhcmQgRXhwaXJhdGlvbiBEYXRlOiAxMTIyCkNhcmQgQ1ZWOiAxMjM=\",\n \"customer[external_id]\": \"111222333\",\n \"customer[name]\": \"Luke Skywalker\",\n \"customer[email]\": \"luke@jedimaster.sw\",\n \"customer[document_number]\": \"00099988877\",\n \"customer[phone_number]\": \"+18007770133\",\n \"customer[address][zipcode]\": \"95351\",\n \"customer[address][country]\": \"us\",\n \"customer[address][state]\": \"CA\",\n \"customer[address][city]\": \"Modesto\",\n \"customer[address][neighborhood]\": \"East Modesto\",\n \"customer[address][street]\": \"Sunset Ave\",\n \"customer[address][number]\": \"713\",\n \"soft_descriptor\": \"Star Wars\",\n \"customer_registration_date\": \"2023-02-01T00:00:00.000Z\",\n \"customer_first_transaction_date\": \"2023-02-02T00:00:00.000Z\",\n \"customer_last_transaction_date\": \"2024-01-01T00:00:00.000Z\",\n \"customer_paid_proposals\": 150\n}'\n\nUma forma de criar o HASH é utilizando a biblioteca crypto do NodeJS. Abaixo um exemplo de como criar o card_hash utilizando essa biblioteca:
\nUsando a Biblioteca Crypto do NodeJS
\nconst crypto = require(\"crypto\");\n// 1 - Crie uma função auxiliadora\nconst encryptCardHash = (card_data, public_key_id, public_key) => {\n const esc = encodeURIComponent;\n const queryString = Object.keys(card_data).map(key => `${esc(key)}=${esc(card_data[key]).trim()}`).join('&');\n const encryptBuffer = crypto.publicEncrypt({\n key: public_key,\n padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,\n passphrase: public_key_id\n }, Buffer.from(queryString))\n const encryptedString = encryptBuffer.toString('base64');\n return `${public_key_id}_${encryptedString}`;\n}\n// 2 - Passe os dados do cartão, a public_key_id e a public_key para a função \nconst card_hash = encryptCardHash({\n card_number: \"4901720080344448\",\n card_holder_name: \"Luke Skywalker\",\n card_expiration_date: \"1122\",\n card_cvv: \"123\",\n}, \"fc417fdc29d7ba484ecb4ba9e40966a1\", JSON.parse(\"-----BEGIN RSA PUBLIC KEY ... END RSA PUBLIC KEY-----\"))\n// 3 - O resultado deve ser algo similar ao valor abaixo\ncard_hash: \"fc417fdc29d7ba484ecb4ba9e40966a1_Q2FyZCBOb3RlOiA0OTAxNzIwMDgwMzQ0NDQ4CkNhcmQgSG9sZGVyIE5hbWU6IEx1a2UgU2t5c2F3a2VyCkNhcmQgRXhwaXJhdGlvbiBEYXRlOiAxMTIyCkNhcmQgQ1ZWOiAxMjM=\"\n\nDeve ser passado no HEADER da requisição.
","key":"api_key","type":"text","value":"api_key_value"}],"url":"https://api.marlim.co/v2/card_hash_key"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"public_key\": \"-----BEGIN RSA PUBLIC KEY-----\\nMIICCgKCAgEAsZi348DiNlkiOD8nwI78ajDg3hgl4OtZmMBTEc8bo9R/+d+47d3V\\np+CMhVyJv7b1op2OPx02yImbuZuw6tLpbKrjxjLkueb7GhxUICWb2g7HzHTUlScX\\nfV39yNNM2x61p3I4ov5Xn2/Heyw9WHha0E1nGrTKcU7zaAHeMVIGsdaJsOPO0qkX\\nx0IQGKL7scrO03O1qfgghyEL8qhw9mZ+EwvVc20fF4m5hOCXCbKBXeuT42oJktbw\\nLkZ4DmnMiPy36Gar+c2OFGmoimyYBUhYeGaLMRE2bZiQ4yydVHYNGYgQHl/t7Yzd\\noyy0ile1fam5yReqRMmv3jHU6n48W2XeE8z16pic5AXj1hHwVzP2tsj/XU3puvto\\nJvRz+a2FBENzbdTkiDVOby/Hbp23Of6IjRvcZ0gHe/VwhpZmrFsUAxNwPxvj81HA\\nrJNK/AVNMPlRzfmbg6d7K3a72ZnBbebCafEnaTPkDg9yUX8t6gK1uMa4bfuWxxoN\\nK9Z9SBOLp0oLLsB5LdUlBRfcTNy7NIKWAxvk8iCpMcspgds0W8uQCTklSomvVYYF\\nGk4O7i/o9jpHmqFNSfpGYXnGVK3GSB2lmvBB24Jvlc7iEg55RJzrjOkxoaNsb6CO\\n3+4I6wXkeV0A70Ipbt79QKRvp9f82QRSNxAqv+Qt1Qi4sHoz3xlbjacCAwEAAQ==\\n-----END RSA PUBLIC KEY-----\\n\",\n \"public_key_id\": \"0fd8855f0076888a7a30d041109a3b89\",\n \"created_at\": 1708689279812,\n \"expires_at\": 1708691079812\n}"}],"_postman_id":"2fc0e007-90ef-4247-adb7-c0bc1d7da34d"}],"id":"bed74769-896a-4bed-8454-58b53b61d6f8","_postman_id":"bed74769-896a-4bed-8454-58b53b61d6f8","description":""},{"name":"Antifraude","item":[{"name":"Device Fingerprint (DFP)","id":"f2465aa2-8648-4e20-8956-0728f5bc0086","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"*","header":[],"body":{"mode":"urlencoded","urlencoded":[]},"url":"","description":"A Marlim utiliza uma ferramenta de identificação digital / device fingerprint (DFP) chamada ThreatMetrix e que é fornecida pela líder de mercado LexisNexis. Com esta identificação digital nós conseguimos otimizar e melhorar a conversão de compra dos nossos clientes pois tomamos melhores decisões ao analisar informações não sensíveis geradas pela ferramenta como IP, versão do OS, browser, entre outros.
\n\nLembrando do nosso interesse em fornecer serviços de prevenção a fraude a partir de perfis comportamentais, os quais são lícitos e representam uma finalidade legítima, considerada a partir de situações concretas, tal como exigido pela LGPD.
\n\nVocê deverá inserir um script em JavaScript no Front-End do checkout da sua aplicação. A URL da Threatmetrix será inserida no script e por isso deve ser corretamente preenchida, seguindo a figura abaixo:
\n\n![](\"https://api.taya.marlim.co/img/dfp.png\")
\n\nO modelo da URL da Threatmetrix é
https://h.online-metrix.net/fp/tags.js?org_id=OrgId&session_id=ProviderMerchantIdItemURL
Na URL, substitua os valores OrgId, ProviderMerchantId e ItemURL conforme a orientação da imagem acima.
Os valores de OrgId e ProviderMerchantId serão disponibilizados pelo time de Desenvolvimento da Marlim durante a sua integração. Existem valores diferentes para Sandbox e Produção.
Insira a URL preenchida na tag script JavaScript, seguindo a orientação abaixo:
\n\n<head>\n <script type=\"text/javascript\" src=\"https://h.online-metrix.net/fp/tags.js?org_id=OrgId&session_id=ProviderMerchantIdItemURL\"></script>\n</head>\n\nEsse valor deve representar o mesmo passado para aAPI de Transações da Marlimdentro do parâmetro item_url. É com esse valor que faremos o \"match\" entre o DFP do Browser do cliente no momento do pagamento com a request da API de Transações da Marlim.
Geralmente é o último item em window.location.pathname no browser. Por exemplo, se URL do pedido do seu cliente for: https://seusite.com/pedido/123456789, então valor a ser usado é: 123456789.
Com isso, quando você chamar a API de Transações da Marlim, deve ser passado o valor 123456789 em item_url e o script do Antifraude Marlim deve ser preenchido da seguinte forma:
https://h.online-metrix.net/fp/tags.js?org_id=XXXXXX&session_id=YYYYYY123456789\n\nO não preenchimento dessa URL de forma exata como descrita nessa documentação, bem como valores incorretos em ItemURL e item_url, podem atrapalhar a conversão da transação do seu cliente. Dúvidas, fale com a gente 🤓