Time	Status	User Agent
Retrieving recent requests…

Create PIX QR Code Chargeback

POST /v2/finance/chargebacks-pix-copy-and-paste

Request a chargeback (full or partial) for a paid PIX QR Code. The chargeback processing is asynchronous and status can be consulted via the Chargeback Status endpoint.

Authentication

Header	Type	Required	Example
Authorization	String	Yes	`Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`
Content-Type	String	Yes	`application/json`

Request Body

Parameter	Type	Required	Description
qr_code_id	Integer	Yes	ID of the PIX QR Code to be refunded. Unique identifier of the QR Code transaction.
information	String	Yes	Reason/information for the chargeback. Descriptive text documenting why the chargeback is requested.
amount	Decimal	Yes	Chargeback amount (must be > 0, with 2 decimal places). Can be equal to or less than the QR Code value.

Request Examples

Full Chargeback:

POST /v2/finance/chargebacks-pix-copy-and-paste
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "qr_code_id": 12345,
  "information": "Full refund - customer canceled order",
  "amount": 100.00
}

Partial Chargeback:

POST /v2/finance/chargebacks-pix-copy-and-paste
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "qr_code_id": 12345,
  "information": "Partial refund - returned 1 of 2 items",
  "amount": 50.00
}

Response (200 OK)

{
  "worked": true,
  "id": 98765,
  "end_to_end_id": "E6070119020210521123456789012345678",
  "amount": 50.00,
  "status": "PENDING",
  "fee": 0.00
}

Field	Type	Description
worked	Boolean	Always `true` for successful requests.
id	Integer	Unique chargeback identifier. Use to query status later.
end_to_end_id	String	End-to-End ID of the refund transaction. May be empty for pending chargebacks.
amount	Decimal	The chargeback amount requested.
status	String	`PENDING` - Processing. `SUCCESS` - Completed. `REJECTED` - Failed.
fee	Decimal	Transaction fee. Usually `0.00` for chargebacks.

Error Responses

Status Code	Error Message	Cause
400	QR Code not found	Invalid `qr_code_id` or doesn't belong to your account
400	QR Code is not paid	QR Code status is not `PAID` or `CHARGEBACK`
400	There is a refund in processing	A `PENDING` chargeback already exists for this QR Code
400	Amount is greater than the value of the QR Code	Chargeback amount exceeds available balance
400	Cannot process chargeback for closed account	Associated account is closed
401	Unauthorized	Invalid or missing Bearer token
422	Validation error	Invalid request format or missing required fields

Code Examples

cURL

curl --request POST \
  --url https://api.somossimpay.com.br/v2/finance/chargebacks-pix-copy-and-paste \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "qr_code_id": 12345,
    "information": "Full refund - customer canceled order",
    "amount": 100.00
  }'

JavaScript (Node.js)

const axios = require('axios');

async function createChargeback(accessToken, qrCodeId, amount, information) {
  try {
    const response = await axios.post(
      'https://api.somossimpay.com.br/v2/finance/chargebacks-pix-copy-and-paste',
      {
        qr_code_id: qrCodeId,
        information: information,
        amount: amount
      },
      {
        headers: {
          'Authorization': `Bearer ${accessToken}`,
          'Content-Type': 'application/json'
        }
      }
    );

    const { worked, id, status, end_to_end_id } = response.data;
    console.log(`Chargeback created: ID ${id}, Status: ${status}`);
    
    return response.data;
  } catch (error) {
    console.error('Chargeback failed:', error.response?.data || error.message);
    throw error;
  }
}

// Usage
createChargeback(accessToken, 12345, 100.00, 'Customer canceled order');

Python

import requests

def create_chargeback(access_token, qr_code_id, amount, information):
    url = "https://api.somossimpay.com.br/v2/finance/chargebacks-pix-copy-and-paste"
    
    payload = {
        "qr_code_id": qr_code_id,
        "information": information,
        "amount": amount
    }
    
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }
    
    try:
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status()
        
        data = response.json()
        print(f"Chargeback created: ID {data['id']}, Status: {data['status']}")
        
        return data
    
    except requests.exceptions.HTTPError as e:
        print(f"Chargeback failed: {e.response.text}")
        raise

# Usage
create_chargeback(access_token, 12345, 100.00, "Customer canceled order")

Business Rules

Authentication

Requires valid Bearer token
User must be authenticated

Validations

QR Code must exist and belong to your account
QR Code status must be PAID or CHARGEBACK (partially refunded)
Cannot create chargeback if there's already a PENDING chargeback
Amount must be > 0 with exactly 2 decimal places
Amount cannot exceed remaining refundable balance
Associated account cannot be closed
All required fields must be provided

Processing

Internal Chargeback (same institution): May have synchronous processing with immediate SUCCESS status
External Chargeback (other institutions): Asynchronous processing with PENDING status. Use Chargeback Status endpoint to track completion
Cannot create a new chargeback while a previous one is still PENDING for the same QR Code

Create PIX QR Code Chargeback

Authentication

Request Body

Request Examples

Response (200 OK)

Error Responses

Code Examples

cURL

JavaScript (Node.js)

Python

Business Rules

Authentication

Validations

Processing

Related Documentation

200Successful response