SocredDocs

    Request a Chargeback by QR Code

    This API allows you to request a chargeback (full or partial) for a paid PIX QR Code. The chargeback processing is asynchronous and the status can be consulted later through the Chargeback Status API.

    POSThttps://api.socredsa.com.br/v2/finance/chargebacks-pix-copy-and-paste
    curl --request POST \
  --url 'https://api.socredsa.com.br/v2/finance/chargebacks-pix-copy-and-paste' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "qr_code_id": 12345,
  "information": "Full refund - customer canceled order",
  "amount": 100
}'
    Response200
    {
  "worked": true,
  "id": 98765,
  "end_to_end_id": "E6070119020210521123456789012345678",
  "amount": 50,
  "status": "PENDING",
  "fee": 0
}

    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

    HeaderTypeRequiredExample
    AuthorizationStringYesBearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
    Content-TypeStringYesapplication/json

    Request Body

    ParameterTypeRequiredDescription
    qr_code_idIntegerYesID of the PIX QR Code to be refunded. Unique identifier of the QR Code transaction.
    informationStringYesReason/information for the chargeback. Descriptive text documenting why the chargeback is requested.
    amountDecimalYesChargeback 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
}
    FieldTypeDescription
    workedBooleanAlways true for successful requests.
    idIntegerUnique chargeback identifier. Use to query status later.
    end_to_end_idStringEnd-to-End ID of the refund transaction. Always present in a successful response.
    amountDecimalThe chargeback amount requested.
    statusStringPENDING - Processing. SUCCESS - Completed. REJECTED - Failed.
    feeDecimalTransaction fee. Usually 0.00 for chargebacks.

    Error Responses

    Status CodeError MessageCause
    400QR Code not foundInvalid qr_code_id, or the QR Code is not available for the account you can access
    400QR Code is not paidQR Code has not been paid, so there is nothing to refund
    400Transaction Cashin not foundThe payment linked to this QR Code could not be found
    400Chargeback period (90 days) has expiredThe payment is older than 90 days and can no longer be refunded
    400There is a refund in processingA PENDING chargeback already exists for this QR Code
    400Amount is greater than the value of the QR CodeThe requested amount, added to what was already refunded, exceeds the QR Code value
    400Insufficient balanceThe account does not have enough balance to cover the refund
    400Cannot process chargeback for closed accountThe account that received the payment is closed
    400Cannot process chargeback for closed destination accountThe payer's account is closed and cannot receive the refund
    400Destination account in the process of closing cannot receive chargebackThe payer's account is being closed and cannot receive the refund
    400Transaction Cashout not foundThe counterpart transaction of the original payment could not be found
    400field: messageRequest validation failed. The detail names the offending field, e.g. amount: Input should be greater than 0
    400provider messageThe refund was refused by the payment system. The detail carries the message returned by it
    401Not authenticatedMissing, malformed or expired Bearer token

    All errors are returned in the standard error envelope:

    {
  "worked": false,
  "detail": "There is a refund in processing",
  "message": "There is a refund in processing",
  "data": null
}

    Code Examples

    cURL

    curl --request POST \
  --url https://api.socredsa.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.socredsa.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.socredsa.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 the QR Code value minus what was already refunded
    • The payment must be at most 90 days old
    • The account must have enough available balance at the moment of the request
    • Neither the receiving nor the payer account can be closed or in the process of closing
    • 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