Documentação
  1. GESTÃO DE TRANSAÇÕES
  2. Transações

Criar Transação com Cartão de Crédito

Esse endpoint permite a criação de uma nova transação no sistema da Paytime. É utilizada para registrar uma transação e obter os dados necessários para o seu processamento. O endpoint requer autenticação via cabeçalhos e os detalhes da transação devem ser fornecidos no corpo da requisição.

🔼

POST {urlServidor}/v1/marketplace/transactions

Obs: A palavra urlServidor deve ser substituída pela url do servidor.

Parâmetros da Requisição

Headers

NomeTipoObrigatórioDescrição
integration-keystringSimChave de integração.
x-tokenstringSimToken de autenticação. Pode ser encontrado em nosso portal na guia de integração.
AuthorizationAuth Type Bearer TokenSimInserir o Bearer Token, gerado na rota Auth
establishment_idstringSimId do estabelecimento que será gerado a transação

Exemplo de header da requisição

curl--request POST \
--location '{{server}/v1/marketplace/transactions' \
--header 'integration-key: your_integration_key' \
--header 'x-token: your_x_token' \
--header 'establishment_id;' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{bearer_token}}' \

Body

O corpo da requisição deve ser enviado no formato JSON, conforme descrito abaixo:

NomeTipoObrigatórioDescrição
payment_typestringSimTipo de transação. Valores permitidos: CREDIT (Crédito), PIX.
amountnumberSimValor da transação em centavos.
installmentsnumberNãoQuantidade de parcelas. Obrigatório somente para transações do tipo crédito.
intereststringSimCLIENT: o valor das taxas serão repassadas ao cliente, aumentando o valor bruto da transação. - STORE: o valor das taxas serão cobradas do estabelecimento, mantendo o valor bruto da transação.
reference_idstringNãoIdentificador definido pelo cliente, utilizado para controle interno. Limite máximo de 100 caracteres.
clientobjectCondicionalDados do cliente. Obrigatório em transações cŕedito, se usando antifraude.
client.addressobjectNãoEndereço do cliente. Obrigatório para transações do tipo crédito.
cardobjectNãoDados do cartão. Obrigatório para transações do tipo crédito.

Estrutura dos Objetos

👥Objeto cliente

NomeTipoObrigatórioDescrição
first_namestringSimNome/Razão Social do cliente.
last_namestringNãoSobrenome/nome fantasia do cliente.
documentstringSimCPF/CNPJ do cliente.
phonestringSimNúmero de telefone do cliente.
emailstringSimEmail do cliente.

🗺️ Objeto endereço

NomeTipoObrigatórioDescrição
streetstringSimLogradouro.
numberstringSimNúmero.
complementstringNãoComplemento.
neighborhoodstringSimBairro.
citystringSimCidade.
statestringSimEstado. Possíveis valores: AC, AL, AP, AM, BA, CE, DF, ES, GO, MA, MS, MT, MG, PA, PB, PR, PE, PI, RJ, RN, RS, RO, RR, SC, SP, SE, TO
zip_codestringSimCEP. Deve conter exatamente 8 caracteres.

💳 Objeto Cartão

NomeTipoObrigatórioDescrição
holder_namestringSimNome do portador do cartão.
holder_documentstringNãoCPF/CNPJ do portador do cartão.
card_numberstringSimNúmero do cartão.
expiration_monthnumberSimMês de expiração (1 a 12).
expiration_yearnumberSimAno de expiração.
security_codestringSimCódigo de segurança do cartão.
create_tokenbooleanNãoGerar Token com os dados do cartão.
tokenstringNãoToken gerado do cartão

🔐Campo tipo Antifraude

NomeTipoObrigatórioDescrição
antifraud_typestringNãoTipo de antifraude aplicado na transação. THREEDS: Autenticação 3DS. IDPAY: Verificação IDPAY.

🔀 Payload info_additional (opcional)

CampoTipoObrigatórioDescrição
info_additionalarrayOpcionalLista de pares chave-valor com informações adicionais da transação. Utilizado principalmente em transações do tipo PIX, podendo incluir identificadores adicionais definidos pelo parceiro.
info_additional[].keystringSimChave identificadora da informação adicional. Exemplo: "origin_system".
info_additional[].valuestringSimValor vinculado à chave. Exemplo: "ERP12345".

🔀 Payload split (opcional)

CampoTipoObrigatórioDescrição
split.titlestringSimTítulo para identificar o split na transação. Exemplo: "Comissão do Representante"
split.divisionstringSimTipo de divisão a ser aplicada entre os participantes. Valores possíveis: <br>• PERCENTAGE (porcentagem)<br>• CURRENCY (valor fixo)
split.establishmentsarraySimLista dos estabelecimentos que participarão do split.
split.establishments[].idnumberSimID do estabelecimento secundário. Este será o recebedor de parte do valor da transação.
split.establishments[].valuenumberSimValor que será destinado ao estabelecimento: <br>• Percentual, se division for PERCENTAGE <br>• Em centavos, se division for CURRENCY

Exemplo do Body para criar a transação

{
    "payment_type": "CREDIT",//Formato de cobrança a ser utilizado
    "amount":39001,
    "installments":1,//Número de parcelas da compra
    "interest": "ESTABLISHMENT",//Quem irá assumir as taxas de cobrança dos juros do cartão de crédito CLIENT=Cliente ou ESTABLISHMENT=Estabelecimento
    "reference_id":"fb67fd4c-2e6a-41dc-b05c-13ab3001d2a1",//ID de referência do Cliente
    "client": {
        "first_name":"João",//Primeiro nome do Cliente ou Estabelecimento
        "last_name": "da Silva",//Sobrenome e último nome do Cliente ou Estabelecimento
        "document": "1006811401",
        "phone": "31992876545",//Número de telefone do Cliente ou Estabelecimento
        "email": "[email protected]",//Email do Cliente ou Estabelecimento
        "address": {//Endereço do Cliente
            "street": "Rua Maria dos Desenvolvedores",//Endereço do Cliente ou Estabelecimento
            "number": "0101",//Número do endereço 
            "complement":"Debug",//Complemento do endereço
            "neighborhood": "Bairro Deploy",//Bairro que localiza o endereço
            "city": "Vitória",//Cidade que localiza o endereço
            "state": "ES",//Estado que localiza o endereço
            "country": "BR",//Pais que localiza o endereço
            "zip_code": "29090390"//CEP do endereço
        }
    },
    "card": {//Dados do cartão de crédito
        "holder_name": "João da Silva",//Nome do portador do cartão de crédito
        "holder_document": "58246374079",//Documento do portador do cartão de crédito
        "card_number": "5200000000001005",//Número do cartão de crédito
        "expiration_month": 12,//Mês de expiração do cartão de crédito
        "expiration_year":  2026,//Ano de expiração do cartão de crédito
        "security_code": "123",//CVC-Código de Verifcação do Cartão
        "create_token": true//Tokenização do Cartão, regras de antifraude pode ser aplicadas.
    },
    "antifraud_type":"IDPAY",//IDPAY ou THREEDS - Tipo de Antifraude
    "split": {
        "title": "Split Cartão Crédito",
        "division": "PERCENTAGE",
        "establishments": [
        {
            "id": 155100,//ID do estabelecimento
            "value":50
        }
        ]
    },
          "info_additional": [//Opcional
            {
            "key": "Origem",
            "value": "ClienteID"
            }
        ]
}

Exemplo de Resposta (200):

{
    "_id": "693b18d13296e51d4620e2b5",
    "status": "PENDING",
    "interest": "STORE",
    "establishment": {
        "id": 155085,
        "type": "INDIVIDUAL",
        "first_name": "EC  Cobranças API",
        "last_name": null,
        "document": "10068114001",
        "access_type": "ACQUIRER"
    },
    "marketplace": {
        "id": 26,
        "type": "LICENSED",
        "nickname": "Parceiro Integrações",
        "active": true,
        "first_name": "Webhooks Integrações",
        "last_name": "API Integrações",
        "document": "60274849000185"
    },
    "representative": {
        "id": 63,
        "marketplace_id": 26,
        "active": true,
        "first_name": "EC  Cobranças API",
        "last_name": null,
        "document": "10068114001"
    },
    "amount": 38065,
    "original_amount": 39001,
    "fees": 936,
    "type": "CREDIT",
    "gateway_key": "63425a53-938d-46fc-a6f5-db36f02486d6",
    "gateway_authorization": "PAYTIME",
    "card": {
        "brand_name": "MASTERCARD",
        "first4_digits": "5200",
        "last4_digits": "1005",
        "expiration_month": "12",
        "expiration_year": "2026",
        "holder_name": "JOÃO DA SILVA",
        "holder_document": "58246374079",
        "bin": "520000",
        "_id": "693b18d13296e51d4620e2b6"
    },
    "installments": 1,
    "customer": {
        "first_name": "João",
        "last_name": "da Silva",
        "document": "1006811401",
        "phone": "31992876545",
        "email": "[email protected]",
        "address": {
            "street": "Rua Maria dos Desenvolvedores",
            "number": "0101",
            "complement": "Debug",
            "neighborhood": "Bairro Deploy",
            "city": "Vitória",
            "state": "ES",
            "zip_code": "29000000"
        },
        "_id": "693b18d13296e51d4620e2b7"
    },
    "point_of_sale": {
        "type": "ONLINE",
        "identification_type": "API"
    },
    "acquirer": {
        "name": "PAGSEGURO",
        "_id": "693b18d13296e51d4620e2c3"
    },
    "expected_on": [
        {
            "date": "2026-01-12T12:00:00.986Z",
            "amount": 38065,
            "status": "PENDING",
            "installment": 1
        }
    ],
    "plan": {
        "id": 79,
        "name": "Plano Comercial Total Antifraude",
        "days_anticipation": 1,
        "allow_anticipation": false,
        "modality": "ONLINE",
        "flag": {
            "id": 1,
            "name": "MASTERCARD"
        }
    },
    "antifraud": [
        {
            "analyse_status": "WAITING_AUTH",
            "analyse_required": "IDPAY",
            "session": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiIwOGQyYTY5Yy05NmU5LTRjYjYtYjMzMy1iMjYwYTRhOWE5N2IiLCJjbGlkIjoiZjJlZDc4ZWYtYzU3Zi00MWZkLWI4MGMtNDczN2U0MjA3MWVlIiwiZXhwIjoxNzY1NzM5ODU4LCJleHRyYSQiOnsiY29uZmlncyI6eyJkeW5hbWljV3JhcHBlciI6ZmFsc2V9LCJkb21haW5zIjpbImh0dHBzOi8vZGV2LnBheXRpbWUuY29tLmJyIiwiaHR0cHM6Ly9pZHBheS50aWx0YnIuY29tLmJyIiwiaHR0cHM6Ly9zYW5kYm94LnBheXRpbWUuY29tLmJyIiwiaHR0cHM6Ly9sb2NhaG9zdDo4MCIsImh0dHBzOi8vbG9jYWhvc3Q6NDIwMCJdfSwiaWF0IjoxNzY1NDgwNjU4LCJpc3MiOiJodHRwczovL2lkcGF5LXVhdC51bmljby5pbyIsImp0aSI6ImVmM2UzNTJiLWQxNDEtNDhlNC04MzFhLTM3NzU0ZDRiOGVjMSIsInNjb3BlIjoiKiIsInN1YiI6ImJjOTg5OGQ1LTM2NDItNGZjYS1iNjIzLTE3ZWM1YmVlMjBjNiJ9.cJz7p0IxP4O3HIUwI4YExpH5c964zDaMRciZwOU8a-v46DIxJgnFlAViuT0QDzjRgRk9pPLhzPBJmD5u3mmQdrtq_dN-WUhrmQQWqquFqGrtjsNvyvJZcNywO9cWC3k76udLs886KuvI3NeDPaLyZm0MvXtDm2O0WxuRpQWQ3L-QkOM2Yk13B-3Y5ZnwFwL5a8niQzNTmztnI6ahTlATi6hH-Krivm59OHm52kjrkIKlRC924XfwIZbJ4bfzYX28lkqnN7eFWSX8qzW2WTEoWlihTu8Swu1bnLQCEsw2wt8az7hC8-AcqLgQRmuZIFi2oudRXGdw2_evYu9Nf3-44A",
            "_id": "693b18d23296e51d4620e2ca",
            "antifraud_id": "ef3e352b-d141-48e4-831a-37754d4b8ec1"
        }
    ],
    "created_at": "2025-12-11T19:17:37.992Z",
    "info_additional": [],
    "reference_id": "fb67fd4c-2e6a-41dc-b05c-13ab3001d2a1"
}

Requisição de Antifraude

Após executar a transação ela pode ficar com o status: PENDING e requerer a autenticação do Antifraude 3Ds ou IDPAY, onde no response da requisição contem o objeto antifraude que pode ter 2 comportamento:

Status da transação

Sua transação pode retornar os status listados abaixo. Você deve realizar o desenvolvimento para tratar na sua aplicação o que fazer com cada status.

CREATED = Transação criada

PENDING = Transação em processamento

PAID = Transação confirmada

APPROVED = (Depreciado) - Transação confirmada

FAILED= Transação Negada

REFUNDED = Transação estornada

DISPUTED= Transação em estado de disputa

CANCELED= Transação foi cancelada em algum momento

CHARGEBACK = Transação com CHARGEBACK aprovado

Códigos de Resposta

Consulte a página com os status: Status de respostas

Para mais detalhes sobre os parâmetros e funcionamento da API, acesse a documentação oficial da Paytime.

Updated 4 months ago

Did this page help you?