Pular para o conteúdo principal

Criar Transação

Endpoint dedicado para a Nomad fazer uma cobrança e criar uma sua transação.

É possível utilizar um card_hash ou um card_id. Os dados abertos do cartão, não serão aceitos nesse endpoint.

Atenção
Tanto este endpoint, quanto esta documentação, ainda estão em fase de desenvolvimento entre os times Marlim e Nomad. Novos parâmetros podem ser adicionados/removidos a qualquer momento ou novas regras podem surgir com o decorrer do desenvolvimento.

Os times da Nomad sempre serão avisados sobre essas mudanças e atualizações.
POSTv2/transactions/nomad

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.
typeint32Tipo de transação que o clinete está fazendo. Valores aceitos: remittance (remessa), currency_exchange (papel moeda).
currency_amountint32Valor transacionado da moeda estrangeira. Ex: 500 Dólares Americanos, deve ser passado como 50000 (mesmo formato do amount, em centavos)
currency_abbreviationstringValores aceitos: AED, ARS, AUD, BRL, CAD, CHF, CLP, CNY, COL, DKK, EUR, GBP, ILS, JPY, MXN, NOK, NZD, PEN, RUB, SEK, USD, UYU, ZAR.
item_idstringID da transação na sua plataforma.
item_urlstringPATH URL no browser do cliente pagador que origina a transação.
card_hashstringHash de um cartão criptografado manualmente usando uma chave pública. Caso inclua um card_id, esse campo torna-se dispensável.
card_idstringID de um cartão salvo e validado anteriormente via card_hash. Caso inclua um card_hash, 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.
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.
postback_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

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]$/]]

Parâmetros Customizados​

Como forma de melhoria na taxa de aprovação/conversão dos clientes, foram criados entre os times Marlim e Nomad 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 Nomad no formato ISODateTime.
customer_first_transaction_datedateTimeData da primeira operação concretizada (paga) na Nomad, independente de ter sido processada pela Marlim ou não no formato ISODateTime.
customer_last_transaction_datedateTimeData da última operação concretizada (paga) na Nomad, independente de ter sido processada pela Marlim ou não no formato ISODateTime.
customer_paid_proposalsint32Quantidade de propostas concretizadas (pagas) pelo cliente na Nomad, independente de ter sido processada pela Marlim ou não.
product_typestringTipo de Produto Nomad para ser enviado ao Antifraude Marlim. Valores aceitos: PRE, POS e REMESSA
Atenção

O formato ISODateTime que a Marlim espera é: YYYY-MM-DDTHH:mm:ssZ, 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, 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.

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 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 '{
  "event": "transaction_status_changed",
  "transaction_id": "98765432",
  "old_status": "processing",
  "desired_status": "paid",
  "current_status": "paid",
  "nsu": "98765432",
  "authorization_code": "112233",
  "date_created": "2025-01-15T19:44:04.883Z",
  "date_updated": "2025-01-15T19:44:04.883Z",
  "net_value": 100000,
  "amount": 103950,
  "paid_amount": 103950,
  "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 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

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 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.marlim.co/v2/transactions/nomad" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "net_value": 1000000,
  "amount": 1039501,
  "installments": "1",
  "type": "currency_exchange",
  "currency_amount": 200000,
  "currency_abbreviation": "USD",
  "item_id": "#234567890",
  "item_url": "234567890",
  "card_id": "card_jedi123master4amidala5son",
  "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]": "Sunset Ave",
  "customer[address][number]": "713",
  "soft_descriptor": "Star Wars",
  "simulate_status": "paid"
}'
Response200
{
  "status": "paid",
  "nsu": "98765432",
  "authorization_code": "112233",
  "date_created": "2025-01-15T19:44:04.883Z",
  "date_updated": "2025-01-15T19:44:04.883Z",
  "net_value": 1000000,
  "amount": 1039501,
  "paid_amount": 1039501,
  "installments": "1",
  "transaction_id": "98765432",
  "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."
}
tip

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.marlim.co/v2/transactions/nomad" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "net_value": 1000000,
  "amount": 1039501,
  "installments": "1",
  "type": "remittance",
  "currency_amount": 150000,
  "currency_abbreviation": "EUR",
  "item_id": "#123456789",
  "item_url": "123456789",
  "card_id": "card_jedi123master4amidala5son",
  "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]": "Sunset Ave",
  "customer[address][number]": "713",
  "soft_descriptor": "Star Wars",
  "simulate_refused": "1000"
}'
Response200
{
  "status": "refused",
  "nsu": "98765434",
  "authorization_code": null,
  "date_created": "2025-01-15T19:44:04.883Z",
  "date_updated": "2025-01-15T19:44:04.883Z",
  "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​

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.marlim.co/v2/transactions/nomad" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "net_value": 1000000,
  "amount": 1039501,
  "installments": "1",
  "type": "remittance",
  "currency_amount": 150000,
  "currency_abbreviation": "EUR",
  "item_id": "#123456789",
  "item_url": "123456789",
  "card_hash": "93237fb4c0948881dc99929899f6eda2_CdJrwrJ3iwVk8hTjM0jTVOz4vm7hJUckoPkLGvn+IBexY89sSdRFNozTCj1SopGs7iIhoRqH5FdXDwebIF605jOeURCJjZbv2EhQZPtJdM3689+hIyZWT/bXL2J8db2UHG+DYDqTnu1f8eY+AqsuOphCKw6q916L8M36RErtRFjxtYq9epsipjnG4nAKJRb8tx23xpEY0D1qHQiAMoAtI6FNcTj+tiYzZO757WMC4PbiyRdgSLjlNlSAeaLLKnPidQxLM+62MasL2rFpz8YZQ182vJXWvLE8fL6pXflwhoxqkyDZ9ySWInKEl+ydentxkCZkAj4htXRdF4bTX5KTXLzY11erHh4MaZZYYJk/jymid6dAqGJrTXsGrwVJB0JDVwThSxE6ashxAko9Ic1iLIDapXvUz6J8BZ2PSwAeu0Ed3RgbJ8vHby3R3alvVPNDGjvQqUqxAwhABKXdXRBY6Iw6oUETnMNHyeA9KBq0FcAVKomZS5fH7PIsse9lKqJP6YGUWBhc19H8iFowhbYdvpgDvW4uo4G/fJvLdXUnX1KIDR0wTxgEeI9dV66mwho7sa+EPxzTY/q5g2bGM3GpQDZTGaJyyTBu8IaawOZNEYLls+0T2B9pA0aBBrqV72IKbBC7/WdUcIUM+T9lqJdabCxM5b0g+pijFgkYfMWnmcM=",
  "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]": "Sunset Ave",
  "customer[address][number]": "713",
  "soft_descriptor": "Star Wars"
}'
Response200
{
  "status": "paid",
  "nsu": "98765432",
  "authorization_code": "112233",
  "date_created": "2025-01-15T19:44:04.883Z",
  "date_updated": "2025-01-15T19:44:04.883Z",
  "net_value": 1000000,
  "amount": 1039501,
  "paid_amount": 1039501,
  "installments": "1",
  "transaction_id": "98765432",
  "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."
}