Checkout

Semi-transparent PIX, boleto, BolePix, credit card and Open Banking checkout

Creates a semi-transparent checkout. BOLETO and BOLETO_PIX require merchant enablement, a configured boleto fee, a complete merchant address, and the shopper document and address. Shopper address is required only for these two methods. Split payments and recurrence are not supported for boleto. PIX charges can be split between your account and linked recipients with the optional split array; see Split payments. Bank transfers and cash deposits are unavailable. Requests using these methods return HTTP 400 with code bank_transfer.discontinued.

POST

v1.1

checkout

transparent

curl --request POST \
  --url https://api.paymee.com.br/v1.1/checkout/transparent \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-api-token: <x-api-token>' \
  --data '
{
  "currency": "BRL",
  "amount": 11,
  "referenceCode": "refcode12345",
  "maxAge": 120,
  "paymentMethod": "PIX",
  "callbackURL": "https://foo.bar/paymeeListener",
  "shopper": {
    "id": "24391203",
    "email": "foo@bar.com",
    "name": "JOHN DOE",
    "document": {
      "type": "CPF",
      "number": "00000000000"
    },
    "phone": {
      "type": "MOBILE",
      "number": "11999990000"
    },
    "bankDetails": {
      "branch": "0001",
      "account": "00011-0"
    }
  }
}
'

{
  "status": 0,
  "message": "success",
  "response": {
    "amount": 11,
    "id": 33200,
    "uuid": "14fe1d3d-26f9-3790-8161-df091e8585da",
    "referenceCode": "0199221121276150",
    "saleCode": "00033200",
    "shopper": {
      "document": {
        "number": "00000000000",
        "type": "CPF"
      },
      "email": "foo@bar.com",
      "id": "24391203",
      "name": "JOHN DOE",
      "phone": {
        "number": "11999990000",
        "type": "MOBILE"
      }
    },
    "instructions": {
      "chosen": "PIX",
      "label": "Transferência via PIX",
      "name": "PIX",
      "qrCode": {
        "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6CAIAAAAHjs1qAAAEvklEQVR42u3ayXXDMBBEQeWftJ2ATzIw3QDqn7VwqeFhHj8/0jN9XALhLuEu4S7hLuEu4S7hLuEu4S7hLuEu3CXcJdwl3CXcJdwl3CXcJdwl3CXchbuEu4T7Xz8X7bsj3Hhxo+ee/Z3Je4o77rjjjjvuuOOOO+6444477rg3YPruVq361uQVmxz+tnuKO+6444477rjjjjvuuOOOO+647ya47zZkV5zZ85o85sl7ijvuuOOOO+6444477rjjjjvuuHdemraL3ong9EcY7rjjjjvuuOOOO+6444477rjjfu6l2XfMk6vSfUeIO+6444477rjjjjvuuOOOO+6438Q9O1qrjnlyAFYtNCevT6cf3HHHHXfccccdd9xxxx133HF/jfuJSzSfab6nuCOIO+6Y4o67z+COu8/gjrvP4P5aky88TS5Gn7uPKOOOu3DHHXfccccdd9xxx/1q7tklY9tCM/sCVvaY214+wx133HHHHXfccccdd9xxxx33F7hPDsm+BWLb+rJtaM9dleKOO+6444477rjjjjvuuOOO+2vcJy9fdj3XtkCcPNMGyrjjjjvuuOOOO+6444477rjjjnv2lCZfGlvF9MTVbXahiTvuuOOOO+6444477rjjjjvuuO9eDu5bok2i7F/h7Ru/zocj7rjjjjvuuOOOO+6444477rjfzX1yXZgdgP6FXfZ49t0L3HHHHXfccccdd9xxxx133HHH/W7K/QvESSiTr7Udv3fHHXfccccdd9xxxx133HHHHfcy7pO/0zZsd6Bc9a0nFpG444477rjjjjvuuOOOO+644x7l3r8K7F9oTg5bdgl7/CISd9xxxx133HHHHXfccccdd9zrua8aklNWXTvOtL/sgw933HHHHXfccccdd9xxxx133HFfu6Lat0TLLuyyS9jsGF+4iMQdd9xxxx133HHHHXfccccd9/pF5InLryzuycdB9uW8wNoXd9xxxx133HHHHXfccccdd9wf455F2X9jToHy/zv4xCISd9xxxx133HHHHXfccccdd9yj3PcRzNJp++XJ63zTgwZ33HHHHXfccccdd9xxxx133HFvI9g2ANlV4OT4BRamuOOOO+6444477rjjjjvuuOP+PPd9A7Dvv/aNaPZBkz3C+QHAHXfccccdd9xxxx133HHHHXfc2+hkobSde+erXbjjjjvuuOOOO+6444477rjjjvuJnfLqUgrl5Ng0rCZxxx133HHHHXfccccdd9xxx/1u7p9obbche177/mvV8Vy4d8cdd9xxxx133HHHHXfccccd9zLu2SXj5I2ZfPVtkvJNC1/ccccdd9xxxx133HHHHXfccce9bUHWj6BtbCYfGbjjjjvuuOOOO+6444477rjjjvvd3Pt/Jzv8+x4i86+R4Y477rjjjjvuuOOOO+6444477idyz55F/xifEu6444477rjjjjvuuOOOO+64454drVX/Nbn4y16N7GDjjjvuuOOOO+6444477rjjjjvua1nsq23pmX1AZAl2DgDuuOOOO+6444477rjjjjvuuN/NXWoOd+Eu4S7hLuEu4S7hLuEu4S7hLuEu4S7cJdwl3CXcJdwl3CXcJdwl3CXcJdyFu4S7dEm/llibksuxCZcAAAAASUVORK5CYII=",
        "plain": "00020101021226720014br.gov.bcb.pix2550bx.com.br/pix/0fa55bba-cb0d-3e5a-8dd3-88af60f2a324520400005303986540647.925802BR5913PayMee Brasil\n6008BRASILIA62190515RP12345678-2019630445C8",
        "url": "https://api.paymee.com.br/payments/pix/qrcode/14fe1d3d-26f9-3790-8161-df091e8585da"
      },
      "steps": {
        "key": [
          "Acesse o APP ou o Internet Banking do seu Banco",
          "Acesse o menu PIX",
          "Informe a chave pix-sandbox@paymee.com.br ou se preferir o nosso CNPJ 00000000000000",
          "Siga os passos no seu APP e finalize a transação"
        ],
        "qrCode": [
          "Acesse o APP ou o Internet Banking do seu Banco",
          "Acesse o menu PIX",
          "Abra o leitor de QRCode no APP e escaneie o código informado",
          "Siga os passos no APP e finalize a transação"
        ]
      }
    }
  }
}

Split payments

PIX charges can be split between your account and linked recipients with the optional split array. Each leg sets a recipientId and either an amount or a percentage. PayMee fees and refunds stay with your account. The response adds a root split block. See Split payments for rules, settlement and error codes.

Boleto and BolePix

Use BOLETO for a bank boleto or BOLETO_PIX for a boleto with a Pix QR code. BolePix offers two ways to pay the same sale; the customer must pay only once. These methods require merchant enablement, a configured boleto fee, and a complete merchant address. Check available payment methods before offering them. Split payments and recurrence are not supported for either method.

Shopper address

shopper.address is required only for BOLETO and BOLETO_PIX. PIX, credit card and Open Banking (INITIATOR) do not require it.

Field	Requirement for boleto and BolePix
`street`	Required, nonblank
`number`	Required, nonblank
`neighborhood`	Required, nonblank
`city`	Required, nonblank
`state`	Required, two-letter Brazilian state code
`zipCode`	Required, eight digits; formatting is accepted
`complement`	Optional

Provide a valid shopper CPF or CNPJ. Shopper bank details are not required for boleto or BolePix. Request examples use illustrative data: replace the document and due date before submitting.

Due date and expiration

dueDate uses yyyy-MM-dd, interpreted in America/Sao_Paulo. The default configuration uses today plus 3 days when omitted and accepts dates from today through today plus 20 days. PayMee can configure these limits. For these two methods, sale expiration is calculated from dueDate plus the configured grace period (default: 2 days), instead of the request’s maxAge. The BolePix QR code expires at the end of dueDate. Use the bank’s returned paymentLimitDate, when present, for the boleto payment limit.

Payment instructions and confirmation

Creation returns boleto fields directly in response.instructions: documentNumber, typeableLine, barcode, dueDate, paymentLimitDate, amountDue, status and pdfUrl. BolePix also returns response.instructions.pix.qrCode with the Pix payload and QR code. Use the returned PDF URL as provided. Successful registration is not payment confirmation. Use the existing payment webhook or transaction query to confirm payment. Transaction queries expose boleto details in the root boleto field; its lifecycle status is separate from the sale’s situation.

Boleto errors

Errors use the existing validation envelope: status: -1, message: "validation failure", errorCount and errors containing field, code and message.

HTTP	Code	Meaning
400	`boleto.disabled`	Boleto is not enabled for this merchant/configuration
400	`merchant.address.incomplete`	Merchant address must be completed
400	`shopper.address.isNull`	Shopper address is missing
400	`shopper.address.<field>.isNull`	Required address field is missing or blank
400	`shopper.address.state.invalid`	State must have two characters
400	`shopper.address.zipCode.invalid`	Postal code must contain eight digits
400	`boleto.register_failed`	The bank could not register the boleto
409	`boleto.duplicate_in_flight`	Issuance is already in progress for this reference code
503	`boleto.unavailable`	Boleto issuance is temporarily unavailable
503	`boleto_pix.pix_unavailable`	The BolePix QR code could not be generated

Headers

x-api-key

string

required

Example:

"your-x-api-key"

x-api-token

string

required

Example:

"your-x-api-token"

Body

application/json

Boleto or BolePix
Other payment methods

paymentMethod

enum<string>

required

Chosen payment method

Available options:

BOLETO,

BOLETO_PIX

Example:

"PIX"

shopper

object

required

Show child attributes

currency

string

required

ISO-4217 currency code

Maximum string length: 3

Example:

"BRL"

amount

number<float>

required

Order Amount

Example:

11

referenceCode

string

required

Unique order identifier

Maximum string length: 50

Example:

"019922112127617"

maxAge

number

Sale max age in minutes. For BOLETO and BOLETO_PIX, sale expiration is calculated from dueDate plus the configured grace period (default 2 days), instead of this value. The Pix QR code expires at the end of dueDate.

Required range: x <= 43200

Example:

120

callbackURL

string<uri>

Callback URL for transaction updates

Maximum string length: 255

Example:

"https://foo.bar/paymeeListener"

redirectURL

string<uri>

Confirmation redirect URL

Maximum string length: 255

Example:

"https://foo.bar/paymeeRedirect"

observation

string

Any internal reference

Maximum string length: 255

Example:

"Internal Transaction ID 999"

recurrence

number

Recurrence in months (required when paymentMethod is INITIATOR) Not supported for BOLETO or BOLETO_PIX.

Required range: x <= 999

Example:

12

brand_id

string<uuid>

Brand ID of the bank (required when paymentMethod is INITIATOR)

dueDate

string<date>

Boleto/BolePix only. Due date in yyyy-MM-dd, evaluated in America/Sao_Paulo. Default configuration: today + 3 days; allowed range: today through today + 20 days. These limits are configurable by PayMee. Omit to use the default.

Example:

"2026-09-22"

split

object[]

PIX only. Splits the charge between your account (parent) and linked recipients. Requires split to be enabled for your account. Up to 20 recipients per charge by default (limit configurable by PayMee). Each recipient may appear once and cannot be your own account. Percentages are applied to amount and rounded down to cents; the rounding remainder stays with the parent. The sum of all legs must not exceed amount, and the parent remainder must cover the PayMee fees, which are calculated on the full amount and charged to the parent only. Not supported with BOLETO, BOLETO_PIX, CREDIT_CARD, INITIATOR, recurrence, scheduled payments, taxData or sellersTransactions. See Split payments.

Minimum array length: 1

Show child attributes

Response

Checkout created. For boleto, successful registration returns payment instructions; it does not confirm payment.

message

string

Example:

"success"

response

object

Show child attributes

status

number

Example:

0

split

Parent sale · object

Present only when the request included split. Returned at the root of the body, next to response.

Show child attributes

curl --request POST \
  --url https://api.paymee.com.br/v1.1/checkout/transparent \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-api-token: <x-api-token>' \
  --data '
{
  "currency": "BRL",
  "amount": 11,
  "referenceCode": "refcode12345",
  "maxAge": 120,
  "paymentMethod": "PIX",
  "callbackURL": "https://foo.bar/paymeeListener",
  "shopper": {
    "id": "24391203",
    "email": "foo@bar.com",
    "name": "JOHN DOE",
    "document": {
      "type": "CPF",
      "number": "00000000000"
    },
    "phone": {
      "type": "MOBILE",
      "number": "11999990000"
    },
    "bankDetails": {
      "branch": "0001",
      "account": "00011-0"
    }
  }
}
'

{
  "status": 0,
  "message": "success",
  "response": {
    "amount": 11,
    "id": 33200,
    "uuid": "14fe1d3d-26f9-3790-8161-df091e8585da",
    "referenceCode": "0199221121276150",
    "saleCode": "00033200",
    "shopper": {
      "document": {
        "number": "00000000000",
        "type": "CPF"
      },
      "email": "foo@bar.com",
      "id": "24391203",
      "name": "JOHN DOE",
      "phone": {
        "number": "11999990000",
        "type": "MOBILE"
      }
    },
    "instructions": {
      "chosen": "PIX",
      "label": "Transferência via PIX",
      "name": "PIX",
      "qrCode": {
        "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6CAIAAAAHjs1qAAAEvklEQVR42u3ayXXDMBBEQeWftJ2ATzIw3QDqn7VwqeFhHj8/0jN9XALhLuEu4S7hLuEu4S7hLuEu4S7hLuEu3CXcJdwl3CXcJdwl3CXcJdwl3CXchbuEu4T7Xz8X7bsj3Hhxo+ee/Z3Je4o77rjjjjvuuOOOO+6444477rg3YPruVq361uQVmxz+tnuKO+6444477rjjjjvuuOOOO+647ya47zZkV5zZ85o85sl7ijvuuOOOO+6444477rjjjjvuuHdemraL3ong9EcY7rjjjjvuuOOOO+6444477rjjfu6l2XfMk6vSfUeIO+6444477rjjjjvuuOOOO+6438Q9O1qrjnlyAFYtNCevT6cf3HHHHXfccccdd9xxxx133HF/jfuJSzSfab6nuCOIO+6Y4o67z+COu8/gjrvP4P5aky88TS5Gn7uPKOOOu3DHHXfccccdd9xxx/1q7tklY9tCM/sCVvaY214+wx133HHHHXfccccdd9xxxx33F7hPDsm+BWLb+rJtaM9dleKOO+6444477rjjjjvuuOOO+2vcJy9fdj3XtkCcPNMGyrjjjjvuuOOOO+6444477rjjjnv2lCZfGlvF9MTVbXahiTvuuOOOO+6444477rjjjjvuuO9eDu5bok2i7F/h7Ru/zocj7rjjjjvuuOOOO+6444477rjfzX1yXZgdgP6FXfZ49t0L3HHHHXfccccdd9xxxx133HHH/W7K/QvESSiTr7Udv3fHHXfccccdd9xxxx133HHHHfcy7pO/0zZsd6Bc9a0nFpG444477rjjjjvuuOOOO+644x7l3r8K7F9oTg5bdgl7/CISd9xxxx133HHHHXfccccdd9zrua8aklNWXTvOtL/sgw933HHHHXfccccdd9xxxx133HFfu6Lat0TLLuyyS9jsGF+4iMQdd9xxxx133HHHHXfccccd9/pF5InLryzuycdB9uW8wNoXd9xxxx133HHHHXfccccdd9wf455F2X9jToHy/zv4xCISd9xxxx133HHHHXfccccdd9yj3PcRzNJp++XJ63zTgwZ33HHHHXfccccdd9xxxx133HFvI9g2ANlV4OT4BRamuOOOO+6444477rjjjjvuuOP+PPd9A7Dvv/aNaPZBkz3C+QHAHXfccccdd9xxxx133HHHHXfc2+hkobSde+erXbjjjjvuuOOOO+6444477rjjjvuJnfLqUgrl5Ng0rCZxxx133HHHHXfccccdd9xxx/1u7p9obbche177/mvV8Vy4d8cdd9xxxx133HHHHXfccccd9zLu2SXj5I2ZfPVtkvJNC1/ccccdd9xxxx133HHHHXfccce9bUHWj6BtbCYfGbjjjjvuuOOOO+6444477rjjjvvd3Pt/Jzv8+x4i86+R4Y477rjjjjvuuOOOO+6444477idyz55F/xifEu6444477rjjjjvuuOOOO+64454drVX/Nbn4y16N7GDjjjvuuOOOO+6444477rjjjjvua1nsq23pmX1AZAl2DgDuuOOOO+6444477rjjjjvuuN/NXWoOd+Eu4S7hLuEu4S7hLuEu4S7hLuEu4S7cJdwl3CXcJdwl3CXcJdwl3CXcJdyFu4S7dEm/llibksuxCZcAAAAASUVORK5CYII=",
        "plain": "00020101021226720014br.gov.bcb.pix2550bx.com.br/pix/0fa55bba-cb0d-3e5a-8dd3-88af60f2a324520400005303986540647.925802BR5913PayMee Brasil\n6008BRASILIA62190515RP12345678-2019630445C8",
        "url": "https://api.paymee.com.br/payments/pix/qrcode/14fe1d3d-26f9-3790-8161-df091e8585da"
      },
      "steps": {
        "key": [
          "Acesse o APP ou o Internet Banking do seu Banco",
          "Acesse o menu PIX",
          "Informe a chave pix-sandbox@paymee.com.br ou se preferir o nosso CNPJ 00000000000000",
          "Siga os passos no seu APP e finalize a transação"
        ],
        "qrCode": [
          "Acesse o APP ou o Internet Banking do seu Banco",
          "Acesse o menu PIX",
          "Abra o leitor de QRCode no APP e escaneie o código informado",
          "Siga os passos no APP e finalize a transação"
        ]
      }
    }
  }
}

API Documentation

Checkout

Split

Payouts

Loan

Transactions

Payment Methods

Financial

Webhooks and Callbacks

Payer Information

Pix Automatic (Recurrence)

Semi-transparent PIX, boleto, BolePix, credit card and Open Banking checkout

Split payments

Boleto and BolePix

Shopper address

Due date and expiration

Payment instructions and confirmation

Boleto errors

Headers

Body

Response

​Split payments

​Boleto and BolePix

​Shopper address

​Due date and expiration

​Payment instructions and confirmation

​Boleto errors

Headers

Body

Response

Split payments

Boleto and BolePix

Shopper address

Due date and expiration

Payment instructions and confirmation

Boleto errors