Headers

Body Details

{
  "source_account_branch_identifier": "0001",
  "source_account_number": "123456",
  "pix_copy_and_paste": "00020126360014br.gov.bcb.pix0114+55119999999995204000053039865406100.505802BR5925FULANO DE TAL6014BELO HORIZONTE62070503***63041D3D",
  "amount": 100.50,
  "tag": "payment-reference-123"
}

Request Examples

Transfer using PIX copy-and-paste:

POST /create-copy-and-paste-transfer
Authorization: Bearer <access_token>
hmac: <computed_hmac>
Content-Type: application/json

{
  "source_account_branch_identifier": "0001",
  "source_account_number": "123456",
  "pix_copy_and_paste": "00020126360014br.gov.bcb.pix0114+55119999999995204000053039865406100.505802BR5925FULANO DE TAL6014BELO HORIZONTE62070503***63041D3D",
  "amount": 100.50
}

Transfer with idempotency key:

POST /create-copy-and-paste-transfer
Authorization: Bearer <access_token>
hmac: <computed_hmac>
idempotency-key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "source_account_branch_identifier": "0001",
  "source_account_number": "123456",
  "pix_copy_and_paste": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-4266141740005204000053039865406250.005802BR5913Maria Santos6009SAO PAULO62070503***6304A1B2",
  "amount": 250.00,
  "tag": "invoice-2024-001"
}

Transfer using static QR code:

POST /create-copy-and-paste-transfer
Authorization: Bearer <access_token>
hmac: <computed_hmac>
Content-Type: application/json

{
  "source_account_branch_identifier": "0001",
  "source_account_number": "123456",
  "pix_copy_and_paste": "00020126330014br.gov.bcb.pix0111123456789015204000053039865802BR5913Store Name6009SAO PAULO62070503***63044D5E",
  "amount": 50.00,
  "tag": "store-payment"
}

Response Details

{
  "worked": true,
  "id": 789460,
  "transaction_id": 789460,
  "code_transaction": "E789460",
  "status": "PROCESSING",
  "amount": 100.5,
  "fee": 0.0,
  "key": "+5511999999999",
  "tag": "payment-reference-123",
  "from_accout": "123456",
  "recipient_instution": "12345678",
  "recipient_instution_name": "Example Bank",
  "recipient_account_id": "654321",
  "recipient_branch_id": "0001",
  "recipient_legal_id": "12345678901",
  "recipient_name": "FULANO DE TAL",
  "recipient_account_type": "CONTA_CORRENTE",
  "operationUuid": null,
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  "erro_descriptor": null,
  "new_erro_descriptor": null
}

Error Responses

Business Rules

1. Copy-and-Paste Validation: The PIX copy-and-paste code must be valid and contain all necessary recipient information.
2. Amount Validation: The amount must be greater than zero and have at most 2 decimal places.
3. Transaction Status: The transaction is created with NEW status, then immediately transitioned to PROCESSING status.
4. Background Processing: After the response is returned, a background task processes the cashout approval.
5. HMAC Validation: The request body must be validated using the provided HMAC signature.
6. Automatic Approval: This endpoint always auto-approves the transaction for immediate processing.

Idempotency

This endpoint supports the optional idempotency-key header to prevent duplicate transactions. Since this endpoint automatically approves transactions, using idempotency keys is critically important to avoid duplicate money transfers, especially when scanning QR codes or pasting BR Codes multiple times.

For complete details on how idempotency works, including key format, response codes, and best practices, see the Idempotency section in the main documentation.

PIX Copy-and-Paste (BR Code) Format

The PIX copy-and-paste code, also known as BR Code, is a string that encodes all the information needed for a PIX transfer. It typically contains:

• Recipient's PIX key or account information
• Recipient's name
• Transaction amount (for static QR codes with fixed amounts)
• Additional transaction information

Example BR Code Structure

00020126360014br.gov.bcb.pix0114+55119999999995204000053039865406100.505802BR5925FULANO DE TAL6014BELO HORIZONTE62070503***63041D3D

This code includes:

• PIX key: +5511999999999
• Suggested amount: 100.50
• Recipient name: FULANO DE TAL
• City: BELO HORIZONTE

The system automatically extracts all necessary information from this code.

Use Cases

1. QR Code Payments: Users scan a QR code displayed by the merchant, and your app extracts the BR Code to make the payment.
2. Copy-Paste Payments: Users receive a PIX code via message, email, or website, copy it, and paste it into your app.
3. Dynamic QR Codes: Each payment has a unique QR code with specific amount and identifier.
4. Static QR Codes: Merchants display a static QR code where users enter the amount.

For more detailed examples and implementation guidance, see the Create Cashout documentation.