Transactions - Dispute

{
  "receipt": null,
  "id": "tra_01hqzvabc",
  "customId": "PEDIDO-1042",
  "amount": 5000,
  "originalAmount": 5000,
  "status": "dispute",
  "method": "credit",
  "currency": "BRL",
  "payment": {
    "provider": "selectwin",
    "version": "1.1",
    "refused": null,
    "reusable": false,
    "billetUrl": null,
    "billetBarcode": null,
    "billetSequence": null,
    "billetDocumentNumber": null,
    "billetReferenceNumber": null,
    "pixQrCodeEmv": null,
    "pixQrCodeUrl": null,
    "pixQrCodeImage": null,
    "acquirerTransactionNumber": "A1B2C3D4E5",
    "cardFirstDigits": "411111",
    "cardLastDigits": "1111",
    "cardBrand": "visa",
    "cardRegistered": false,
    "installments": 3,
    "expirationDate": null,
    "paidAt": "2026-04-12T17:56:33.000Z",
    "allowRenewPayment": false,
    "invoiceLink": "https://selectwin.io/invoices/tra_01hqzvabc"
  },
  "discount": null,
  "customer": {
    "id": "cus_01hqzvabc",
    "firstName": "João",
    "lastName": "Silva",
    "email": "[email protected]",
    "birthdate": "1990-01-15",
    "gender": "male",
    "document": {
      "type": "cpf",
      "number": "12345678901"
    },
    "telephone": {
      "countryCode": "55",
      "areaCode": "11",
      "number": "999999999",
      "line": "5511999999999"
    },
    "available": true,
    "delinquent": false,
    "externalReference": "CRM-USER-001",
    "additionalEmails": null,
    "metadata": {},
    "updatedAt": "2026-04-12T17:56:33.000Z",
    "createdAt": "2026-04-10T09:15:25.000Z"
  },
  "billing": {
    "address": {
      "id": "addr_01hqzvabc",
      "ownerId": "cus_01hqzvabc",
      "ownerType": "customer",
      "street": "Av. Paulista",
      "number": "1000",
      "complement": "Apt 42",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postcode": "01310-100",
      "country": "BR",
      "latitude": -23.5613,
      "longitude": -46.6558,
      "line": "Av. Paulista, 1000 - Apt 42 - Bela Vista, São Paulo - SP, 01310-100",
      "line1": "Av. Paulista, 1000",
      "line2": "Apt 42",
      "line3": "Bela Vista",
      "updatedAt": "2026-04-10T09:15:25.000Z",
      "createdAt": "2026-04-10T09:15:25.000Z"
    }
  },
  "shipping": null,
  "externalReference": "order-9981",
  "shippable": false,
  "spplited": false,
  "items": [
    {
      "id": "item_01hqzvabc",
      "name": "Premium Plan",
      "unitPrice": 5000,
      "quantity": 1,
      "currency": "BRL",
      "description": "Assinatura mensal",
      "images": [
        "https://cdn.example.com/product.png"
      ],
      "isUpsell": false,
      "isOrderbump": false,
      "metadata": {
        "sku": "SKU-1"
      },
      "variantId": "var_01hqzvabc",
      "externalReference": "line-1",
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:32.000Z"
    }
  ],
  "receivables": [
    {
      "id": "rec_01hqzvabc",
      "recipient": "bus_1234567890",
      "split": null,
      "status": "dispute",
      "amount": 4805,
      "grossAmount": 5000,
      "anticipationFee": 0,
      "installmentNumber": 1,
      "description": null,
      "currency": "BRL",
      "authorizationCode": "654321",
      "paidAt": "2026-04-12T17:56:33.000Z",
      "refundedAt": null,
      "canceledAt": null,
      "expectedOn": "2026-05-12",
      "liable": true,
      "chargeProcessingFee": true,
      "updatedAt": "2026-04-13T10:00:00.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "splits": null,
  "refunds": null,
  "disputes": [
    {
      "id": "dsp_01hqzvabc",
      "returnEmail": "[email protected]",
      "description": "Cliente alega não recebimento do produto.",
      "deliveryProof": [
        {
          "description": "Comprovante de entrega assinado",
          "assetUrl": "https://cdn.example.com/disputes/delivery-proof.pdf",
          "authentication": {
            "username": null,
            "password": null,
            "token": null
          }
        }
      ],
      "shipmentProof": [
        {
          "description": "Etiqueta de postagem dos Correios",
          "assetUrl": "https://cdn.example.com/disputes/shipment-label.pdf",
          "authentication": {
            "username": null,
            "password": null,
            "token": null
          },
          "carrier": "Correios",
          "trackingCode": "BR123456789BR",
          "shippingDate": "2026-04-12"
        }
      ],
      "deliveryReceipts": null,
      "fiscalDocuments": null,
      "communicationProof": null,
      "updatedAt": "2026-04-13T10:00:00.000Z",
      "createdAt": "2026-04-13T10:00:00.000Z"
    }
  ],
  "timeline": [
    {
      "id": "tml_03hqzvabc",
      "message": "Transaction dispute opened",
      "details": null,
      "type": "status",
      "updatedAt": "2026-04-13T10:00:00.000Z",
      "createdAt": "2026-04-13T10:00:00.000Z"
    },
    {
      "id": "tml_01hqzvabc",
      "message": "Transaction created",
      "details": null,
      "type": "status",
      "updatedAt": "2026-04-12T17:56:32.000Z",
      "createdAt": "2026-04-12T17:56:32.000Z"
    }
  ],
  "callback": null,
  "metadata": {},
  "updatedAt": "2026-04-13T10:00:00.000Z",
  "createdAt": "2026-04-12T17:56:32.000Z",
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/transactions/tra_01hqzvabc",
      "method": "PUT",
      "description": "Dispute the transaction."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/transactions",
      "method": "POST",
      "description": "Create a new transaction."
    },
    "read": {
      "href": "https://api.selectwin.io/v1/transactions/tra_01hqzvabc",
      "method": "GET",
      "description": "Read a transaction."
    },
    "refund": {
      "href": "https://api.selectwin.io/v1/transactions/tra_01hqzvabc/refund",
      "method": "POST",
      "description": "Refund the transaction."
    },
    "list": {
      "href": "https://api.selectwin.io/v1/transactions",
      "method": "GET",
      "description": "List all transactions."
    }
  }
}

{
  "error": {
    "status": "Bad Request",
    "statusCode": 400,
    "category": "validation",
    "message": "Validation errors occurred",
    "details": "One or more parameters are invalid or out of range. Please check the parameters and try again.",
    "params": [
      {
        "payment[currency]": "currency must be one of [BRL]"
      },
      {
        "amount": "amount is required"
      }
    ],
    "code": "invalidParameters",
    "resource": "client"
  }
}

{
  "error": {
    "status": "Unauthorized",
    "statusCode": 401,
    "category": "authentication",
    "message": "Unauthorized",
    "details": "Authentication failed. The provided API key is invalid or does not have permission to operate.",
    "code": "unauthorized"
  }
}

{
  "error": {
    "status": "Request Failed",
    "statusCode": 402,
    "category": "payment",
    "code": "insufficientFundsError",
    "type": "cardError",
    "message": "The request was valid, but the payment process failed.",
    "details": "Please verify your payment information and try again.",
    "params": [
      {
        "payment": "Saldo insuficiente para realizar esta compra. Verifique seu limite disponível."
      }
    ],
    "displayMessage": "Saldo insuficiente para realizar esta compra. Verifique seu limite disponível.",
    "reversible": false
  }
}

{
  "error": {
    "status": "Forbidden",
    "statusCode": 403,
    "category": "authorization",
    "message": "Forbidden",
    "details": "Access denied. This may be due to IP blocks, domain restrictions, or insufficient permissions.",
    "code": "forbidden"
  }
}

{
  "error": {
    "status": "Not Found",
    "statusCode": 404,
    "category": "client",
    "message": "Not Found",
    "details": "The requested resource was not found on the server.",
    "code": "notFound"
  }
}

{
  "error": {
    "status": "Unprocessable Entity",
    "statusCode": 422,
    "category": "validation",
    "message": "Unprocessable Entity",
    "details": "The request was understood, but contains invalid data that could not be processed.",
    "code": "unprocessableEntity"
  }
}

{
  "error": {
    "status": "Too Many Requests",
    "statusCode": 429,
    "category": "rate_limit",
    "message": "Too Many Requests",
    "details": "The number of requests exceeded the limit allowed for the IP or user.",
    "retryAfterMinutes": 60,
    "code": "tooManyRequests"
  }
}

{
  "error": {
    "status": "Internal Server Error",
    "statusCode": 500,
    "category": "server",
    "message": "Server error.",
    "details": "An internal server error occurred. Please try again later.",
    "code": "serverError",
    "resource": "server"
  }
}