Pular para o conteúdo principal
Version: v1

Criar Transação

Para fazer uma cobrança você deve utilizar essa rota e criar a sua transação. É possível utilizar um card_id ou todos os dados do cartão diretamente. A primeira opção é a mais indicada, por fatores de segurança.

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.
item_urlstringPATH URL no browser do cliente pagador que origina a transação.
card_holder_namestringNome do portador do cartão.
card_numberstringNúmero do cartão.
card_expiration_datestringData de validade do cartão. Somente números no formato MMAA.
card_cvvstringCódigo verificador do cartão.
card_idstringHash de um cartão salvo e validado anteriormente. Caso inclua os dados do cartão, esse campo torna-se dispensável.
customerobjectObjeto Cliente.
customer[external_id]stringCódigo identificador do cliente em sua plataforma.
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 (clientes nacionais) ou ZIP (clientes estrangeiros) do cliente.
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...
customer[address][state]stringEstado do atual endereço do cliente, no formato sigla do estado. Ex: SP, RJ, MG...
customer[address][city]stringCidade do endereço do cliente.
customer[address][neighborhood]stringBairro do endereço do cliente.
customer[address][street]stringRua do endereço do cliente. Não é necessário passar número ou complemento.
soft_descriptorstringDescrição que aparecerá na fatura do seu cliente. Máximo de 13 caracteres, sendo alfanuméricos e espaços.
postback_urlstringParâmetro opcional para passar o endpoint do seu sistema que receberá informações a cada atualização da transação.
simulate_antifraude_statusstringParâmetro opcional que pode ser passado em ambiente de teste para simular o fluxo do Antifraude. Valores aceitos: paid, review e rejected.
simulate_antifraude_envstringParâmetro opcional que pode ser passado em ambiente de teste para simular o fluxo do Antifraude. Valores aceitos: production e sandbox. Default sandbox.
Importante

Os parâmetros customer[document_number] e customer[phone_number] devem ser tratados e passados de forma diferente entre clientes de nacionalidade brasileira ou estrangeira.

Caso o cliente seja de nacionalidade brasileira (customer[address][country] == 'br')
• Em customer[document_number] deve ser passado o CPF do cliente
• Em customer[phone_number] deve ser passado no formato +55DDXXXXXXXXX
Caso o cliente seja de nacionalidade estrangeira (customer[address][country] != 'br')
• Em customer[document_number] deve ser passado o NIN (national identification number) do cliente
• Em customer[phone_number] deve ser passado deve ser passado no padrão regex /^\+(?:[0-9] ?)14[0-9]$/]]

Response Object​

PropriedadeTipoDescrição
statusstringRepresenta o estado atual da transação. Valores possíveis: paid, review, refused e rejected.
authorization_codestringCódigo de autorização retornado pelo banco emissor.
nsustring Código que identifica a transação na adquirente.
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.
authorized_amountint32Valor em centavos autorizado 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.
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.

Postback URL​

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. Esses status, possuem 3 contextos: old_status (o status anterior), desired_status (o status desejado) e current_status (o status mais atual). 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://seusite.com/pedido/123456789/callback" \
-H "Content-Type: application/json" \ 
-H "User-Agent: Marlim/1.0.0" \ 
-H "Marlim-Api-Signature: Star98765Wars43210ANewHope1977" \
-d '{
  "transaction_id": "98765432",
  "event": "transaction_status_changed",
  "old_status": "processing",
  "desired_status": "paid",
  "current_status": "paid",
  "authorization_code": "112233",
  "nsu": "98765432",
  "date_created": "2024-02-16T19:58:04.238Z",
  "date_updated": "2024-02-16T19:58:04.238Z",
  "net_value": 1000000,
  "authorized_amount": 103950,
  "paid_amount": 103950,
  "refunded_amount": 0,
  "installments": "1",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "acquirer_status_code": "0000"
}'
Atenção

Você deve validar a origem do postback, isto é, se ele foi realmente enviado pelos servidores da Marlim.
Para isso, enviamos no HEADER do POST 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 postback 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 postback, 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

Caso todas essas tentativas falhem, é possível utilizar o Endpoint GET passando o ID dessa transação para retornar o status mais atual.

Antifraude​

Atenção

O nosso antifraude é composto por uma série de regras, entre elas a confirmação de que o cartão utilizado realmente pertence ao cliente em questão. Por conta disso é de extrema importância que na UI do checkout tenha um aviso/disclaimer informando aos clientes para não utilizar cartões virtuais e/ou de terceiros, uma vez que esta validação irá falhar e a operação será recusada. Ou seja, deixe evidente para o seu cliente uma mensagem solicitando para ele utilizar os dados do cartão físico expedido pelo banco emissor e do próprio cliente que está efetuando a compra, evitando surpresas 😎

Simular Status de Transações​

Para facilitar durante a fase de desenvolvimento você pode simular os status de uma transação e alterá-la depois para entender como adicionar esse fluxo na sua aplicação. Uma simulação comum, seria criar uma transação em revisão manual (review) e futuramente alterar o status para paid ou rejected. Emulando assim, em desenvolvimento como aconteceria esse fluxo em produção.

🕹  Criar uma transação com status review e depois alterá-la para paid
Request
curl -X POST "https://api.crypto.marlim.co/v1/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "net_value": 1000000,
  "amount": 1039501,
  "installments": "1",
  "item_id": "123456789",
  "item_url": "https://seusite.com/pedido/123456789",
  "card_holder_name": "Luke Skywalker",
  "card_number": "5555444433332222",
  "card_expiration_date": "1122",
  "card_cvv": "123",
  "customer[external_id]": "111222333",
  "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]": "713 Sunset Ave",
  "soft_descriptor": "Star Wars",
  "postback_url": "https://seusite.com/pedido/123456789/callback",
  "simulate_antifraude_status": "review"
}'
Response200
{
  "status": "review",
  "authorization_code": "555729",
  "nsu": "11122233",
  "date_created": "2024-02-16T19:58:04.238Z",
  "date_updated": "2024-02-16T19:58:04.238Z",
  "net_value": 1000000,
  "authorized_amount": 103950,
  "paid_amount": 0,
  "refunded_amount": 0,
  "installments": "1",
  "transaction_id": "11122233",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "acquirer_status_code": "0000",
  "acquirer_status_message": "The bank has authorized this amount on the card."
}
🕹  Criar uma transação com status rejected
Request
curl -X POST "https://api.crypto.marlim.co/v1/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "net_value": 1000000,
  "amount": 1039501,
  "installments": "1",
  "item_id": "123456789",
  "item_url": "https://seusite.com/pedido/123456789",
  "card_holder_name": "Luke Skywalker",
  "card_number": "5555444433332222",
  "card_expiration_date": "1122",
  "card_cvv": "123",
  "customer[external_id]": "111222333",
  "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]": "713 Sunset Ave",
  "soft_descriptor": "Star Wars",
  "postback_url": "https://seusite.com/pedido/123456789/callback",
  "simulate_antifraude_status": "rejected"
}'
Response200
{
  "status": "rejected",
  "authorization_code": null,
  "nsu": null,
  "date_created": "2024-02-16T19:58:04.238Z",
  "date_updated": "2024-02-16T19:58:04.238Z",
  "net_value": 1000000,
  "authorized_amount": 0,
  "paid_amount": 0,
  "refunded_amount": 0,
  "installments": "1",
  "transaction_id": null,
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "acquirer_status_code": null,
  "acquirer_status_message": null
}

Simular em Produção​

O Antifraude Marlim contém como parte dos mecanismos de validação uma verificação do cartão junto ao banco emissor. Como o fluxo de banco emissor não existe em ambiente sandbox, preparamos o parâmetro simulate_antifraude_env que pode ser usado durante a fase de desenvolvimento para simular a validação acurada do Antifraude em produção, porém não será cobrado nada do cliente / cartão, uma vez que a api_key usada é do ambiente sandbox.

🕹  Simulando Antifraude em Produção
Request
curl -X POST "https://api.crypto.marlim.co/v1/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "net_value": 1000000,
  "amount": 1039501,
  "installments": "1",
  "item_id": "123456789",
  "item_url": "https://seusite.com/pedido/123456789",
  "card_holder_name": "Luke Skywalker",
  "card_number": "5555444433332222",
  "card_expiration_date": "1122",
  "card_cvv": "123",
  "customer[external_id]": "111222333",
  "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]": "713 Sunset Ave",
  "soft_descriptor": "Star Wars",
  "simulate_antifraude_env": "production"
}'
Response200
{
  "status": "paid",
  "authorization_code": "555729",
  "nsu": "11122233",
  "date_created": "2024-02-16T19:58:04.238Z",
  "date_updated": "2024-02-16T19:58:04.238Z",
  "net_value": 1000000,
  "authorized_amount": 103950,
  "paid_amount": 103950,
  "refunded_amount": 0,
  "installments": "1",
  "transaction_id": "11122233",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "acquirer_status_code": "0000",
  "acquirer_status_message": "The acquirer captured the amount on the card."
}
Nota

Se você utlizar o parâmetro simulate_antifraude_env com o valor production o parâmetro opcional simulate_antifraude_status se torna inutilizável.

Atenção

Os parâmetros simulate_antifraude_status e simulate_antifraude_env e o endpoint v1/antifraud só são habilitados para api_key do ambiente sandbox. Se você passar algum desses dois parâmetros ou chamar o endpoint de alteração de status 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_response_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 card_cvv, que pode ser passado com algumas combinações, utlizando o dígito 6 no início, como segue na tabela abaixo.

ValorSignificado
601Transação não aprovada pelo banco (acquirer_response_code: 1000).
602Dados incorretos do cartão (acquirer_response_code: 1011).
603Saldo insuficiente (acquirer_response_code: 1016).
604Erro bancário genérico (acquirer_response_code: 5000).
🕹  Simulando Recusa Bancária em Desenvolvimento
Request
curl -X POST "https://api.crypto.marlim.co/v1/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "net_value": 1000000,
  "amount": 1039501,
  "installments": "1",
  "item_id": "123456789",
  "item_url": "https://seusite.com/pedido/123456789",
  "card_holder_name": "Luke Skywalker",
  "card_number": "5555444433332222",
  "card_expiration_date": "1122",
  "card_cvv": "601",
  "customer[external_id]": "111222333",
  "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]": "713 Sunset Ave",
  "soft_descriptor": "Star Wars"
}'
Response200
{
  "status": "refused",
  "authorization_code": null,
  "nsu": null,
  "date_created": "2024-02-16T19:58:04.238Z",
  "date_updated": "2024-02-16T19:58:04.238Z",
  "net_value": 1000000,
  "authorized_amount": 0,
  "paid_amount": 0,
  "refunded_amount": 0,
  "installments": "1",
  "transaction_id": null,
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "acquirer_status_code": "0000",
  "acquirer_status_message": "Transaction not approved by the bank. Please contact the bank and try again."
}

Exemplos​

Nota

Os valores utilizados nos exemplos abaixo são apenas para ilustração. Em ambiente de desenvolvimento ou 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.crypto.marlim.co/v1/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "net_value": 1000000,
  "amount": 1039501,
  "installments": "1",
  "item_id": "123456789",
  "item_url": "https://seusite.com/pedido/123456789",
  "card_holder_name": "Luke Skywalker",
  "card_number": "5555444433332222",
  "card_expiration_date": "1122",
  "card_cvv": "123",
  "customer[external_id]": "111222333",
  "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]": "713 Sunset Ave",
  "soft_descriptor": "Star Wars"
}'
Response200
{
  "status": "paid",
  "authorization_code": "112233",
  "nsu": "98765432",
  "date_created": "2024-02-16T19:58:04.238Z",
  "date_updated": "2024-02-16T19:58:04.238Z",
  "net_value": 1000000,
  "authorized_amount": 103950,
  "paid_amount": 103950,
  "refunded_amount": 0,
  "installments": "1",
  "transaction_id": "98765432",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "acquirer_status_code": "0000",
  "acquirer_status_message": "The acquirer captured the amount on the card."
}