Pular para o conteúdo principal
Version: v2

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.

POSTv2/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.
authentication_statusstringValor do Status da Autenticação do 3DS. Valores aceitos: AUTH_FLOW_COMPLETED, AUTH_NOT_SUPPORTED e CHANGE_PAYMENT_METHOD.
authentication_auth_statusstringValor do Status do liability do Banco Emissor no 3DS. Valores aceitos: AUTHENTICATED e NOT_AUTHENTICATED.
authentication_idstringRepresenta o id da Autenticação do 3DS.
customerobjectObjeto Cliente.
customer[name]stringNome do cliente.
customer[email]stringE-mail do cliente.
customer[document_number]stringNúmero do documento do cliente.
customer[phone]stringObjeto Telefone do Cliente.
customer[phone][type]stringO tipo do telefone do cliente: mobile, business e home.
customer[phone][area]stringCódigo de operadora local (DDD) do telefone do cliente.
customer[phone][number]stringNúmero do telefone do cliente.
customer[address]objectObjeto Endereço do Cliente.
customer[address][zipcode]stringCEP do atual endereço do cliente.
customer[address][state]stringEstado do atual endereço do cliente, no formato sigla do estado no padrão ISO 3166-2 Ex: SP, RJ, MG...
customer[address][city]stringCidade do atual endereço do cliente.
customer[address][neighborhood]stringBairro do atual endereço do cliente.
customer[address][street]stringRua do atual endereço do cliente.
customer[address][number]stringNúmero do atual endereço do cliente.
customer[address][complement]stringParâmetro opcional do complemento do atual endereço do cliente.
soft_descriptorstringDescrição que aparecerá na fatura do seu cliente. Máximo de 17 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

Diferenças entre a V1 e V2:

• Removidos os parâmetros customer[external_id] e customer[address][country], não sendo mais necessário enviar esses valores no body da request;

• O parâmetro customer[phone_number] mudou para o objeto customer[phone] e seus subsequentes: customer[phone][type], customer[phone][area] e customer[phone][number];

• Acrescentados os parâmetros customer[address][number] (obrigatório) e customer[address][complement] (opcional) referentes ao endereço do cliente;

• Nessa versão não serão aceitos dados de compradores estrangeiros, logo não há necessidade de tratar de forma diferente os valores relacionados ao documento e o telefone do cliente como na V1;

Parâmetros Customizados​

Como forma de melhoria na taxa de aprovação/conversão dos clientes, foram criados entre os times Marlim e Foxbit alguns parâmetros customizados que devem 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:

AtributoTipoDescrição
customer_registration_datedateTimeData de abertura do cadastro do usuário com a Foxbit no formato ISODateTime.
customer_first_transaction_datedateTimeData da primeira operação concretizada (paga) na Foxbit, independente de ter sido processada pela Marlim ou não no formato ISODateTime.
customer_last_transaction_datedateTimeData da última operação concretizada (paga) na Foxbit, independente de ter sido processada pela Marlim ou não no formato ISODateTime.
customer_paid_proposalsint32Quantidade de propostas concretizadas (pagas) pelo cliente na Foxbit, independente de ter sido processada pela Marlim ou não.
Atençã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()).

Response Object​

PropriedadeTipoDescrição
statusstringRepresenta o estado atual da transação. Valores possíveis: paid, review, refused e rejected.
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​

Ao criar uma transação, se você passar uma url no parâmetro postback_url a sua aplicação recebe um POST contendo no body um objeto com informações adicionais sobre o atual status da transação.

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 2 contextos: old_status (o status anterior) 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",
  "current_status": "paid",
  "nsu": "98765432",
  "date_created": "2024-02-16T20:19:09.053Z",
  "date_updated": "2024-02-16T20:19:09.053Z",
  "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 6 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ª Tentativa60 segundos
2ª Tentativa1800 segundos
3ª Tentativa3600 segundos
4ª Tentativa7200 segundos
5ª Tentativa14400 segundos
6ª Tentativa28800 segundos

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.foxbit.marlim.co/v2/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[name]": "Luke Skywalker",
  "customer[email]": "luke@jedimaster.sw",
  "customer[document_number]": "00099988877",
  "customer[phone][type]": "mobile",
  "customer[phone][area]": "11",
  "customer[phone][number]": "988887777",
  "customer[address][zipcode]": "95351",
  "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",
  "postback_url": "https://seusite.com/pedido/123456789/callback",
  "simulate_antifraude_status": "review"
}'
Response200
{
  "status": "review",
  "nsu": "11122233",
  "date_created": "2024-02-16T20:19:09.053Z",
  "date_updated": "2024-02-16T20:19:09.053Z",
  "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.foxbit.marlim.co/v2/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[name]": "Luke Skywalker",
  "customer[email]": "luke@jedimaster.sw",
  "customer[document_number]": "00099988877",
  "customer[phone][type]": "mobile",
  "customer[phone][area]": "11",
  "customer[phone][number]": "988887777",
  "customer[address][zipcode]": "95351",
  "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",
  "postback_url": "https://seusite.com/pedido/123456789/callback",
  "simulate_antifraude_status": "rejected"
}'
Response200
{
  "status": "rejected",
  "nsu": null,
  "date_created": "2024-02-16T20:19:09.053Z",
  "date_updated": "2024-02-16T20:19:09.053Z",
  "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.foxbit.marlim.co/v2/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[name]": "Luke Skywalker",
  "customer[email]": "luke@jedimaster.sw",
  "customer[document_number]": "00099988877",
  "customer[phone][type]": "mobile",
  "customer[phone][area]": "11",
  "customer[phone][number]": "988887777",
  "customer[address][zipcode]": "95351",
  "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",
  "postback_url": "https://seusite.com/pedido/123456789/callback",
  "simulate_antifraude_env": "production"
}'
Response200
{
  "status": "paid",
  "nsu": "11122233",
  "date_created": "2024-02-16T20:19:09.053Z",
  "date_updated": "2024-02-16T20:19:09.053Z",
  "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 v2/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_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 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_status_code: 1000).
602Dados incorretos do cartão (acquirer_status_code: 1011).
603Saldo insuficiente (acquirer_status_code: 1016).
604Erro bancário genérico (acquirer_status_code: 5000).
🕹  Simulando Recusa Bancária em Desenvolvimento
Request
curl -X POST "https://api.crypto.foxbit.marlim.co/v2/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[name]": "Luke Skywalker",
  "customer[email]": "luke@jedimaster.sw",
  "customer[document_number]": "00099988877",
  "customer[phone][type]": "mobile",
  "customer[phone][area]": "11",
  "customer[phone][number]": "988887777",
  "customer[address][zipcode]": "95351",
  "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": "refused",
  "nsu": null,
  "date_created": "2024-02-16T20:19:09.053Z",
  "date_updated": "2024-02-16T20:19:09.053Z",
  "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": "1000",
  "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.foxbit.marlim.co/v2/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",
  "authentication_status": "AUTH_FLOW_COMPLETED",
  "authentication_auth_status": "AUTHENTICATED",
  "authentication_id": "3DS-C4669D-0DF8-48DF-BBB3-6E22FBA865AF",
  "card_holder_name": "Luke Skywalker",
  "card_number": "5555444433332222",
  "card_expiration_date": "1122",
  "card_cvv": "123",
  "customer[name]": "Luke Skywalker",
  "customer[email]": "luke@jedimaster.sw",
  "customer[document_number]": "00099988877",
  "customer[phone][type]": "mobile",
  "customer[phone][area]": "11",
  "customer[phone][number]": "988887777",
  "customer[address][zipcode]": "95351",
  "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",
  "date_created": "2024-02-16T20:19:09.053Z",
  "date_updated": "2024-02-16T20:19:09.053Z",
  "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."
}