Pular para o conteúdo principal

Criar Transação

Para fazer uma cobrança você deve utilizar essa rota e criar a sua transação.

É possível utilizar um card_hash, card_id ou todos os dados do cartão diretamente (card_holder_name, card_number, card_expiration_date e card_cvv). 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, sem precisar expor os dados sensíveis do cartão.

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, descrevemos o passo a passo de como criar um card_hash.

Split de Pagamento

A Marlim oferece a opção de Split de Pagamento para que a isaac possa criar uma transação com múltiplos recebedores, basta passar um array de objetos com seller_id e amount no parâmetro split no corpo da requisição.

Se for utilizada a opção de Split de Pagamento, será necessário adicionar o recebedor padrão da isaac no parâmetro split.

Caso não seja passado o parâmetro split, o valor cobrado será destinado inteiramente ao recebedor padrão da isaac.
POSTv1/transactions

Request Body Params​

AtributoTipoDescrição
net_valueint32Valor a ser cobrado sem as taxas de adquirência. Deve ser passado em centavos.
amountint32Valor final a ser cobrado com as taxas. Deve ser passado em centavos.
installmentsstringNúmero de parcelas da transação, sendo mínimo: 1 e máximo: 12.
item_idstringID da transação na sua plataforma.
card_hashstringHash de um cartão criptografado manualmente usando uma chave pública.
Caso inclua um card_id ou os dados abertos do cartão, esse campo torna-se dispensável.
card_idstringID de um cartão salvo e validado anteriormente via card_hash.
Caso inclua um card_hash ou os dados abertos do cartão, esse campo torna-se dispensável.
card_holder_namestringNome do portador do cartão.
Caso inclua um card_id ou card_hash, esse campo torna-se dispensável.
card_numberstringNúmero do cartão.
Caso inclua um card_id ou card_hash, esse campo torna-se dispensável.
card_expiration_datestringData de validade do cartão. Somente números no formato MMAA.
Caso inclua um card_id ou card_hash, esse campo torna-se dispensável.
card_cvvstringCódigo verificador do cartão.
Caso inclua um card_id ou card_hash, esse campo torna-se dispensável.
customerobjectObjeto Cliente.
customer[name]stringNome do cliente.
customer[email]stringE-mail do cliente.
customer[document_number]stringNúmero do documento do cliente.
customer[phone_number]stringNúmero do telefone do cliente.
customer[address]objectObjeto Endereço do Cliente.
customer[address][zipcode]stringCEP do cliente.
Máximo em caracteres: 9
customer[address][country]stringNacionalidade 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 em caracteres: 2
customer[address][state]stringEstado do atual endereço do cliente, no formato sigla do estado. Ex: SP, RJ, MG...
Máximo em caracteres: 2
customer[address][city]stringCidade do endereço do cliente.
Máximo em caracteres: 50
customer[address][neighborhood]stringBairro do endereço do cliente.
Máximo em caracteres: 45
customer[address][street]stringRua do endereço do cliente.
Máximo em caracteres: 54
customer[address][number]stringNúmero do atual endereço do cliente.
Máximo em caracteres: 5
customer[address][complement]stringParâmetro opcional do complemento do atual endereço do cliente.
Máximo em caracteres: 14
soft_descriptorstringDescrição que aparecerá na fatura do seu cliente. Máximo de 17 caracteres, sendo alfanuméricos e espaços.
splitarrayParâmetro opcional para o array de objetos com os dados do Split de Pagamento.
split[][seller_id]stringParâmetro opcional para passar o ID do parceiro que fará parte do Split de Pagamento.
split[][amount]int32Valor em centavos que o parceiro deverá receber do pagamento. Deve ser passado em centavos.
webhook_urlstringParâmetro opcional para passar o endpoint do seu sistema que receberá informações a cada atualização da transação.
simulate_statusstringParâmetro opcional que pode ser passado em ambiente de teste para simular o fluxo do Antifraude. Valores aceitos: paid, review e rejected.
simulate_refusedstringParâmetro opcional que pode ser passado em ambiente de teste para simular o fluxo de retornos negativos do banco emissor. Valores aceitos: 1000, 1011, 1016 e 5000.
Importante

Nossa API não aceita null, undefined ou empty valores de string em qualquer endpoint. Se passar um parâmetro com qualquer um destes 3 valores, será retornado um erro. Caso o parâmetro não seja obrigatório e você não queira que ele seja computado, basta removê-lo da requisição.

Atenção

O formato ISODateTime que a Marlim espera é: YYYY-MM-DDTHH:mm:ssZ, por exemplo: 2025-01-01T00:00:000Z. Algo similar ao método toISOString() do Javascript (new Date().toISOString()).

Response Object​

PropriedadeTipoDescrição
statusstringRepresenta o estado atual da transação. Valores possíveis: paid, review, rejected e refused.
nsustringCódigo que identifica a transação na adquirente.
authorization_codestringCódigo de autorização retornado pelo banco emissor.
date_createddateTimeData de criação da transação no formato ISODateTime.
date_updateddateTimeData de atualização do status da transação no formato ISODateTime.
net_valueint32Valor em centavos a ser cobrado sem as taxas de adquirência.
amountint32Valor em centavos a ser cobrado na transação.
paid_amountint32Valor em centavos capturado na transação.
refunded_amountint32Valor em centavos estornado na transação.
installmentsstringNúmero de parcelas em que o cliente pagou.
transaction_idstringNúmero identificador da transação.
card_holder_namestringNome do portador do cartão utilizado no pagamento.
card_brandstringBandeira do cartão utilizado no pagamento. Valores possíveis: visa, mastercard, amex, hipercard e elo.
card_first_digitsstringPrimeiros 6 dígitos do cartão utilizado no pagamento.
card_last_digitsstringÚltimos 4 dígitos do cartão utilizado no pagamento.
card_idstring | nullAo realizar uma transação, retornamos sempre um card_id. Se a transação foi criada usando um card_hash, criamos automaticamente esse id com os dados do cartão criptografado no vault da Marlim. Esse card_id pode ser usado em compras futuras.
acquirer_status_codestringCódigo identificador da resposta do Banco Emissor. Valores possíveis: 0000, 1000, 1011, 1016 e 5000.
acquirer_status_messagestringMensagem referente ao código da resposta do Banco Emissor.
splitarrayArray de objetos com os dados do Split de Pagamento
split[][seller_id]stringID do parceiro que fará parte do Split de Pagamento.
split[][amount]int32Valor em centavos que o parceiro deverá receber do pagamento.

Webhook URL​

Todo o processo de mudança de status de uma transação é assíncrono. Por isso, é importante que você passe um webhook_url durante o processo de criação de uma transação para que sua aplicação receba todas as mudanças de status. Abaixo, a tabela com os valores possíveis de status.

StatusSignificado
processingA request entrou em uma fila de requisições e a transação está em processo de autorização.
paidTransação paga e capturada com sucesso.
reviewTransação está em processo de revisão manual pelos nossos especialistas.
O valor foi autorizado e reservado no cartão, mas ainda não foi capturado.
refusedTransação recusada pelo banco emissor.
refundedTransação estornada.
chargebackTransação sofreu chargeback.
🕹  Exemplo do BODY de um POST da Marlim para a sua aplicação
Request
curl -X POST "https://isaac.com.br/pedido/123456789/callback" \
-H "Content-Type: application/json" \ 
-H "User-Agent: Marlim/1.0.0" \ 
-H "Marlim-Api-Signature: Star98765Wars43210ANewHope1977" \
-d '{
  "event": "transaction_status_changed",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "current_status": "paid",
  "nsu": "98765432",
  "authorization_code": "112233",
  "date_created": "2025-03-30T20:20:05.812Z",
  "date_updated": "2025-03-30T20:20:05.812Z",
  "net_value": 100000,
  "amount": 105000,
  "paid_amount": 105000,
  "installments": "1",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "444455",
  "card_last_digits": "2222",
  "acquirer_status_code": "0000"
}'
Atenção

Você deve validar a origem do webhook, isto é, se ele foi realmente enviado pelos servidores da Marlim.
Para isso, enviamos no HEADER do POST do dois valores:

• User-Agent: sempre com o valor Marlim/1.0.0
• Marlim-Api-Signature: o final da sua api_key removendo os valores mak_test_ e mak_live_

Retentativas​

Caso o seu sistema deixe de receber um webhook por alguma instabilidade ou até mesmo por estar fora do ar, serão executados dos servidores da Marlim novas tentativas para completar a request até que os nossos servidores recebeba um STATUS 200 do seu sistema. Partindo do primeiro webhook, os próximos são enviados com o seguinte padrão de intervalo de tempo:

TempoTentativas
1 Minuto3 Tentativas
5 Minutos3 Tentativas
60 Minutos25 Tentativas

Antifraude​

Simular Status de Transações​

Para facilitar durante a fase de desenvolvimento você pode simular os status de uma transação em conjunto com o nossos Antifraude para desenvolver esse fluxo na sua aplicação. Você pode simular os status paid, review ou rejected.

🕹  Exemplos de como criar uma transação simulando o status
Request
curl -X POST "https://api.isaac.marlim.co/v1/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "net_value": 1000000,
  "amount": 1039501,
  "installments": "1",
  "type": "currency_exchange",
  "item_id": "#234567890",
  "card_id": "card_jedi123master4amidala5son",
  "customer[name]": "Luke Skywalker",
  "customer[email]": "luke@jedimaster.sw",
  "customer[document_number]": "00099988877",
  "customer[phone_number]": "+18007770133",
  "customer[address][zipcode]": "95351",
  "customer[address][country]": "us",
  "customer[address][state]": "CA",
  "customer[address][city]": "Modesto",
  "customer[address][neighborhood]": "East Modesto",
  "customer[address][street]": "Sunset Ave",
  "customer[address][number]": "713",
  "soft_descriptor": "Star Wars",
  "simulate_status": "paid"
}'
Response200
{
  "status": "paid",
  "nsu": "98765432",
  "authorization_code": "112233",
  "date_created": "2025-03-30T20:20:05.812Z",
  "date_updated": "2025-03-30T20:20:05.812Z",
  "net_value": 1000000,
  "amount": 1039501,
  "paid_amount": 1039501,
  "installments": "1",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "card_id": "card_jedi123master4amidala5son",
  "acquirer_status_code": "0000",
  "acquirer_status_message": "The acquirer captured the amount on the card."
}
Atenção

O parâmetro simulate_status só é habilitado para api_key do ambiente sandbox. Se você passar esse parâmetro em ambiente de produção, será retornado um erro 403 (Forbidden).

Recusa Banco Emissor​

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.

PrefixoSignificado
0000Transação autorizada, capturada ou estornada.
1000Transação não aprovada pelo banco.
1011Dados incorretos do cartão.
1016Cartão sem saldo.
5000Erro bancário genérico. O cliente deve entrar em contato com o Banco Emissor.

Simular Recusa Bancária​

O fluxo de banco emissor não existe em ambiente sandbox, então para facilitar na etapa de desenvolvimento preparamos o parâmetro simulate_refused, que pode ser passado com alguns valores como segue na tabela abaixo.

ValorSignificado
1000Transação não aprovada pelo banco (acquirer_status_code: 1000).
1011Dados incorretos do cartão (acquirer_status_code: 1011).
1016Saldo insuficiente (acquirer_status_code: 1016).
5000Erro bancário genérico (acquirer_status_code: 5000).
🕹  Exemplos de como simular a Recusa Bancária em Desenvolvimento
Request
curl -X POST "https://api.isaac.marlim.co/v1/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "net_value": 1000000,
  "amount": 1039501,
  "installments": "1",
  "type": "remittance",
  "item_id": "#123456789",
  "card_id": "card_jedi123master4amidala5son",
  "customer[name]": "Luke Skywalker",
  "customer[email]": "luke@jedimaster.sw",
  "customer[document_number]": "00099988877",
  "customer[phone_number]": "+18007770133",
  "customer[address][zipcode]": "95351",
  "customer[address][country]": "us",
  "customer[address][state]": "CA",
  "customer[address][city]": "Modesto",
  "customer[address][neighborhood]": "East Modesto",
  "customer[address][street]": "Sunset Ave",
  "customer[address][number]": "713",
  "soft_descriptor": "Star Wars",
  "simulate_refused": "1000"
}'
Response200
{
  "status": "refused",
  "nsu": "98765434",
  "authorization_code": null,
  "date_created": "2025-03-30T20:20:05.812Z",
  "date_updated": "2025-03-30T20:20:05.812Z",
  "net_value": 1000000,
  "amount": 1039501,
  "paid_amount": 0,
  "installments": "1",
  "transaction_id": null,
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "card_id": "card_jedi123master4amidala5son",
  "acquirer_status_code": "1000",
  "acquirer_status_message": "Transaction not approved by the bank. Please contact the bank and try again."
}

Exemplos​

ATENÇÃO

Os valores utilizados nos exemplos abaixo são apenas para ilustração e não devem ser usados para fazer requests nas APIs da Marlim. Em ambiente de desenvolvimento e testes, utilize dados mais próximos de uma transação real (dados de cartão e cliente). Se você utlizar valores fictícios o Antifraude pode não funcionar de forma esperada.

Request
curl -X POST "https://api.isaac.marlim.co/v1/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "net_value": 1000000,
  "amount": 1039501,
  "installments": "1",
  "type": "remittance",
  "item_id": "#123456789",
  "card_hash": "93237fb4c0948881dc99929899f6eda2_CdJrwrJ3iwVk8hTjM0jTVOz4vm7hJUckoPkLGvn+IBexY89sSdRFNozTCj1SopGs7iIhoRqH5FdXDwebIF605jOeURCJjZbv2EhQZPtJdM3689+hIyZWT/bXL2J8db2UHG+DYDqTnu1f8eY+AqsuOphCKw6q916L8M36RErtRFjxtYq9epsipjnG4nAKJRb8tx23xpEY0D1qHQiAMoAtI6FNcTj+tiYzZO757WMC4PbiyRdgSLjlNlSAeaLLKnPidQxLM+62MasL2rFpz8YZQ182vJXWvLE8fL6pXflwhoxqkyDZ9ySWInKEl+ydentxkCZkAj4htXRdF4bTX5KTXLzY11erHh4MaZZYYJk/jymid6dAqGJrTXsGrwVJB0JDVwThSxE6ashxAko9Ic1iLIDapXvUz6J8BZ2PSwAeu0Ed3RgbJ8vHby3R3alvVPNDGjvQqUqxAwhABKXdXRBY6Iw6oUETnMNHyeA9KBq0FcAVKomZS5fH7PIsse9lKqJP6YGUWBhc19H8iFowhbYdvpgDvW4uo4G/fJvLdXUnX1KIDR0wTxgEeI9dV66mwho7sa+EPxzTY/q5g2bGM3GpQDZTGaJyyTBu8IaawOZNEYLls+0T2B9pA0aBBrqV72IKbBC7/WdUcIUM+T9lqJdabCxM5b0g+pijFgkYfMWnmcM=",
  "customer[name]": "Luke Skywalker",
  "customer[email]": "luke@jedimaster.sw",
  "customer[document_number]": "00099988877",
  "customer[phone_number]": "+18007770133",
  "customer[address][zipcode]": "95351",
  "customer[address][country]": "us",
  "customer[address][state]": "CA",
  "customer[address][city]": "Modesto",
  "customer[address][neighborhood]": "East Modesto",
  "customer[address][street]": "Sunset Ave",
  "customer[address][number]": "713",
  "soft_descriptor": "Star Wars"
}'
Response200
{
  "status": "paid",
  "nsu": "98765432",
  "authorization_code": "112233",
  "date_created": "2025-03-30T20:20:05.812Z",
  "date_updated": "2025-03-30T20:20:05.812Z",
  "net_value": 1000000,
  "amount": 1039501,
  "paid_amount": 1039501,
  "installments": "1",
  "transaction_id": "k4m6Rw5rlQszEY7fiuRe",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "card_id": "card_jedi123master4amidala5son",
  "acquirer_status_code": "0000",
  "acquirer_status_message": "The acquirer captured the amount on the card."
}