Credit Card Payments with CertoPay: Visa, Mastercard, Elo

CertoPay supports credit card payments for the three most widely issued card brands in Brazil — Visa, Mastercard, Elo, Hipercard, Hiper, American Express, Diners Club, JCB, Aura, Discover. Charges are authorized and captured in a single step, so an approved response with status: CAPTURED means funds are already reserved. You can split payments into up to 12 installments (parcelamento), and for repeat customers or subscription products you can tokenize the card and charge the stored token on future orders without asking the buyer to re-enter their details.

Supported Brands

Brand	Single charge	Installments	Tokenization
Visa	✅	✅ Up to 12×	✅
Mastercard	✅	✅ Up to 12×	✅
Elo	✅	✅ Up to 12×	✅
Hipercard	✅	✅ Up to 12×	✅
Hiper	✅	✅ Up to 12×	✅
American Expess	✅	✅ Up to 12×	✅
Diners Club	✅	✅ Up to 12×	✅
JCB	✅	✅ Up to 12×	✅
Aura	✅	✅ Up to 12×	✅
Discover	✅	✅ Up to 12×	✅

Two Ways to Charge a Card

Option A — Direct Card Data
Option B — Card Token (Recurring)

Send the full card details in the payment request. This is the simplest integration path for one-time purchases.

Your server must handle raw card numbers only over HTTPS. Never log or store card numbers, CVVs, or expiry dates — this is a PCI DSS requirement. For repeat customers, use Option B (tokenization) instead.

Request

POST /api/payment-gateway/process
X-Api-Key: sk_live_sua_chave_aqui
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440003
Content-Type: application/json

{
  "orderId": "uuid-do-pedido",
  "method": "CARD",
  "amount": 29700,
  "installments": 3,
  "cardHolderName": "JOAO DA SILVA",
  "cardNumber": "4111111111111111",
  "cardExpirationMonth": "12",
  "cardExpirationYear": "28",
  "cardSecurityCode": "123",
  "cardBrand": "Visa",
  "buyerDoc": "12345678900",
  "buyerBirthdate": "1990-05-20",
  "buyerCellNumber": "(11) 99999-9999",
  "buyerAddress": {
    "postal_code": "01310930",
    "street": "Avenida Paulista",
    "number": "100",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP"
  }
}

Request Fields

orderId

string

required

The unique identifier for the order, obtained from POST /api/orders.

method

string

required

Must be "CARD" to route the charge through the credit card rail.

amount

integer

required

The total charge amount in centavos. Example: R$ 297,00 → 29700.

installments

integer

required

Number of installments. Use 1 for a single charge, or 2–12 to split the payment. The total amount is divided equally across installments.

cardHolderName

string

required

Cardholder name exactly as printed on the card, in uppercase. Example: "JOAO DA SILVA".

cardNumber

string

required

Full card number, digits only, no spaces or dashes. Example: "4111111111111111".

cardExpirationMonth

string

required

Two-digit expiration month. Example: "12".

cardExpirationYear

string

required

Two-digit expiration year. Example: "28" for 2028.

cardSecurityCode

string

required

Card security code (CVV/CVC) — 3 digits for Visa/Mastercard/Elo. Never store this value.

cardBrand

string

required

Card brand. Accepted values: "Visa", "Mastercard", "Elo".

buyerDoc

string

required

Buyer’s CPF — exactly 11 numeric digits, no punctuation. Example: "12345678900".

buyerBirthdate

string

required

Buyer’s date of birth in YYYY-MM-DD format. Example: "1990-05-20".

buyerCellNumber

string

required

Buyer’s mobile phone number with area code (DDD). Example: "(11) 99999-9999".

buyerAddress

object

required

Buyer’s billing address.

Show buyerAddress fields

postal_code

string

required

Brazilian postal code (CEP), 8 digits. Example: "01310930".

street

string

required

Street name. Example: "Avenida Paulista".

number

string

required

Street number. Example: "100".

neighborhood

string

required

Neighborhood (bairro). Example: "Bela Vista".

city

string

required

City name. Example: "São Paulo".

state

string

required

Two-letter state abbreviation (UF). Example: "SP".

Tokenize the card once, then charge the stored token on every subsequent order. The buyer only enters card details one time, and you never store raw card data on your servers.

Card tokenization is strongly recommended for subscription products, membership sites, and any checkout flow where buyers return for repeat purchases. It improves conversion rates (no re-entry friction) and keeps your PCI DSS scope minimal.

Step 1 — Tokenize the Card

Call the tokenize endpoint when the buyer saves their card (e.g., during account setup or their first checkout):

POST /api/payment-gateway/tokenize-card
X-Api-Key: sk_live_sua_chave_aqui
Content-Type: application/json

{
  "customerId": "uuid-do-customer",
  "doc": "12345678900",
  "holderName": "JOAO DA SILVA",
  "cardNumber": "4111111111111111",
  "brand": "Visa",
  "expirationMonth": "12",
  "expirationYear": "28",
  "securityCode": "123",
  "birthdate": "1990-05-20",
  "cellNumber": "(11) 99999-9999",
  "address": {
    "postal_code": "01310930",
    "street": "Avenida Paulista",
    "number": "100",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP"
  }
}

Tokenize response:

{
  "cardToken": "tok_abc123..."
}

Store cardToken against the customer record in your database. This token represents the card and can be reused for any number of future charges.

Tokenize Request Fields

customerId

string

required

Your internal customer UUID. CertoPay links the token to this customer ID so you can manage multiple saved cards per customer.

doc

string

required

Customer’s CPF — 11 numeric digits. Example: "12345678900".

holderName

string

required

Cardholder name in uppercase, as printed on the card.

cardNumber

string

required

Full card number, digits only.

brand

string

required

Card brand: "Visa", "Mastercard", or "Elo".

expirationMonth

string

required

Two-digit expiration month. Example: "12".

expirationYear

string

required

Two-digit expiration year. Example: "28".

securityCode

string

required

Card CVV — 3 digits. Used only during tokenization; never stored by CertoPay.

birthdate

string

required

Customer’s date of birth in YYYY-MM-DD format.

cellNumber

string

required

Customer’s mobile phone number with area code.

address

object

required

Customer’s billing address (same sub-fields as buyerAddress: postal_code, street, number, neighborhood, city, state).

Step 2 — Charge Using the Token

On every subsequent order, send cardToken instead of raw card fields. No CVV or card number needed:

POST /api/payment-gateway/process
X-Api-Key: sk_live_sua_chave_aqui
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440004
Content-Type: application/json

{
  "orderId": "uuid-do-pedido",
  "method": "CARD",
  "amount": 29700,
  "installments": 1,
  "cardToken": "tok_abc123..."
}

Token Charge Fields

orderId

string

required

The unique identifier for the new order.

method

string

required

Must be "CARD".

amount

integer

required

Charge amount in centavos.

installments

integer

required

Number of installments (1–12). Use 1 for full-amount subscription charges.

cardToken

string

required

The token returned by POST /api/payment-gateway/tokenize-card. Replaces all raw card fields.

Response

Both Option A and Option B return the same response shape:

{
  "transactionId": "uuid-da-transacao",
  "status": "CAPTURED",
  "method": "CARD",
  "amount": 29700,
  "installments": 3
}

Response Fields

transactionId

string

CertoPay’s unique identifier for this transaction. Store this for refund requests and dispute resolution.

status

string

The outcome of the charge attempt:

CAPTURED — The card was approved and funds have been reserved. Fulfill the order.
REFUSED — The card issuer declined the charge. Prompt the buyer to try a different card.

method

string

Echoes back "CARD".

amount

integer

Total charge amount in centavos, as submitted.

installments

integer

Number of installments the charge was split into.

Handling Declined Cards

When a card is declined, the response returns status: REFUSED:

{
  "transactionId": "uuid-da-transacao",
  "status": "REFUSED",
  "method": "CARD",
  "amount": 29700,
  "installments": 3
}

A REFUSED status means the issuing bank rejected the charge. Do not retry the same card automatically — show the buyer a message and invite them to use a different card or payment method. Repeated automatic retries on a declined card may result in the card being permanently blocked by the issuer.

Common reasons for refusal include insufficient credit limit, security blocks from the issuing bank, or incorrect card details. You should not expose the raw decline reason to the buyer — a generic “cartão recusado” message is sufficient.

​Supported Brands

​Two Ways to Charge a Card

​Request

​Request Fields

​Step 1 — Tokenize the Card

​Tokenize Request Fields

​Step 2 — Charge Using the Token

​Token Charge Fields

​Response

​Response Fields

​Handling Declined Cards

Supported Brands

Two Ways to Charge a Card

Request

Request Fields

Step 1 — Tokenize the Card

Tokenize Request Fields

Step 2 — Charge Using the Token

Token Charge Fields

Response

Response Fields

Handling Declined Cards