O pagamento com cartão de crédito acontece em duas etapas, nesta ordem:

1. Tokenização — os dados sensíveis do cartão (número, CVV, validade) são trocados por um token, e é ele — nunca o número do cartão — que trafega até a API de pagamento.
2. Pagamento — o token é enviado em POST /v1/payments/credit-card, junto com order_id e customer_id, para efetivar a cobrança.

Vai testar no sandbox? Consulte os cartões de teste no fim desta página.

Tokenizando pelo front-end?

No checkout, a tokenização normalmente é feita pelo appmax.js via CDN — veja Appmax JS. O endpoint da etapa 1 documenta o contrato subjacente, útil para implementações custom (sem o script) e para debug.

1. Tokenização

Tokenização de cartão de crédito

POST

/v1/payments/tokenize

Substitui os dados reais do cartão (número, CVV, validade) por um token único e seguro, permitindo realizar transações sem expor as informações originais.

Tokenização server-side exige PCI-DSS

Quando você tokeniza pelo seu backend, o seu servidor toca o número de cartão e o CVV em claro. Isso só é permitido se sua arquitetura está em escopo PCI-DSS. Se você não tem certeza, use o caminho via CDN — o script Appmax JS isola os dados sensíveis do seu servidor.

Existem dois caminhos de autenticação distintos para este endpoint: via CDN (header external-id) ou via backend (header Authorization: Bearer). Veja external-id para o contexto.

Autorizações

bearerAuth

Token Bearer do merchant obtido via POST /oauth2/token usando as credenciais do merchant (não do app). Veja Autenticação.

Tipo

HTTP (bearer)

Corpo da Requisição

application/json

{

  

"payment_data": {

  

  

"credit_card": {

  

  

  

"number": "4444222222222222",

  

  

  

"cvv": "123",

  

  

  

"expiration_month": "12",

  

  

  

"expiration_year": "28",

  

  

  

"holder_name": "John Doe"

  

  

}

  

}

}

Respostas

Token gerado com sucesso.

Content-Type

application/json

POST

/v1/payments/tokenize

Exemplos

Sandboxhttps://api.sandboxappmax.com.br

Authorization (Bearer)

Cole uma vez e use em todos os playgrounds — o token fica salvo somente nesta aba do navegador e é apagado quando ela for fechada.

Corpo

{
  "payment_data": {
    "credit_card": {
      "number": "4444222222222222",
      "cvv": "123",
      "expiration_month": "12",
      "expiration_year": "28",
      "holder_name": "John Doe"
    }
  }
}

Duplo clique no JSON para editar

2. Pagamento

Pagamento com cartão de crédito

POST

/v1/payments/credit-card

Cria um pagamento por cartão de crédito vinculado a um pedido existente. Permite parcelamento e personalização do soft descriptor.

WARNING

Antes de criar um pagamento, você precisa ter:

• order_id — ID do pedido (criar pedido)
• customer_id — ID do cliente (criar cliente)

INFO

Consulte Cálculo de parcelas para obter os valores corretos com as taxas configuradas antes de enviar um pagamento parcelado.

Autorizações

bearerAuth

Token Bearer do merchant obtido via POST /oauth2/token usando as credenciais do merchant (não do app). Veja Autenticação.

Tipo

HTTP (bearer)

Corpo da Requisição

application/json

{

  

"order_id": 12345,

  

"customer_id": 407,

  

"payment_data": {

  

  

"credit_card": {

  

  

  

"token": "422146c7523a46119d6073ea56193913",

  

  

  

"holder_document_number": "19100000000",

  

  

  

"holder_name": "Teste teste",

  

  

  

"installments": 1,

  

  

  

"soft_descriptor": "MYSTORE"

  

  

}

  

}

}

Respostas

Pagamento criado com sucesso.

Content-Type

application/json

POST

/v1/payments/credit-card

Exemplos

Sandboxhttps://api.sandboxappmax.com.br

Authorization (Bearer)

Cole uma vez e use em todos os playgrounds — o token fica salvo somente nesta aba do navegador e é apagado quando ela for fechada.

Corpo

{
  "order_id": 12345,
  "customer_id": 407,
  "payment_data": {
    "credit_card": {
      "token": "422146c7523a46119d6073ea56193913",
      "holder_document_number": "19100000000",
      "holder_name": "Teste teste",
      "installments": 1,
      "soft_descriptor": "MYSTORE"
    }
  }
}

Duplo clique no JSON para editar

Cartões de teste

Para testar o fluxo no ambiente de sandbox, utilize os cartões abaixo com uma data de expiração futura:

Número do cartão	Cenário
4000000000000010	Aprovado e capturado. O pedido fica aprovado, com paid_at e captured_at preenchidos.
4000000000000028	Aprovado sem captura (pré-autorização). O pedido fica autorizado, com captured_at vazio.
4000000000000002	Recusado pelo emissor. O pagamento retorna erro e o pedido é cancelado.
4000000000000036	Erro na transação. Falha no processamento; o pagamento retorna erro.
4000000000000044	Falha no pedido. O pedido falha no gateway; o pagamento retorna erro.
4000000000009999	Gateway indisponível. Simula indisponibilidade do provedor de pagamento.
Qualquer outro cartão	Recusado.

Os cenários valem tanto enviando os dados do cartão diretamente em POST /v1/payments/credit-card quanto no fluxo tokenizado (POST /v1/payments/tokenize e depois o pagamento com o token): o token gerado a partir de um cartão de teste reproduz o cenário dele.

Testando Pix ou boleto? Eles não usam cartões de teste: no sandbox são aprovados automaticamente, e há documentos específicos para manter o pedido pendente. Veja Testar no sandbox.

TIP

Utilize o cartão 4000000000000010 para testar o fluxo completo de pagamento com sucesso, e o cartão 4000000000000002 para testar o tratamento de erros de pagamento. Repare que o 4000000000000028 aprova a transação, apenas sem capturar.