Create Payment

Create a PIX payment (payout) to a beneficiary. Two methods are available: via PIX key (recommended) or via bank details.

---

Method 1: PIX Key (Recommended)

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

POST /v2/payout/pix

Headers

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

Request Body

Parameter	Type		Description
transaction_id	string	required	Unique identifier for the transaction. UUID v4 recommended.
currency	string	required	Currency code. Only BRL is accepted.
amount	number	required	Payment amount in reais (BRL).
name	string	required	Beneficiary full name.
document_type	string	required	CPF or CNPJ.
document_number	string	required	Document number — digits only, no punctuation.
pix_key	string	required	PIX key of the beneficiary.
phone_number	string	optional	Beneficiary phone number.
email	string	optional	Beneficiary e-mail address.
webhook	string	optional	URL to receive payment status notifications.

Accepted PIX Key Formats

• CPF — e.g. 12345678900
• CNPJ — e.g. 12345678000195
• E-mail — e.g. user@example.com
• Phone number — e.g. +5511999999999
• Random key (chave aleatória) — e.g. 123e4567-e89b-12d3-a456-426614174000

Example Request

curl -X POST https://api-pix.crypto2pay.app/v2/payout/pix \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "9233a90c-1b2a-4c3d-8e5f-6a7b8c9d0e1f",
    "currency": "BRL",
    "amount": 1500,
    "name": "Maria Silva",
    "document_type": "CPF",
    "document_number": "12345678900",
    "pix_key": "maria@example.com",
    "webhook": "https://yourapp.com/webhooks/payout"
  }'

Response 200

{
  "id": 796,
  "transaction_id": "9233a90c-1b2a-4c3d-8e5f-6a7b8c9d0e1f",
  "status": 0,
  "currency": "BRL",
  "amount": 1500,
  "bank": {
    "type": "email",
    "bank_name": "COOPERATIVA DE CRÉDITO",
    "ispb": "82527557",
    "account_agency": "3879",
    "account_number": "7716539016157248"
  }
}

Response Fields

Field	Type	Description
id	number	Internal payment ID.
transaction_id	string	The transaction ID you provided.
status	number	Current payment status (see Status Codes).
currency	string	Currency code.
amount	number	Payment amount in reais.
bank.type	string	PIX key type resolved for the beneficiary.
bank.bank_name	string	Name of the beneficiary's bank or financial institution.
bank.ispb	string	ISPB code of the beneficiary's institution.
bank.account_agency	string	Beneficiary's bank branch.
bank.account_number	string	Beneficiary's account number.

Errors

HTTP Status	Description
400	pix_key is missing or in an unsupported format.
409	transaction_id already exists — duplicate request.

---

Method 2: Bank Details

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

POST /v2/payout

Headers

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

Request Body

Parameter	Type		Description
transaction_id	string	required	Unique identifier for the transaction. UUID v4 recommended.
currency	string	required	Currency code. Only BRL is accepted.
amount	number	required	Payment amount in reais (BRL).
name	string	required	Beneficiary full name.
document_type	string	required	CPF or CNPJ.
document_number	string	required	Document number — digits only, no punctuation.
bank.type	string	required	Must be "PIX".
bank.ispb	string	required	ISPB code of the beneficiary's financial institution.
bank.account_agency	string	required	Beneficiary's bank branch (up to 4 digits).
bank.account_number	string	required	Beneficiary's account number.
bank.bank_name	string	optional	Name of the beneficiary's bank.
phone_number	string	optional	Beneficiary phone number.
email	string	optional	Beneficiary e-mail address.
webhook	string	optional	URL to receive payment status notifications.

Example Request

curl -X POST https://api-pix.crypto2pay.app/v2/payout \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "currency": "BRL",
    "amount": 300,
    "name": "João Souza",
    "document_type": "CPF",
    "document_number": "98765432100",
    "bank": {
      "type": "PIX",
      "ispb": "00000000",
      "account_agency": "0001",
      "account_number": "123456789",
      "bank_name": "BANCO DO BRASIL"
    },
    "webhook": "https://yourapp.com/webhooks/payout"
  }'

Response 200

{
  "id": 797,
  "transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": 0,
  "currency": "BRL",
  "amount": 300,
  "bank": {
    "type": "PIX",
    "bank_name": "BANCO DO BRASIL",
    "ispb": "00000000",
    "account_agency": "0001",
    "account_number": "123456789"
  }
}

Errors

HTTP Status	Description
400	bank.ispb is missing or invalid.
400	bank.account_agency exceeds the maximum allowed length.
409	transaction_id already exists — duplicate request.

---

Payment Status Codes

Code	Status	Description
0	Created	Payment has been created and is pending processing.
1	Paid / Completed	Payment was successfully processed and delivered.
2	Rejected	Payment was rejected by the receiving institution.
3	Reversed	Payment was completed but subsequently reversed by the customer or bank.

Status flow:

0 → 1 (success) · 0 → 2 (rejection) · 0 → 1 → 3 (reversal)