Criar pagamento

Fazendo Requisição

A chamada deverá ser feita utilizando o método POST. É necessária a autenticação via Authorization header.

POST/v1/card_payments

Descrição dos atributos

Atributo	Tipo	Descrição	Obrigatório
`card_expiration_date`	string	Data de expiração do cartão, no formato MMyyyy (ex.: `012029`)	Parcial
`card_number`	string	Número do cartão, sem espaços ou traços	Parcial
`card_security_code`	string	Código de segurança (CVV/CVC)	Parcial
`slug_token`	string	Uma sequência alfanumérica de 32 caracteres que representa um cartão tokenizado pelo endpoint `/v1/tokenize_card`. Pode ser usada em vez de `card_number`, `card_expiration_date` e `card_security_code`.	Não
`slug_stored_card`	string	Uma sequência alfanumérica de 32 caracteres que representa um cartão armazenado no cofre de cartões pelo endpoint `/v1/tokenize_card`. Pode ser usada em vez de `card_number`, `card_expiration_date` e `card_security_code`.	Não
`card_holder_document`	string	Documento do portador do cartão (CPF ou CNPJ, apenas números)	Sim
`card_holder_name`	string	Nome do portador impresso no cartão	Sim
`installments`	integer	Número de parcelas (entre 1 e 12) Caso não seja enviado o padrão é de 1 parcela	Não
`payment_type`	string	Tipo de pagamento (CREDIT ou DEBIT) Caso não seja enviado o padrão é CREDIT	Não
`currency`	string	Moeda da transação (BRL) Caso não seja enviado o padrão é BRL	Sim
`amount`	integer	Valor do pagamento em centavos (ex.: `100` = R$ 1,00)	Sim
`platform_name`	string	Nome da plataforma que está gerando o checkout	Não
`billing_url`	string	URL para redirecionar o usuário para a página customizada de cobrança	Não
`return_url`	string	URL do webhook onde as notificações serão enviadas	Não
`xid`	string	O identificador da transação, uma string base64 de tamanho 28	Não
`cavv`	string	O Valor de Verificação de Autenticação do Titular do Cartão, uma string base64 de tamanho 32. Este campo recebe o valor CAVV para as bandeiras de cartão Visa e Elo e o valor UCAF para Mastercard. É obrigatório para todas as transações 3DS	Não
`cavv_result_code`	string	O código de resultado do CAVV (tamanho 1). Valores: Espaço (Não validado), 0 (Dados incorretos), 1 (Falha), 2 (Aprovada), 3 (Tentativa incompleta), 4 (Erro sistema)	Não
`secure_version`	string	A versão 3DS no formato x.y. É necessária para todas as transações 3DS	Não
`directory_server_transaction_id`	string	Identificador da transação no servidor da Mastercard. Formato alfanumérico com 32 caracteres. Requerido apenas para transações Master 3DS	Não
`three_ds_server_transaction_id`	string	O ID da transação fornecido pelo autenticador. Formato alfanumérico com 32 caracteres. Necessário apenas para transações Amex 3DS	Não
`billing_address`	object	Dados do endereço de cobrança(Para transações a partir de R$150.00)	Não
`billing_address.street`	string	Rua do endereço de cobrança	Não
`billing_address.number`	string	Número do endereço de cobrança	Não
`billing_address.neighborhood`	string	Bairro do endereço de cobrança	Não
`billing_address.city`	string	Cidade do endereço de cobrança	Não
`billing_address.state`	string	Estado do endereço de cobrança	Não
`billing_address.zip_code`	string	CEP do endereço de cobrança	Não
`billing_address.complement`	string	Complemento do endereço de cobrança	Não

Exemplo de Requisição (Padrão)

POST /v1/card_payments

HTTP Request Body
{
  "card_payment": {
    "card_expiration_date": "012029",
    "card_holder_document": "00000000000",
    "card_security_code": "123",
    "card_holder_name": "John Doe",
    "installments": 1,
    "payment_type": "CREDIT",
    "card_number": "4111111111111111",
    "currency": "BRL",
    "amount": 100,
    "platform_name": "string",
    "billing_url": "string",
    "return_url": "string",
    "xid": "string",
    "cavv": "string",
    "cavv_result_code": "string",
    "secure_version": "string",
    "directory_server_transaction_id": "string",
    "three_ds_server_transaction_id": "string"
    
  }
}

Exemplo de Requisição (Maior ou igual a R$150.00)

POST /v1/card_payments

HTTP Request Body
{
  "card_payment": {
    "card_expiration_date": "012029",
    "card_holder_document": "00000000000",
    "card_security_code": "123",
    "card_holder_name": "John Doe",
    "installments": 1,
    "payment_type": "CREDIT",
    "card_number": "4111111111111111",
    "currency": "BRL",
    "amount": 15000,
    "platform_name": "string",
    "billing_url": "string",
    "return_url": "string",
    "xid": "string",
    "cavv": "string",
    "cavv_result_code": "string",
    "secure_version": "string",
    "directory_server_transaction_id": "string",
    "three_ds_server_transaction_id": "string",
    "billing_address": {
      "street": "string",
      "number": "string",
      "neighborhood": "string",
      "city": "string",
      "state": "string",
      "zip_code": "string",
      "complement": "string"
    }
  }
}

Exemplo de Requisição(Zero Dollar) → Validação de cartão

POST /v1/card_payments

HTTP Request Body(Zero Dollar)  - Validação de cartão - Exemplo
{
  "card_payment": {
    "card_expiration_date": "012029",
    "card_security_code": "123",
    "card_holder_name": "John Doe",
    "card_holder_document": "00000000000",
    "card_number": "4111111111111111",
    "amount": 0,
    "platform_name": "string",
    "billing_url": "string",
    "return_url": "string",
    "xid": "string",
    "cavv": "string",
    "cavv_result_code": "string",
    "secure_version": "string",
    "directory_server_transaction_id": "string",
    "three_ds_server_transaction_id": "string"
  }
}

Exemplo de Requisição (Slug Token)

POST /v1/card_payments

HTTP Request Body Slug Token - Exemplo
{
  "card_payment": {
    "slug_token": "XXXXXXXXXXX",
    "card_holder_document": "00000000000",
    "card_holder_name": "John Doe",
    "installments": 1,
    "payment_type": "CREDIT",
    "currency": "BRL",
    "amount": 100,
    "platform_name": "string",
    "billing_url": "string",
    "return_url": "string",
    "xid": "string",
    "cavv": "string",
    "cavv_result_code": "string",
    "secure_version": "string",
    "directory_server_transaction_id": "string",
    "three_ds_server_transaction_id": "string"
  }
}

Exemplo de Requisição (Stored Card)

POST /v1/card_payments

HTTP Request Body Stored Card - Exemplo
{
  "card_payment": {
    "slug_stored_card": "XXXXXXXXXXX",
    "card_holder_document": "00000000000",
    "card_holder_name": "John Doe",
    "installments": 1,
    "payment_type": "CREDIT",
    "currency": "BRL",
    "amount": 100,
    "platform_name": "string",
    "billing_url": "string",
    "return_url": "string",  
    "xid": "string",
    "cavv": "string",
    "cavv_result_code": "string",
    "secure_version": "string",
    "directory_server_transaction_id": "string",
    "three_ds_server_transaction_id": "string"
  }
}

Sucesso

Após a chamada, é retornado um JSON com o status 201 - Created caso o procedimento tenha ocorrido com sucesso.

HTTP 201 Response Body - Exemplo
{
  "card_payment": {
    "muid": "7bcedaa6-1c58-4ae6-a7ca-3c4628967049",
    "external_id": "seu-external-id",
    "slug": null,
    "rrn": "123456789012",
    "amount": 1000,
    "currency": "BRL",
    "status": "approved",
    "last_digits": "4321",
    "installments": 2,
    "tracking_number": "7bcedaa6-1c58-4ae6-a7ca-3c4628967049",
    "card_holder_name": "John Doe",
    "card_holder_email": null,
    "card_holder_document": "12345678901",
    "brand": "Visa",
    "request_token": "req_tok_abc123xyz",
    "payment_type": "credit",
    "authorization_code": "A1B2C3",
    "refund_tracking_number": null,
    "first_digits": "411111",
    "active": true,
    "slug_authorizer": "7bcedaa6-1c58-4ae6-a7ca-3c4628967049",
    "slug_customer": "7bcedaa6-1c58-4ae6-a7ca-3c4628967049",
    "slug_terminal": "7bcedaa6-1c58-4ae6-a7ca-3c4628967049",
    "slug_merchant": "7bcedaa6-1c58-4ae6-a7ca-3c4628967049",
    "sales_channel": null,
    "authorizer_merchant_id": "M1234567",
    "authorizer_terminal_id": "T7654321",
    "transaction_status": "authorized",
    "product_or_issuer": null,
    "settlement_management_type": null,
    "transaction_method": "",
    "cancelling": false,
    "platform_name": "string",
    "billing_url": "string",
    "return_url": "string",
    "xid": "string",
    "cavv": "string",
    "cavv_result_code": "string",
    "secure_version": "string",
    "directory_server_transaction_id": "string",
    "three_ds_server_transaction_id": "string",
    "created_at": "2025-09-11T19:45:00Z"
  }
}

Eventos Notificados

O sistema irá enviar notificações para todos os status disponíveis da transação.
Isso vale para Checkout, PixQrCode e Cartão
Qualquer mudança de status (Criação, confirmação, cancelamento, etc.) resultará em uma chamada ao webhook configurado na criação da transação.
As notificações seguirão exatamente o mesmo padrão de dados já utilizados pelo webhook existente, garantindo compatibilidade e consistência na integração.

Entre nesta página para mais detalhes sobre Webhook - Notificação do cartão

Erros

Em caso de erros, será retornado um json com o atributo error especificando o motivo de a operação ter sido invalidada.

HTTP 422 Response Body  - Unprocessable Entity - Exemplo
  {
    "errors": [
        {
            "code": "AUTHORIZER_REJECTED",
            "msg": "46 - Identification required"
        }
    ],
    "muid": "f251e1b753504766957cf4142e936262",
    "request_token": "83329FF45587498D88E1590C7FB78CD8",
    "amount": 1,
    "currency": "BRL",
    "tracking_number": "00010609171144580010000000324834",
    "last_digits": "1111",
    "transaction_status": "REJECTED",
    "brand_response_code": "83",
    "multiacq_id": "021"
}

🔹 Atributos Importantes da Resposta

Atributo	Descrição
`muid`	Identificador único da transação
`external_id`	Identificador único external, criado pelo cliente
`amount`	Valor da transação
`rrn`	Retrieval Reference Number (referência do adquirente/banco)
`status`	Código de resposta da transação (`accepted`, `reject` e `waiting_3ds_authentication`)
`transaction_status`	Status da transação (`pending`, `pre_authorized`, `authorized`, `denied`, `canceled`, `expired`, `refunded`, `waiting`)
`authorization_code`	Código de autorização retornado pela adquirente
`last_digits`	Últimos 4 dígitos do cartão
`installments`	Número de parcelas
`created_at`	Data/hora da criação da transação
`code`	Código de erro da transação(encontrado dentro do array `errors`)
`msg`	Descrição do erro retornado(encontrado dentro do array `errors`)

🔹 Códigos de Resposta

200 OK – Pagamento processado com sucesso
422 Unprocessable Entity – Dados inválidos (ex.: formato incorreto de CPF ou número do cartão)
401 Unauthorized – Falha de autenticação/autorização na API
500 Internal Server Error – Erro interno no processamento

Tabela de Erros do Gateway

Código de Erro	Mensagem	Descrição
MIN_INSTALLMENTS	Installments can't be lower than 1	O número de parcelas não pode ser menor que 1.
MAX_INSTALLMENTS	Installments can't the higher than 12	O número de parcelas não pode ser maior que 12.
INVALID_MONTH_NUMBER	Incorrect expiration date. Invalid month number.	Quando o mês da data de expiração do cartão é inválido.
INCORRECT_EXPIRATION_DATE	Incorrect expiration date. Correct format is MMyyyy.	Quando a data de expiração do cartão é diferente do formato correto (mmYYYY).
EXPIRATION_DATE_NON_NUMERIC	Expiration date has non-numeric character.	Quando a data de expiração do cartão possui caracteres não numéricos.
MSG_GENERAL_ERROR	Unknown Card Brand.	Quando o número do cartão tem mais de 19 dígitos ou está vazio.
AMOUNT_REQUIRED	Amount required.	Transação sem envio do campo valor.
CURRENCY_REQUIRED	Currency required.	Transação sem envio do campo moeda.
FIELDS_REQUIRED	The following fields are required: expirationDate	Ao tentar enviar uma transação, verifique a data de expiração.
INVALID_CVV	Invalid CVV. CVV should be 3 digits.	Quando o código de segurança do cartão é diferente de 3 dígitos (exceto AMEX) e/ou não é numérico.
CURRENCY_NOT_SUPPORTED	Currency not supported. Please refer to our documentation to see supported currencies.	Ao tentar enviar uma transação, verifique a moeda suportada.
CURRENCY_INVALID_FORMAT	Currency must be notated in ISO 4217 currency code.	Ao tentar enviar uma transação, verifique o formato de moeda suportado.
INVALID_AMOUNT	Invalid Amount	O campo valor é inválido.
AMOUNT_NOT_SUPPORTED	Amount can't be higher than 100 million	Valores maiores que 100 milhões não são suportados.
AMOUNT_OUT_OF_BOUNDS	Amount value out of bounds (max 2 digits expected for fraction)	Quando o valor tem mais de dois dígitos após o ponto decimal.
SPLIT_VALUE_TOO_HIGH	Splits total value can't be equal or higher than the transaction amount.	Ao tentar enviar uma transação, verifique que o valor total das divisões não pode ser igual ou maior que o valor da transação.
EMPTY_SPLIT	Field splits can't be empty if splitValueType field is present	Ao tentar enviar uma transação, verifique se o campo splits não pode estar vazio se o campo splitValueType estiver presente.
EMPTY_SPLIT_TYPE	Field splitValueType can't be empty if splits field is present	Ao tentar enviar uma transação, o campo splitValueType não pode estar vazio se o campo splits estiver presente.
OWNER_IN_SPLIT	Merchant executing the transaction must not be on splits field	Se você é quem está executando a divisão, não deve estar incluído no campo split.
SPLIT_MERCHANT_DUPLICATION	Can't have duplicated documentId in split	Ao tentar enviar uma transação, não é possível ter um documentId duplicado.
INVALID_INSTALLMENTS_PLAN_ENTRY	Installments plan entry cannot be the same as or lower than the previous entry.	Ao tentar enviar uma transação, o valor da entrada do plano de parcelamento não deve ser igual ou menor que a entrada anterior.
INSTALLMENTSPLAN_ENTRIES_AND_INSTALLMENTSMISMATCH	InstallmentsPlan should have the same amount of entries as the installments field value.	Ao tentar enviar uma transação, o plano de parcelamento deve ter a mesma quantidade de entradas que o valor do campo de parcelas.
INSTALLMENTS_PLAN_CANT_BE_EMPTY	Installments plan cannot be empty.	Ao tentar enviar uma transação, o plano de parcelamento não pode estar vazio.
INVALID_NULL_OR_ZERO_INSTALLMENTS_PLAN_ENTRY	Installments plan entries cannot be null nor 0 (zero).	Ao tentar enviar uma transação, não é possível enviar parcelas nulas ou 0 (zero).
CUSTOM_NOT_ALLOWED	Customer not allowed for custom installment plan transaction.	Cliente não permitido para transação com plano de parcelamento personalizado.
CARDBRAND_NOT_ALLOWED	Cardbrand must be Visa for custom installment plan transactions.	A bandeira do cartão deve ser Visa para transações com plano de parcelamento personalizado.
MSG_GENERAL_ERROR	These documentId were not found: "S"	document_id não encontrado.
MSG_GENERAL_ERROR	The following merchants aren't enabled to process CNP with authorizer POSTILION: "S"	Comerciante não habilitado para processar CNP.
Split value must be higher than zero	Split value must be higher than zero	Ao tentar enviar uma transação, o valor da divisão deve ser maior que zero.
Can't have more than 20 splits entries	Can't have more than 20 splits entries	Ao tentar enviar uma transação, não é possível ter mais de 20 entradas de divisão.

Fazendo Requisição​

Exemplo de Requisição (Padrão)​

Exemplo de Requisição (Maior ou igual a R$150.00)​

Exemplo de Requisição(Zero Dollar) → Validação de cartão​

Exemplo de Requisição (Slug Token)​

Exemplo de Requisição (Stored Card)​

Sucesso​

Eventos Notificados​

Erros​

🔹 Atributos Importantes da Resposta​

🔹 Códigos de Resposta​

Tabela de Erros do Gateway​