Consult PIX QR Code Chargeback Status

GET https://api.somossimpay.com.br/v2/finance/chargebacks-pix-copy-and-paste/status

This API allows you to consult the status of a previously created chargeback. The query can be made using either the chargeback ID or the End-to-End ID.

Check Chargeback Status

GET /v2/finance/chargebacks-pix-copy-and-paste/status

Query the status of a previously created chargeback using either the chargeback ID or the End-to-End ID.

Authentication

Header	Type	Required	Example
Authorization	String	Yes	Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Query Parameters

Parameter	Type	Required	Description
id	Integer	Optional	Chargeback ID returned when creating the chargeback. Provide either id OR end_to_end_id, not both.
end_to_end_id	String	Optional	End-to-End ID (UUID) returned when creating. Provide either id OR end_to_end_id, not both.

⚠️

Important: You must provide exactly ONE parameter - either id OR end_to_end_id.

Request Examples

Check status by chargeback ID:

HTTP

GET /v2/finance/chargebacks-pix-copy-and-paste/status?id=98765
Authorization: Bearer <access_token>

Check status by End-to-End ID:

HTTP

GET /v2/finance/chargebacks-pix-copy-and-paste/status?end_to_end_id=E6070119020210521123456789012345678
Authorization: Bearer <access_token>

Response (200 OK)

JSON

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

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

Status Values

Status	Description
PENDING	Chargeback is being processed. Query again after a few minutes.
SUCCESS	Chargeback successfully completed. The refund has been processed and amount returned.
REJECTED	Chargeback was rejected. The refund could not be completed.

Error Responses

Status Code	Error Message	Cause
400	Either 'id' or 'end_to_end_id' parameter is required	No parameter provided. Must send one.
400	Only one parameter should be provided	Both parameters sent. Send only one.
400	Chargeback not found	Invalid ID or doesn't belong to your account
401	Unauthorized	Invalid or missing Bearer token
422	Validation error	Query parameter validation failed

Code Examples

cURL

Bash

# By ID
curl --request GET \
  --url 'https://api.somossimpay.com.br/v2/finance/chargebacks-pix-copy-and-paste/status?id=98765' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

# By End-to-End ID
curl --request GET \
  --url 'https://api.somossimpay.com.br/v2/finance/chargebacks-pix-copy-and-paste/status?end_to_end_id=E6070119020210521123456789012345678' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

JavaScript (Node.js)

JavaScript

const axios = require('axios');

async function checkChargebackStatus(accessToken, chargebackId = null, endToEndId = null) {
  if (!chargebackId && !endToEndId) {
    throw new Error('Either chargebackId or endToEndId must be provided');
  }

  const params = chargebackId ? { id: chargebackId } : { end_to_end_id: endToEndId };

  try {
    const response = await axios.get(
      'https://api.somossimpay.com.br/v2/finance/chargebacks-pix-copy-and-paste/status',
      {
        params,
        headers: {
          'Authorization': `Bearer ${accessToken}`
        }
      }
    );

    const { id, status, amount } = response.data;
    console.log(`Chargeback ${id}: ${status} - ${amount} BRL`);
    
    return response.data;
  } catch (error) {
    console.error('Error checking status:', error.response?.data || error.message);
    throw error;
  }
}

// Usage
checkChargebackStatus(accessToken, 98765);  // By ID
checkChargebackStatus(accessToken, null, 'E6070119020210521123456789012345678');  // By E2E ID

Python

Python

import requests

def check_chargeback_status(access_token, chargeback_id=None, end_to_end_id=None):
    if not chargeback_id and not end_to_end_id:
        raise ValueError("Either chargeback_id or end_to_end_id must be provided")
    
    url = "https://api.somossimpay.com.br/v2/finance/chargebacks-pix-copy-and-paste/status"
    
    params = {"id": chargeback_id} if chargeback_id else {"end_to_end_id": end_to_end_id}
    
    headers = {
        "Authorization": f"Bearer {access_token}"
    }
    
    try:
        response = requests.get(url, params=params, headers=headers)
        response.raise_for_status()
        
        data = response.json()
        print(f"Chargeback {data['id']}: {data['status']} - {data['amount']} BRL")
        
        return data
    
    except requests.exceptions.HTTPError as e:
        print(f"Error checking status: {e.response.text}")
        raise

# Usage
check_chargeback_status(access_token, chargeback_id=98765)  # By ID
check_chargeback_status(access_token, end_to_end_id='E6070119020210521123456789012345678')  # By E2E ID

Business Rules

Authentication

• Requires valid Bearer token
• User must be authenticated

Parameter Requirements

• Exactly one parameter must be provided: either id OR end_to_end_id
• Cannot provide both parameters
• Cannot omit both parameters

Query Identifiers

• Use id for queries using the chargeback ID returned when creating
• Use end_to_end_id for queries using the End-to-End ID for reconciliation
• Both identifiers are unique and valid for querying

Authorization

• The chargeback must belong to your account
• Only the account that created the chargeback can query its status

Polling Recommendations

• For PENDING status, wait at least 30 seconds between queries
• External chargebacks typically complete within 5-10 minutes
• If a chargeback remains PENDING for >30 minutes, contact support
• Consider implementing webhooks for real-time notifications instead of polling

Related Documentation

• Create Chargeback - Request a chargeback
• Chargeback API Overview - Complete chargeback guide