Skip to main content

Criar Transação

Para fazer uma cobrança você deve utilizar essa rota e criar a sua transação. Nesse primeiro momento deve ser usado todos os dados do cartão do cliente, futuramente podemos adicionar a opção de ser usado um HASH do cartão para aumentar ainda mais a segurança.

Nota

A Marlim possui a Certificação PCI-DSS (Payment Card Industry Data Security Standard), ou seja, todas as transações que passam pelos nossos servidores são criptografadas e seguem os mais altos padrões de segurança. Com isso, a Taya poderá passar os dados "abertos" do cartão para os nossos servidores sem se preocupar com a segurança dos dados.

POSTv1/transactions

Request Body Params​

AtributoTipoDescrição
amountint32Valor final a ser cobrado com as taxas. Deve ser passado em centavos.
net_valueint32Valor total da taxa de juros que foi cobrado na transação. 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.
authentication_idstringRepresenta o id da Autenticação do 3DS.
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.
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:

Valores aceitos: 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.
successful_fgts_proposalbooleanValidação se o cliente já obteve uma proposta do FGTS com sucesso anteriormente.
webhook_urlstringParâmetro opcional para receber notificações no seu sistema sobre todas as alterações de status de uma transação.
webhook_auth_tokenstringParâmetro opcional para autenticar as notificações enviadas para o webhook_url. Caso o parâmetro não seja informado, as notificações serão enviadas sem autenticação.
simulate_statusstringParâmetro opcional para "simular" alguns status durante a fase de desenvolvimento.

Valores aceitos: authorized, review, rejected e refused.

Response Object​

PropriedadeTipoDescrição
statusstringRepresenta o estado atual da transação. Valores possíveis: authorized, review, rejected e refused
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.
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 na Marlim.
item_idstringNúmero identificador da transação na sua plataforma.
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.

Webhooks​

Todo o processo de alteração do status de uma transação de saque é assíncrono. Portanto, é 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 alterações de status. Esta url da sua aplicação pode ser aberta para receber payloads dos servidores Marlim (você pode validar os payloads recebidos pela nossa aplicação), ou caso esta url exija autenticação, você pode passar um webhook_auth_token para o Marlim enviar os webhooks com autenticação no HEADER da requisição.

ValorDescrição
paidTransação paga e capturada com sucesso.
authorizedTransação autorizada e valor reservado no cartão. Pendente de captura.
reviewTransação em processo de revisão manual pelos nossos especialistas.
O valor foi autorizado e reservado no cartão, porém ainda não pode ser capturada.
rejectedTransação recusada pelo Antifraude Marlim.
refusedTransação recusada pelo banco emissor.
canceledTransação rejeitada após a revisão manual. O valor reservado no cartão foi cancelado e não pode mais ser capturado.
refundedTransação estornada. O valor pago foi devolvido ao cliente.
chargebackTransação sofreu chargeback. O valor pago pelo clinete será descontado da conta da Taya.
info

Se for passado algum valor no parâmetro webhook_auth_token a Marlim vai enviar o token para a sua aplicação usando o padrão no Header da requisição: Authorization: Bearer {webhook_auth_token}.

Caso nenhum valor seja passado em webhook_url, você poderá consultar o status atual da transação futuramente utilizando o endpoint GET e filtrando o cash-in, utilizando a propriedade cash_in_id.

🕹  Exemplo do BODY de um POST da Marlim para a sua aplicação
Request
curl -X POST "https://taya.com.br/webhooks" \
-H "Content-Type: application/json" \ 
-H "User-Agent: Marlim/1.0.0" \ 
-H "Marlim-Api-Signature: Star98765Wars43210ANewHope1977" \
-d '{
  "status": "authorized",
  "nsu": "032416400102",
  "date_created": "2024-04-08T16:39:09.312Z",
  "date_updated": "2024-04-08T16:39:09.312Z",
  "authorized_amount": 1000000,
  "paid_amount": 0,
  "refunded_amount": 0,
  "installments": "1",
  "transaction_id": "RSlg4dVGiwh028uFEU5k",
  "item_id": "987654321",
  "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."
}'
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 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_

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 Status de Transações​

Em ambiente Sandbox para facilitar o desenvolvimento é possível simular os status de uma transação utilizando o parâmetro simulate_status.

Alguns cenários comuns seriam criar uma transação com o status authorized e capturar futuramente ou criar uma transação com o status review e depois "simular" o comportamento de um revisor do Antifraude Marlim, alterando o status dessa transação para paid ou canceled. Com esse parâmetro é possível em desenvolvimento executar cenários similares ao que aconteceria em Produção.

ValorSignificado
authorizedSimula uma transação autorizada no banco emissor para ser capturada no futuro.
reviewSimula uma transação autorizada, porém que ainda não pode ser capturada, uma vez que está em processo de revisão manual.
rejectedSimula uma transação rejeitada pelo Antifraude da Marlim.
refusedSimula uma transação recusada no Banco Emissor.
Nessa simulação o valor em acquirer_status_code será randômico.
🕹  Criar uma transação com status authorized e capturar depois (paid)
Request
curl -X POST "https://api.taya.marlim.co/v1/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "simulate_status": "authorized",
  "successful_fgts_proposal": true,
  "net_value": 800000,
  "amount": 1000000,
  "installments": "1",
  "item_id": "ABC987654321",
  "item_url": "987654321",
  "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",
  "card_holder_name": "Luke Skywalker",
  "card_number": "5555444433332222",
  "card_expiration_date": "1122",
  "card_cvv": "123",
  "authentication_status": "AUTH_FLOW_COMPLETED",
  "authentication_auth_status": "AUTHENTICATED",
  "authentication_id": "3DS-C4669D-0DF8-48DF-BBB3-6E22FBA865AF",
  "webhook_url": "https://taya.com.br/webhooks",
  "webhook_auth_token": "ABCDEFGH1234567890",
  "soft_descriptor": "Star Wars"
}'
Response200
{
  "status": "authorized",
  "nsu": "032416400102",
  "date_created": "2024-04-08T16:39:09.312Z",
  "date_updated": "2024-04-08T17:39:09.312Z",
  "authorized_amount": 1000000,
  "paid_amount": 0,
  "refunded_amount": 0,
  "installments": "1",
  "transaction_id": "RSlg4dVGiwh028uFEU5k",
  "item_id": "ABC987654321",
  "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 que retorna uma Recusa Bancária (refused)
Request
curl -X POST "https://api.taya.marlim.co/v1/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "simulate_status": "refused",
  "successful_fgts_proposal": true,
  "net_value": 800000,
  "amount": 1000000,
  "installments": "1",
  "item_id": "ABC987654321",
  "item_url": "987654321",
  "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",
  "card_holder_name": "Luke Skywalker",
  "card_number": "5555444433332222",
  "card_expiration_date": "1122",
  "card_cvv": "123",
  "authentication_status": "AUTH_FLOW_COMPLETED",
  "authentication_auth_status": "AUTHENTICATED",
  "authentication_id": "3DS-C4669D-0DF8-48DF-BBB3-6E22FBA865AF",
  "webhook_url": "https://taya.com.br/webhooks",
  "webhook_auth_token": "ABCDEFGH1234567890",
  "soft_descriptor": "Star Wars"
}'
Response200
{
  "status": "rejected",
  "nsu": "032416400102",
  "date_created": "2024-04-08T16:39:09.313Z",
  "date_updated": "2024-04-08T17:39:09.313Z",
  "authorized_amount": 0,
  "paid_amount": 0,
  "refunded_amount": 0,
  "installments": "1",
  "transaction_id": "RSlg4dVGiwh028uFEU5k",
  "item_id": "ABC987654321",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "acquirer_status_code": "1011",
  "acquirer_status_message": "Some of the card numbers are incorrect. Check the numbers and try again."
}

Antifraude​

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 transaçã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 😎

🕹  Criar uma transação com status review, "aceitar" (authorized) e futuramente capturar (paid)
Request
curl -X POST "https://api.taya.marlim.co/v1/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "simulate_status": "review",
  "successful_fgts_proposal": true,
  "net_value": 800000,
  "amount": 1000000,
  "installments": "1",
  "item_id": "ABC987654321",
  "item_url": "987654321",
  "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",
  "card_holder_name": "Luke Skywalker",
  "card_number": "5555444433332222",
  "card_expiration_date": "1122",
  "card_cvv": "123",
  "authentication_status": "AUTH_FLOW_COMPLETED",
  "authentication_auth_status": "AUTHENTICATED",
  "authentication_id": "3DS-C4669D-0DF8-48DF-BBB3-6E22FBA865AF",
  "webhook_url": "https://taya.com.br/webhooks",
  "webhook_auth_token": "ABCDEFGH1234567890",
  "soft_descriptor": "Star Wars"
}'
Response200
{
  "status": "review",
  "nsu": "032416400102",
  "date_created": "2024-04-08T16:39:09.313Z",
  "date_updated": "2024-04-08T17:39:09.313Z",
  "authorized_amount": 1000000,
  "paid_amount": 0,
  "refunded_amount": 0,
  "installments": "1",
  "transaction_id": "RSlg4dVGiwh028uFEU5k",
  "item_id": "ABC987654321",
  "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 review, "rejeitar" (rejected) e automaticamente cancelar (canceled)
Request
curl -X POST "https://api.taya.marlim.co/v1/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "simulate_status": "review",
  "successful_fgts_proposal": true,
  "net_value": 800000,
  "amount": 1000000,
  "installments": "1",
  "item_id": "ABC987654321",
  "item_url": "987654321",
  "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",
  "card_holder_name": "Luke Skywalker",
  "card_number": "5555444433332222",
  "card_expiration_date": "1122",
  "card_cvv": "123",
  "authentication_status": "AUTH_FLOW_COMPLETED",
  "authentication_auth_status": "AUTHENTICATED",
  "authentication_id": "3DS-C4669D-0DF8-48DF-BBB3-6E22FBA865AF",
  "webhook_url": "https://taya.com.br/webhooks",
  "webhook_auth_token": "ABCDEFGH1234567890",
  "soft_descriptor": "Star Wars"
}'
Response200
{
  "status": "review",
  "nsu": "032416400102",
  "date_created": "2024-04-08T16:39:09.313Z",
  "date_updated": "2024-04-08T17:39:09.313Z",
  "authorized_amount": 1000000,
  "paid_amount": 0,
  "refunded_amount": 0,
  "installments": "1",
  "transaction_id": "RSlg4dVGiwh028uFEU5k",
  "item_id": "ABC987654321",
  "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.taya.marlim.co/v1/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "simulate_status": "rejected",
  "successful_fgts_proposal": true,
  "net_value": 800000,
  "amount": 1000000,
  "installments": "1",
  "item_id": "ABC987654321",
  "item_url": "987654321",
  "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",
  "card_holder_name": "Luke Skywalker",
  "card_number": "5555444433332222",
  "card_expiration_date": "1122",
  "card_cvv": "123",
  "authentication_status": "AUTH_FLOW_COMPLETED",
  "authentication_auth_status": "AUTHENTICATED",
  "authentication_id": "3DS-C4669D-0DF8-48DF-BBB3-6E22FBA865AF",
  "webhook_url": "https://taya.com.br/webhooks",
  "webhook_auth_token": "ABCDEFGH1234567890",
  "soft_descriptor": "Star Wars"
}'
Response200
{
  "status": "rejected",
  "nsu": null,
  "date_created": "2024-04-08T16:39:09.313Z",
  "date_updated": "2024-04-08T17:39:09.313Z",
  "authorized_amount": 0,
  "paid_amount": 0,
  "refunded_amount": 0,
  "installments": "1",
  "transaction_id": "RSlg4dVGiwh028uFEU5k",
  "item_id": "ABC987654321",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "acquirer_status_code": null,
  "acquirer_status_message": null
}
Atenção

O parâmetro simulate_status e o endpoint v1/antifraud só são habilitados para api_key do Ambiente Sandbox. Se for utilizado um dos 2 em Ambiente de Produção, será retornado um erro 403 (Forbidden).

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.taya.marlim.co/v1/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "successful_fgts_proposal": true,
  "net_value": 800000,
  "amount": 1000000,
  "installments": "1",
  "item_id": "ABC987654321",
  "item_url": "987654321",
  "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",
  "card_holder_name": "Luke Skywalker",
  "card_number": "5555444433332222",
  "card_expiration_date": "1122",
  "card_cvv": "123",
  "authentication_status": "AUTH_FLOW_COMPLETED",
  "authentication_auth_status": "AUTHENTICATED",
  "authentication_id": "3DS-C4669D-0DF8-48DF-BBB3-6E22FBA865AF",
  "webhook_url": "https://taya.com.br/webhooks",
  "webhook_auth_token": "ABCDEFGH1234567890",
  "soft_descriptor": "Star Wars"
}'
Response200
{
  "status": "paid",
  "nsu": "032416400102",
  "date_created": "2024-04-08T16:39:09.313Z",
  "date_updated": "2024-04-08T17:39:09.313Z",
  "authorized_amount": 1000000,
  "paid_amount": 1000000,
  "refunded_amount": 0,
  "installments": "1",
  "transaction_id": "RSlg4dVGiwh028uFEU5k",
  "item_id": "ABC987654321",
  "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."
}