{"openapi":"3.1.0","info":{"title":"Chargeback Service","description":"These APIs provide authorized systems/users access to the Chargeback Service, enabling them to create chargebacks and manage their lifecycle.\n","version":"v1"},"servers":[{"url":"https://api.sandbox.eu.ppro.com","description":"Sandbox environment for integration testing"},{"url":"https://api.eu.ppro.com","description":"Production"}],"paths":{"/v1/chargebacks":{"get":{"tags":["Internal","Chargebacks"],"summary":"Get Chargebacks","description":"Returns all chargebacks associated with either a dispute ID or PPRO payment charge ID. Exactly one of [disputeId, paymentChargeId] must be provided.","operationId":"getChargebacks","parameters":[{"name":"disputeId","in":"query","description":"Dispute ID starting with 'dispute_' followed by 21 characters.","required":false,"schema":{"type":"string","pattern":"^dispute_.{21}"},"example":"dispute_20240619XYZabcdefghij"},{"name":"paymentChargeId","in":"query","description":"Payment Charge starting with 'charge_' followed by 21 characters.","required":false,"schema":{"type":"string","pattern":"^charge_.{21}"},"example":"charge_7s8FcBoJxMwVkWFR3B41p"},{"name":"Request-Reference","in":"header","description":"Optional Reference for the request. This is used to identify the request in debugging.","schema":{"type":"string"},"example":"unique-value-for-request-reference"}],"responses":{"200":{"description":"Successfully retrieved all chargebacks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChargebackResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Duplicate request received with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/chargeback-reversals":{"get":{"tags":["Internal","Chargebacks"],"summary":"Get Chargeback Reversals","description":"Returns all chargeback reversals associated with either a dispute ID or PPRO payment charge ID. Exactly one of [disputeId, paymentChargeId] must be provided.","operationId":"getChargebackReversals","parameters":[{"name":"disputeId","in":"query","required":false,"schema":{"type":"string","description":"Dispute ID starting with 'dispute_' followed by 21 characters. Exactly one of [disputeId, paymentChargeId] must be provided."}},{"name":"paymentChargeId","in":"query","required":false,"schema":{"type":"string","description":"Payment Charge ID starting with 'charge_' followed by 21 characters. Exactly one of [disputeId, paymentChargeId] must be provided."}},{"name":"Request-Reference","in":"header","description":"Optional Reference for the request. This is used to identify the request in debugging.","schema":{"type":"string"},"example":"unique-value-for-request-reference"}],"responses":{"200":{"description":"Successfully retrieved all chargeback reversals.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChargebackReversalResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Duplicate request received with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/chargebacks/{id}":{"get":{"tags":["Internal","Chargebacks"],"summary":"Get Chargeback","description":"Fetches chargeback details by id.","operationId":"getChargeback","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"disputeId","in":"query","description":"When set, must match the chargeback's dispute id or the request is rejected.","required":false,"schema":{"type":"string"}},{"name":"Request-Reference","in":"header","description":"Optional Reference for the request. This is used to identify the request in debugging.","schema":{"type":"string"},"example":"unique-value-for-request-reference"}],"responses":{"200":{"description":"Successfully retrieved the chargeback","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChargebackDetails"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Duplicate request received with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/chargeback-reversals/{id}":{"get":{"tags":["Internal","Chargebacks"],"summary":"Get Chargeback Reversal","description":"Fetches chargeback reversal details by id.","operationId":"getChargebackReversal","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"disputeId","in":"query","description":"When set, must match the chargeback reversal's dispute id or the request is rejected.","required":false,"schema":{"type":"string"}},{"name":"Request-Reference","in":"header","description":"Optional Reference for the request. This is used to identify the request in debugging.","schema":{"type":"string"},"example":"unique-value-for-request-reference"}],"responses":{"200":{"description":"Successfully retrieved the chargeback reversal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChargebackReversalDetails"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Duplicate request received with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"schemas":{"Amount":{"type":"object","properties":{"value":{"type":"integer","format":"int64"},"currency":{"type":"string"}},"required":["currency","value"]},"ChargebackTransferConfigDto":{"type":"object","properties":{"settledSlaInDays":{"type":"integer","format":"int32","deprecated":true,"description":"SLA in days for settled transfer expectation (strictly positive)."},"dueBy":{"type":"string","format":"date-time","description":"Due date for the transfer, in ISO 8601 UTC datetime format."}},"required":["settledSlaInDays"]},"CreateChargebackRequest":{"type":"object","description":"Create Chargeback","properties":{"amount":{"$ref":"#/components/schemas/Amount","description":"Amount transferred."},"transferStatus":{"type":"string","description":"Status of the transfer for settlement tracking.","enum":["EXPECTED","FAILED","SETTLED"]},"config":{"$ref":"#/components/schemas/ChargebackTransferConfigDto","description":"Optional SLA configuration; required when transferStatus is not SETTLED."},"reason":{"type":"string","description":"Reason code for the chargeback.","enum":["PDSP_AUTH_001","PDSP_AUTH_002","PDSP_AUTH_003","PDSP_AUTH_004","PDSP_PROD_001","PDSP_PROD_002","PDSP_PROD_003","PDSP_PROD_004","PDSP_PROD_005","PDSP_CANC_001","PDSP_CANC_002","PDSP_CANC_003","PDSP_CANC_004","PDSP_SUBS_001","PDSP_SUBS_002","PDSP_SUBS_003","PDSP_SUBS_004","PDSP_GEN_001","PDSP_GEN_002","PDSP_GEN_003"]},"providerReason":{"$ref":"#/components/schemas/ProviderReasonDto","description":"Provider reason details."},"receivedAt":{"type":"string","description":"Timestamp when the chargeback was received, in ISO 8601 UTC datetime format."},"paymentMethod":{"type":"string","description":"Payment method used."},"providerName":{"type":"string","description":"Provider name."},"processorName":{"type":"string","description":"Processor name."},"disputeId":{"type":"string","description":"Dispute ID of the dispute associated with the chargeback."},"providerChargebackReference":{"type":"string","description":"Provider chargeback reference."},"providerPaymentReference":{"type":"string","description":"Provider payment reference."},"merchantPaymentReference":{"type":"string","description":"Merchant payment reference."},"paymentChargeId":{"type":"string","description":"Payment charge ID."},"paymentOperationNumber":{"type":"string","description":"Payment operation number."},"chargebackContext":{"type":"object","additionalProperties":{"type":"string"},"description":"Additional chargeback context for the provider as key-value pairs."},"providerCaseReference":{"type":"string"}},"required":["amount","paymentMethod","processorName","receivedAt","transferStatus"]},"ProviderReasonDto":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"ApiError":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"status":{"type":"integer","format":"int32"},"failureMessage":{"type":"string"},"extensions":{"type":"object","additionalProperties":{"type":"string"}}}},"CreateChargebackResponse":{"type":"object","properties":{"id":{"type":"string"},"_links":{"$ref":"#/components/schemas/Links"}}},"CreateChargebackReversalRequest":{"type":"object","description":"Create Chargeback Reversal","properties":{"amount":{"$ref":"#/components/schemas/Amount","description":"Amount transferred."},"transferStatus":{"type":"string","description":"Status of the transfer for settlement tracking.","enum":["EXPECTED","FAILED","SETTLED"]},"config":{"$ref":"#/components/schemas/ChargebackTransferConfigDto","description":"Optional SLA configuration; required when transferStatus is not SETTLED."},"reason":{"type":"string","description":"Reason code for the chargeback reversal.","enum":["PDSP_AUTH_001","PDSP_AUTH_002","PDSP_AUTH_003","PDSP_AUTH_004","PDSP_PROD_001","PDSP_PROD_002","PDSP_PROD_003","PDSP_PROD_004","PDSP_PROD_005","PDSP_CANC_001","PDSP_CANC_002","PDSP_CANC_003","PDSP_CANC_004","PDSP_SUBS_001","PDSP_SUBS_002","PDSP_SUBS_003","PDSP_SUBS_004","PDSP_GEN_001","PDSP_GEN_002","PDSP_GEN_003"]},"providerReason":{"$ref":"#/components/schemas/ProviderReasonDto","description":"Provider reason details."},"receivedAt":{"type":"string","description":"Timestamp when the chargeback reversal was received, in ISO 8601 UTC datetime format."},"paymentMethod":{"type":"string","description":"Payment method used."},"providerName":{"type":"string","description":"Provider name."},"processorName":{"type":"string","description":"Processor name."},"disputeId":{"type":"string","description":"Dispute ID of the dispute associated with the chargeback reversal."},"providerChargebackReversalReference":{"type":"string","description":"Provider chargeback reversal reference."},"providerPaymentReference":{"type":"string","description":"Provider payment reference."},"merchantPaymentReference":{"type":"string","description":"Merchant payment reference."},"paymentChargeId":{"type":"string","description":"Payment charge ID."},"paymentOperationNumber":{"type":"string","description":"Payment operation number."},"chargebackReversalContext":{"type":"object","additionalProperties":{"type":"string"},"description":"Additional chargeback reversal context for the provider as key-value pairs."},"providerCaseReference":{"type":"string"}},"required":["amount","paymentMethod","processorName","receivedAt","transferStatus"]},"CreateChargebackReversalResponse":{"type":"object","properties":{"id":{"type":"string"},"_links":{"$ref":"#/components/schemas/Links"}}},"UpdateChargebackRequest":{"type":"object","description":"Update Chargeback","properties":{"amount":{"$ref":"#/components/schemas/Amount","description":"Amount transferred."},"transferStatus":{"type":"string","description":"Status of the transfer for settlement tracking.","enum":["SETTLED","FAILED"]},"chargebackContext":{"type":"object","additionalProperties":{"type":"string"},"description":"Additional chargeback context for the provider as key-value pairs."}},"required":["transferStatus"]},"UpdatePaymentAdjustmentEntityResponse":{"type":"object","properties":{"id":{"type":"string"},"_links":{"$ref":"#/components/schemas/Links"}}},"UpdateChargebackReversalRequest":{"type":"object","description":"Update Chargeback Reversal","properties":{"amount":{"$ref":"#/components/schemas/Amount","description":"Amount transferred."},"transferStatus":{"type":"string","description":"Status of the transfer for settlement tracking.","enum":["SETTLED","FAILED"]},"chargebackReversalContext":{"type":"object","additionalProperties":{"type":"string"},"description":"Additional chargeback reversal context for the provider as key-value pairs."}},"required":["transferStatus"]},"ChargebackDetails":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier.","example":"cb_20240619XYZabcdefghij or cr_20240619XYZabcdefghij"},"amount":{"$ref":"#/components/schemas/Amount","description":"Defines the value and currency."},"reason":{"type":"string","description":"Defines the reason.","enum":["PDSP_AUTH_001","PDSP_AUTH_002","PDSP_AUTH_003","PDSP_AUTH_004","PDSP_PROD_001","PDSP_PROD_002","PDSP_PROD_003","PDSP_PROD_004","PDSP_PROD_005","PDSP_CANC_001","PDSP_CANC_002","PDSP_CANC_003","PDSP_CANC_004","PDSP_SUBS_001","PDSP_SUBS_002","PDSP_SUBS_003","PDSP_SUBS_004","PDSP_GEN_001","PDSP_GEN_002","PDSP_GEN_003"]},"paymentChargeId":{"type":"string","description":"The payment charge identifier.","example":"charge_7s8FcBoJxMwVkWFR3B41p"},"disputeId":{"type":"string","description":"The unique identifier of the associated dispute.","example":"dispute_20240619XYZabcdefghij"},"transferStatus":{"type":"string","description":"Status of the transfer for settlement tracking.","enum":["EXPECTED","FAILED","SETTLED"]},"createdAt":{"type":"string","format":"date-time","description":"Date and time when the entity was created in PPRO.","example":"2025-06-19T12:34:56.789Z"},"updatedAt":{"type":"string","format":"date-time","description":"Date and Time when the entity was last updated.","example":"2025-06-19T12:34:56.789Z"},"_links":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"string"}}}}},"ChargebackResponse":{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/Pagination"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ChargebackDetails"}}}},"Pagination":{"type":"object","properties":{"totalPages":{"type":"integer","format":"int32"},"totalCount":{"type":"integer","format":"int32"},"currentPage":{"type":"integer","format":"int32"}}},"ChargebackReversalDetails":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier.","example":"cb_20240619XYZabcdefghij or cr_20240619XYZabcdefghij"},"amount":{"$ref":"#/components/schemas/Amount","description":"Defines the value and currency."},"reason":{"type":"string","description":"Defines the reason.","enum":["PDSP_AUTH_001","PDSP_AUTH_002","PDSP_AUTH_003","PDSP_AUTH_004","PDSP_PROD_001","PDSP_PROD_002","PDSP_PROD_003","PDSP_PROD_004","PDSP_PROD_005","PDSP_CANC_001","PDSP_CANC_002","PDSP_CANC_003","PDSP_CANC_004","PDSP_SUBS_001","PDSP_SUBS_002","PDSP_SUBS_003","PDSP_SUBS_004","PDSP_GEN_001","PDSP_GEN_002","PDSP_GEN_003"]},"paymentChargeId":{"type":"string","description":"The payment charge identifier.","example":"charge_7s8FcBoJxMwVkWFR3B41p"},"disputeId":{"type":"string","description":"The unique identifier of the associated dispute.","example":"dispute_20240619XYZabcdefghij"},"transferStatus":{"type":"string","description":"Status of the transfer for settlement tracking.","enum":["EXPECTED","FAILED","SETTLED"]},"createdAt":{"type":"string","format":"date-time","description":"Date and time when the entity was created in PPRO.","example":"2025-06-19T12:34:56.789Z"},"updatedAt":{"type":"string","format":"date-time","description":"Date and Time when the entity was last updated.","example":"2025-06-19T12:34:56.789Z"},"_links":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"string"}}}}},"ChargebackReversalResponse":{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/Pagination"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ChargebackReversalDetails"}}}},"Link":{"type":"object","properties":{"href":{"type":"string"},"hreflang":{"type":"string"},"title":{"type":"string"},"type":{"type":"string"},"deprecation":{"type":"string"},"profile":{"type":"string"},"name":{"type":"string"},"templated":{"type":"boolean"}}},"Links":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Link"}}}}}