POST /api/payment-gateway/process — Process a Payment

The /api/payment-gateway/process endpoint is CertoPay’s unified payment entry point. A single request shape handles all three supported payment methods — PIX, Boleto, and Credit Card — differing only in the method field and method-specific parameters. Because payment charges are non-idempotent by nature, always supply an Idempotency-Key header with a unique UUID v4 per charge attempt to prevent duplicate transactions in the event of a network retry.

Base URL

https://v2.certopaybrasil.com/api

Endpoint

POST /payment-gateway/process

Request Headers

X-Api-Key

string

required

Your secret API key. Keep this value server-side and never expose it in client-facing code.

Content-Type

string

required

Must be application/json.

Idempotency-Key

string

A unique UUID v4 generated per charge attempt. CertoPay uses this key to deduplicate requests — submitting the same key twice returns the original response without creating a second charge.Strongly recommended for all production requests.

Request Body — Common Fields

The following fields are required for all payment methods.

orderId

string

required

Your internal order identifier (UUID recommended). Used to correlate the transaction with your own records.

method

string

required

The payment method to use. Accepted values: "PIX", "BOLETO", "CARD".

amount

integer

required

Charge amount in centavos (Brazilian cents). For example, R$297,00 is represented as 29700.

buyerDoc

string

required

The buyer’s CPF (Cadastro de Pessoas Físicas), digits only. Example: "12345678900".

buyerCellNumber

string

required

The buyer’s mobile phone number in Brazilian format. Example: "(11) 99999-9999".

buyerAddress

object

required

The buyer’s billing address.

Show buyerAddress fields

postal_code

string

required

Brazilian CEP (postal code), digits only. 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 code (UF). Example: "SP".

Method-Specific Request Body & Examples

PIX
Boleto
Credit Card

PIX is Brazil’s instant payment rail. A successful request returns a QR code payload (emv) and a hosted QR code image URL that your customer scans to complete payment. PIX transactions have a configurable expiry window.

Additional Fields

No additional fields are required beyond the common fields above. Set method to "PIX".

Example Request

curl -X POST https://v2.certopaybrasil.com/api/payment-gateway/process \
  -H "X-Api-Key: sk_live_sua_chave_aqui" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "uuid-do-pedido",
    "method": "PIX",
    "amount": 29700,
    "buyerDoc": "12345678900",
    "buyerCellNumber": "(11) 99999-9999",
    "buyerAddress": {
      "postal_code": "01310930",
      "street": "Avenida Paulista",
      "number": "100",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP"
    }
  }'

Response Fields

transactionId

string

Unique identifier for this transaction. Store this value to query status or issue refunds.

status

string

Initial transaction status. Will be "PENDING" until the PIX payment is confirmed by the buyer.

method

string

Echo of the payment method: "PIX".

amount

integer

Charged amount in centavos.

pix

object

PIX-specific payment details.

Show pix fields

pix.emv

string

The EMV payload (Pix Copia e Cola string) that your app or checkout page can render as a QR code.

pix.qrCodeUrl

string

Hosted URL to a pre-rendered QR code PNG image. Embed this in your payment confirmation screen.

pix.expiresAt

string

ISO 8601 timestamp indicating when the PIX charge expires. After this time, the emv and QR code are no longer valid.

Example Response

{
  "transactionId": "uuid-da-transacao",
  "status": "PENDING",
  "method": "PIX",
  "amount": 29700,
  "pix": {
    "emv": "00020126580014br.gov.bcb.pix...",
    "qrCodeUrl": "https://...",
    "expiresAt": "2026-06-26T11:00:00Z"
  }
}

Poll GET /api/payment-gateway/transaction/{transactionId} or listen for the payment.confirmed webhook event to detect when the PIX payment status transitions from PENDING to PAID.

Boleto Bancário is a widely used Brazilian payment slip that customers can pay at banks, ATMs, lottery kiosks, or via internet banking. A successful request returns a scannable barcode and a PDF download link. Boleto payments have a due date after which the slip expires.

Additional Fields

No additional fields are required beyond the common fields above. Set method to "BOLETO".

Example Request

curl -X POST https://v2.certopaybrasil.com/api/payment-gateway/process \
  -H "X-Api-Key: sk_live_sua_chave_aqui" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440002" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "uuid-do-pedido",
    "method": "BOLETO",
    "amount": 29700,
    "buyerDoc": "12345678900",
    "buyerCellNumber": "(11) 99999-9999",
    "buyerAddress": {
      "postal_code": "01310930",
      "street": "Avenida Paulista",
      "number": "100",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP"
    }
  }'

Response Fields

transactionId

string

Unique identifier for this transaction. Store this value to query status or issue refunds.

status

string

Initial transaction status. Will be "PENDING" until payment is confirmed by the banking network.

method

string

Echo of the payment method: "BOLETO".

amount

integer

Charged amount in centavos.

boleto

object

Boleto-specific payment details.

Show boleto fields

boleto.barcode

string

The formatted barcode string that can be displayed on a payment confirmation page or printed on the boleto slip.

boleto.digitableLine

string

The numeric digitable line (linha digitável) used for manual entry during payment. This is the string customers type in if their scanner cannot read the barcode.

boleto.pdfUrl

string

Hosted URL to a ready-to-print boleto PDF. Redirect your customer here or embed it in a download link.

boleto.dueDate

string

ISO 8601 timestamp for the boleto’s due date. After this date the slip can no longer be paid and a new boleto must be issued.

Example Response

{
  "transactionId": "uuid-da-transacao",
  "status": "PENDING",
  "method": "BOLETO",
  "amount": 29700,
  "boleto": {
    "barcode": "34191.09008 61207.727308 71140.421477 1 10010002970000",
    "digitableLine": "34191090086120772730871140421477101001000297000",
    "pdfUrl": "https://...",
    "dueDate": "2026-07-03T23:59:59Z"
  }
}

Boleto confirmation typically takes 1–3 business days to be reflected in the transaction status. Do not fulfill orders based solely on the PENDING status — wait for the payment.confirmed webhook or poll the transaction endpoint.

Credit card payments are processed synchronously. A successful charge returns status: "CAPTURED" immediately. You may pass raw card data directly in the request or substitute a cardToken obtained from the Tokenize Card endpoint to avoid handling raw PAN data on your server.

Additional Fields

installments

integer

Number of installments (parcelas). Use 1 for a single full charge. Maximum installments vary by card brand and acquirer configuration.

cardHolderName

string

Full name exactly as it appears on the card, in uppercase. Example: "JOAO DA SILVA". Required unless using cardToken.

cardNumber

string

16-digit card number, digits only. Example: "4111111111111111". Required unless using cardToken.

cardExpirationMonth

string

Two-digit expiration month. Example: "12". Required unless using cardToken.

cardExpirationYear

string

Two-digit expiration year. Example: "28" for 2028. Required unless using cardToken.

cardSecurityCode

string

Card CVV/CVC security code. Example: "123". Required unless using cardToken.

cardBrand

string

Card network brand. Accepted values: "Visa", "Mastercard", "Elo". Required unless using cardToken.

cardToken

string

A token returned by POST /api/payment-gateway/tokenize-card. When provided, all raw card* fields above are ignored. Use this to charge returning customers without re-collecting card data.

buyerBirthdate

string

The buyer’s date of birth in YYYY-MM-DD format. Required for anti-fraud checks. Example: "1990-05-20".

Example Request

curl -X POST https://v2.certopaybrasil.com/api/payment-gateway/process \
  -H "X-Api-Key: sk_live_sua_chave_aqui" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440003" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
    }
  }'

Response Fields

transactionId

string

Unique identifier for this transaction. Store this value to issue refunds or query status.

status

string

Transaction outcome. "CAPTURED" means the charge was successful and funds are reserved. Other possible values include "DECLINED" and "ERROR".

method

string

Echo of the payment method: "CARD".

amount

integer

Total charged amount in centavos.

installments

integer

Number of installments the charge was split into.

Example Response

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

To charge a returning customer without asking for card details again, first call POST /api/payment-gateway/tokenize-card to save the card, then pass the returned cardToken in place of all card* fields.

Error Responses

HTTP Status	Meaning
`400 Bad Request`	Missing or invalid field. Check the `errors` array in the response body for field-level details.
`401 Unauthorized`	The `X-Api-Key` header is missing or invalid.
`409 Conflict`	A transaction with the same `Idempotency-Key` was already processed. The original response is returned.
`422 Unprocessable Entity`	The request was well-formed but the charge was declined by the acquirer.
`500 Internal Server Error`	An unexpected error occurred on CertoPay’s side. Retry with exponential back-off.

Never log or store raw card numbers (cardNumber, cardSecurityCode) in your application logs or database. Use the Tokenize Card endpoint to handle repeat customers securely.

​Base URL

​Endpoint

​Request Headers

​Request Body — Common Fields

​Method-Specific Request Body & Examples

​Additional Fields

​Example Request

​Response Fields

​Example Response

​Additional Fields

​Example Request

​Response Fields

​Example Response

​Additional Fields

​Example Request

​Response Fields

​Example Response

​Error Responses

Base URL

Endpoint

Request Headers

Request Body — Common Fields

Method-Specific Request Body & Examples

Additional Fields

Example Request

Response Fields

Example Response

Additional Fields

Example Request

Response Fields

Example Response

Additional Fields

Example Request

Response Fields

Example Response

Error Responses