Create Charge

Create a new PIX charge for your customer.

Base URLs

Environment	URL
Production	https://api-pix.crypto2pay.app/v2/pix
Sandbox	https://sandbox-pix.crypto2pay.app/v2/pix

Request

POST /v2/pix

Headers

Header	Value
Authorization	YOUR_API_KEY
Content-Type	application/json
x-sandbox-behaviour	(sandbox only) paid · expired · refunded · paid_then_refunded

Body Parameters

Parameter	Type	Required	Description
transaction_id	string	required	Unique transaction identifier on your platform (UUID v4 recommended)
currency	string	required	Transaction currency (only BRL is supported)
amount	number	required	Charge amount in Brazilian reais (e.g., 150.75)
due	string	required	Charge expiration date and time in ISO 8601 format. Always send in UTC-0 timezone
name	string	required	Payer's full name
document_type	string	required	CPF or CNPJ
document_number	string	required	Document number (digits only)
webhook	string	required	URL for receiving status notifications
phone_number	string	optional	International format (e.g., 5547999999999)
email	string	optional	Payer email address
external_id	string	optional	External identifier for grouping
base64image	boolean	optional	Include QR code as base64 image in response

Example Request

curl -X POST https://api-pix.crypto2pay.app/v2/pix \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "12345678942",
    "currency": "BRL",
    "amount": 145,
    "due": "2026-11-30T19:00:00.000Z",
    "name": "John Doe",
    "document_type": "CPF",
    "document_number": "12345678901",
    "webhook": "https://yoursite.com/webhook"
  }'

Success Response (200)

{
  "id": 59366,
  "transaction_id": "12345678942",
  "status": 0,
  "currency": "BRL",
  "amount": 145,
  "due": "2026-11-30T19:00:00.000Z",
  "qrcode": "00020101021226890014br.gov.bcb.pix..."
}

note

When base64image: true is sent in the request body, the response will include an additional qrcode_image field containing the QR code as a base64-encoded PNG image.

caution

Sandbox QR codes are not valid PIX QR codes. They cannot be paid or scanned by any real banking app — attempting to read one will result in an error. To simulate a payment in the sandbox, use the x-sandbox-behaviour header instead.

Error Responses

Status	Description
400	Duplicate transaction_id — a charge with this transaction ID already exists
400	Invalid expiration — the due date is in the past or has an invalid format
500	Server error — an unexpected error occurred

Charge Status Codes

Code	Description
0	Created — awaiting payment
1	Paid
2	Cancelled
3	Expired
4	Refunded