> For the complete documentation index, see [llms.txt](https://yutax.gitbook.io/developer/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yutax.gitbook.io/developer/api-reference/chargebacks.md).

# Chargebacks

Registro de chargebacks

## Crear chargeback

> Crea un chargeback.\
> REQUIRED: - fullname - (email OR phone) - original\_transaction\_id - transaction\_date (YYYY-MM-DD o YYYY-MM-DD HH:MM:SS) - posting\_date (YYYY-MM-DD o YYYY-MM-DD HH:MM:SS) - transaction\_amount (decimal string) - transaction\_currency (USD/EUR/GBP/DOP/CUP/MLC/OTHER) - transaction\_type\_code (CODE del catálogo \`chargeback\_tx\_type\_catalog\`)\
> REQUIRED por lógica de servidor: - user\_report\_id o user\_account\_id (para offender)  (si no, 400)\
> Opcional: - ci, address, notes - user\_victim\_report\_id o user\_victim\_account\_id (si no viene, se guarda vacío)<br>

```json
{"openapi":"3.0.3","info":{"title":"Yutax API","version":"1.0.0"},"tags":[{"name":"Chargebacks","description":"Registro de chargebacks"}],"servers":[{"url":"https://business.yutax.net","description":"Host placeholder (cambia por tu dominio)"}],"security":[{"HmacHeaders":[]}],"components":{"securitySchemes":{"HmacHeaders":{"type":"apiKey","in":"header","name":"X-SIGNATURE","description":"Auth por headers.\nHeaders: - X-PUBLIC-KEY: public key del business (test o live) - X-TIMESTAMP: unix timestamp (string numérico) - X-NONCE: opcional - X-SIGNATURE: Base64(HMAC-SHA256(stringToSign, privateKey))\nstringToSign:\n  POST\\n{path}\\n{timestamp}\\n{nonce}\\n{sha256(body)}\\n\n\nNota: en NDJSON bulk, el server usa sha256 del body gzip real.\n"}},"parameters":{"XPublicKey":{"name":"X-PUBLIC-KEY","in":"header","required":true,"schema":{"type":"string"},"description":"Public key (ej- yk_live_pk_...)"},"XTimestamp":{"name":"X-TIMESTAMP","in":"header","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Unix timestamp (string numérico)"},"XNonce":{"name":"X-NONCE","in":"header","required":false,"schema":{"type":"string"},"description":"Nonce opcional"},"XSignature":{"name":"X-SIGNATURE","in":"header","required":true,"schema":{"type":"string"},"description":"Firma HMAC base64"}},"schemas":{"ChargebackCreateRequest":{"type":"object","additionalProperties":false,"required":["fullname","user_report_id","user_account_id","original_transaction_id","transaction_date","posting_date","transaction_amount","transaction_currency","transaction_type_code"],"allOf":[{"anyOf":[{"required":["email"]},{"required":["phone"]}]},{"anyOf":[{"required":["user_report_id"]},{"required":["user_account_id"]}]}],"properties":{"fullname":{"type":"string","maxLength":150},"ci":{"type":"string","maxLength":50},"email":{"type":"string","maxLength":190,"description":"Requerido si phone vacío (regla - email or phone)"},"phone":{"type":"string","maxLength":40,"description":"Requerido si type vacío (regla - email or phone)"},"address":{"type":"string","maxLength":255},"user_report_id":{"type":"integer","nullable":true,"description":"Offender por report_id (alternativa a user_account_id)"},"user_account_id":{"type":"integer","nullable":true,"description":"Offender por account_id (alternativa a user_report_id)"},"user_victim_report_id":{"type":"integer","nullable":true,"description":"Victim por report_id (alternativa a user_victim_account_id)"},"user_victim_account_id":{"type":"integer","nullable":true,"description":"Victim por account_id (alternativa a user_victim_report_id)"},"original_transaction_id":{"type":"string","maxLength":100},"transaction_date":{"type":"string","description":"YYYY-MM-DD o YYYY-MM-DD HH:MM:SS"},"posting_date":{"type":"string","description":"YYYY-MM-DD o YYYY-MM-DD HH:MM:SS"},"transaction_amount":{"type":"string","description":"Decimal como string"},"transaction_currency":{"$ref":"#/components/schemas/CurrencyCode"},"transaction_type_code":{"type":"string","enum":["DEPOSIT","P2P_TRANSFER","CARD_PURCHASE","ECOMMERCE","IN_STORE","WALLET_TRANSFER","ATM_WITHDRAWAL","DIGITAL_GOODS","SERVICES","CRYPTO","BNPL","OTHER"],"description":"CODE del catálogo chargeback_tx_type_catalog.\nEj: P2P_TRANSFER = \"P2P Transfer\"\n"},"notes":{"type":"string","maxLength":5000}}},"CurrencyCode":{"type":"string","description":"Si no viene, default USD","enum":["USD","EUR","GBP","DOP","CUP","MLC","OTHER"]},"ChargebackCreateResponse":{"type":"object","additionalProperties":false,"required":["ok","chargeback_id","business_id","created_at","transaction_type","allowed_currencies"],"properties":{"ok":{"type":"boolean"},"chargeback_id":{"type":"integer"},"business_id":{"type":"integer"},"created_at":{"type":"string"},"transaction_type":{"type":"object","additionalProperties":false,"required":["code","id"],"properties":{"code":{"type":"string"},"id":{"type":"integer"}}},"allowed_currencies":{"type":"array","items":{"$ref":"#/components/schemas/CurrencyCode"}}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Código de error"},"message":{"type":"string","description":"Mensaje legible (cuando aplique)"}}}},"responses":{"AuthError":{"description":"Auth inválida / headers faltantes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"MethodNotAllowed":{"description":"Método no permitido (solo POST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/chargeback/create":{"post":{"tags":["Chargebacks"],"summary":"Crear chargeback","description":"Crea un chargeback.\nREQUIRED: - fullname - (email OR phone) - original_transaction_id - transaction_date (YYYY-MM-DD o YYYY-MM-DD HH:MM:SS) - posting_date (YYYY-MM-DD o YYYY-MM-DD HH:MM:SS) - transaction_amount (decimal string) - transaction_currency (USD/EUR/GBP/DOP/CUP/MLC/OTHER) - transaction_type_code (CODE del catálogo `chargeback_tx_type_catalog`)\nREQUIRED por lógica de servidor: - user_report_id o user_account_id (para offender)  (si no, 400)\nOpcional: - ci, address, notes - user_victim_report_id o user_victim_account_id (si no viene, se guarda vacío)\n","parameters":[{"$ref":"#/components/parameters/XPublicKey"},{"$ref":"#/components/parameters/XTimestamp"},{"$ref":"#/components/parameters/XNonce"},{"$ref":"#/components/parameters/XSignature"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChargebackCreateRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChargebackCreateResponse"}}}},"400":{"description":"Error de validación / relaciones / catálogo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/AuthError"},"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}}}}
```