A credit card payment happens in two steps, in this order:

1. Tokenization — the sensitive card data (number, CVV, expiry) is exchanged for a single-use token. It is this token, never the card number, that travels to the payment API.
2. Payment — the token is sent to POST /v1/payments/credit-card, along with order_id and customer_id, to complete the charge.

Testing in sandbox? Check the test cards at the end of this page.

Tokenizing from the front-end?

At checkout, tokenization is usually done by appmax.js via CDN — see Appmax JS. The endpoint in step 1 documents the underlying contract, useful for custom implementations (without the script) and for debugging.

1. Tokenization

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. Payment

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

Test cards

To test the flow in the sandbox environment, use the cards below with a future expiration date:

Card number	Scenario
4000000000000010	Approved and captured. The order becomes aprovado, with paid_at and captured_at set.
4000000000000028	Approved without capture (pre-authorization). The order becomes autorizado, captured_at null.
4000000000000002	Declined by the issuer. The payment returns an error and the order is canceled.
4000000000000036	Transaction error. Processing failure; the payment returns an error.
4000000000000044	Order failed. The order fails at the gateway; the payment returns an error.
4000000000009999	Gateway unavailable. Simulates a payment-provider outage.
Any other card	Declined.

The scenarios work both when sending the card data directly to POST /v1/payments/credit-card and in the tokenized flow (POST /v1/payments/tokenize, then paying with the token): a token minted from a test card reproduces that card's scenario.

TIP

Use card 4000000000000010 to test the full successful payment flow, and card 4000000000000002 to test payment error handling. Note that 4000000000000028 approves the transaction, it just does not capture it.