From 08837a86b7ab472aa9d84c7bbcab8cdff022ca5b Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Sat, 25 May 2024 00:14:09 +0200 Subject: [PATCH] polymorphic_refund_model --- .../carrier_billing_refund.yaml | 205 +++++++++--------- 1 file changed, 103 insertions(+), 102 deletions(-) diff --git a/code/API_definitions/carrier_billing_refund.yaml b/code/API_definitions/carrier_billing_refund.yaml index 837ec65..e6ffd82 100644 --- a/code/API_definitions/carrier_billing_refund.yaml +++ b/code/API_definitions/carrier_billing_refund.yaml @@ -149,13 +149,15 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/RefundCreated" + $ref: "#/components/schemas/Refund" "400": $ref: "#/components/responses/RefundInvalid400" "401": $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/RefundPermissionDenied403" + "404": + $ref: "#/components/responses/Generic404" "422": $ref: "#/components/responses/CreateRefundUnprocessableContent422" "409": @@ -292,17 +294,15 @@ components: schemas: CreateRefund: type: object + description: Information to create a Refund resource. required: - - amountTransaction - type properties: - amountTransaction: - $ref: "#/components/schemas/AmountTransactionInput" type: type: string description: |- Type of refund. - - `total` stands for a final refund, whose amount can be indicated by API Consumer (PENDING POINT). No more refunds are allowed for that `paymentId`. + - `total` stands for a final refund, where whole amount is refunded so as it is not indicated by API Consumer. No more refunds are allowed for that `paymentId`. - `partial` stands for a partial refund, whose amount is indicated by API Consumer. More refunds are allowed for that `paymentId`. enum: - total @@ -314,60 +314,33 @@ components: allOf: - $ref: "#/components/schemas/Webhook" - description: Information to manage refund notifications - RefundCreated: - type: object - required: - - amountTransaction - - refundId - - refundStatus - - refundCreationDate - - type - properties: - refundId: - type: string - description: Unique Identifier of the refund - example: "AK234rfweSBuWGFUEWFGWEVWRV" - refundStatus: - type: string - description: - Specifies the refund status (`processing`, `denied`, `succeeded`). - example: "processing" - type: - type: string - description: |- - Type of refund. - - `total` stands for a final refund, whose amount can be indicated by API Consumer. No more refunds are allowed for that `paymentId`. - - `partial` stands for a partial refund, whose amount is indicated by API Consumer. More refunds are allowed for that `paymentId`. - enum: - - total - - partial - amountTransaction: - $ref: "#/components/schemas/AmountTransaction" - refundCreationDate: - type: string - format: date-time - description: Date time when the refund is created in server database. This is a technical information. It must follow RFC 3339 and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). - refundDate: - type: string - format: date-time - description: Date time when the refund is effectively performed. This is a business information. It must follow RFC 3339 and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). - reason: - type: string - description: Reason provided to request the refund. Optionally provided by the user or the merchant. - webhook: - allOf: - - $ref: "#/components/schemas/Webhook" - - description: Information to manage refund notifications - RefundArray: - description: A list of refund(s) - type: array - minItems: 0 - items: - $ref: "#/components/schemas/Refund" + discriminator: + propertyName: type + mapping: + total: "#/components/schemas/CreateTotalRefund" + partial: "#/components/schemas/CreatePartialRefund" + CreateTotalRefund: + allOf: + - $ref: "#/components/schemas/CreateRefund" + - type: object + required: + - amountTransaction + properties: + amountTransaction: + $ref: "#/components/schemas/AmountTransactionTotalRefund" + CreatePartialRefund: + allOf: + - $ref: "#/components/schemas/CreateRefund" + - type: object + required: + - amountTransaction + properties: + amountTransaction: + $ref: "#/components/schemas/AmountTransactionPartialRefund" Refund: type: object + description: Information about a Refund resource. required: - - amountTransaction - refundId - refundStatus - refundCreationDate @@ -386,13 +359,11 @@ components: type: string description: |- Type of refund. - - `total` stands for a final refund, whose amount can be indicated by API Consumer. No more refunds are allowed for that `paymentId`. + - `total` stands for a final refund, where whole amount is refunded so as it is not indicated by API Consumer. No more refunds are allowed for that `paymentId`. - `partial` stands for a partial refund, whose amount is indicated by API Consumer. More refunds are allowed for that `paymentId`. enum: - total - partial - amountTransaction: - $ref: "#/components/schemas/AmountTransaction" refundCreationDate: type: string format: date-time @@ -408,24 +379,34 @@ components: allOf: - $ref: "#/components/schemas/Webhook" - description: Information to manage refund notifications - Webhook: + discriminator: + propertyName: type + mapping: + total: "#/components/schemas/TotalRefund" + partial: "#/components/schemas/PartialRefund" + TotalRefund: + allOf: + - $ref: "#/components/schemas/Refund" + - type: object + required: + - amountTransaction + properties: + amountTransaction: + $ref: "#/components/schemas/AmountTransactionTotalRefund" + PartialRefund: + allOf: + - $ref: "#/components/schemas/Refund" + - type: object + required: + - amountTransaction + properties: + amountTransaction: + $ref: "#/components/schemas/AmountTransactionPartialRefund" + AmountTransactionTotalRefund: type: object - required: - - notificationUrl - properties: - notificationUrl: - type: string - description: Callback URL to allow asynchronous delivery of refund related events - example: "https://myservice.com/refund/events" - notificationAuthToken: - type: string - description: Authentification token for callback endpoint - example: "c8974e592c2fa383d4a3960714" - AmountTransaction: required: - refundAmount - referenceCode - type: object properties: clientCorrelator: type: string @@ -433,23 +414,23 @@ components: Uniquely identifies this create refund request. If there is a communication failure during the refund request, using the same clientCorrelator when retrying the request allows the operator to avoid applying the same - refund twice. This field SHOULD be present. Same value as indicated in the request. + charge twice. This field SHOULD be present. example: "req-12f2pgh448gh2hvrfrv" refundAmount: - $ref: "#/components/schemas/RefundAmount" + $ref: "#/components/schemas/RefundAmountTotalRefund" referenceCode: type: string description: Merchant generated refund reference to uniquely identify the - request, for instance, in the case of disputes. Same value as the one provided in the request. + request, for instance, in the case of disputes. example: "ref-refund-834tfr2rA3v8r8vr3rv" - serverReferenceCode: - type: string - description: - Reference to the charge or refund, provided by the server, - and meaningful to the server’s backend system for the purpose of reconciliation. - example: "ref-pay-834tfr2rA3v8r8vr3rv-serv" - AmountTransactionInput: + RefundAmountTotalRefund: + type: object + description: Information for a `total` refund. Whole amount is refunded so as it is not needed to be provided, then it can be an empty object unless `merchantIdentifier` is indicated. + properties: + chargingMetaData: + $ref: "#/components/schemas/ChargingMetaData" + AmountTransactionPartialRefund: type: object required: - refundAmount @@ -464,15 +445,16 @@ components: charge twice. This field SHOULD be present. example: "req-12f2pgh448gh2hvrfrv" refundAmount: - $ref: "#/components/schemas/RefundAmount" + $ref: "#/components/schemas/RefundAmountPartialRefund" referenceCode: type: string description: Merchant generated refund reference to uniquely identify the request, for instance, in the case of disputes. example: "ref-refund-834tfr2rA3v8r8vr3rv" - RefundAmount: + RefundAmountPartialRefund: type: object + description: Information for a `partial` refund. Amount to be refunded is required. required: - chargingInformation properties: @@ -482,13 +464,26 @@ components: $ref: "#/components/schemas/ChargingMetaData" refundDetails: $ref: "#/components/schemas/RefundDetails" - RefundDetails: + RefundArray: + description: A list of refund(s) type: array - description: Detailed description of the concepts/items considered within a specific refund procedure. - minItems: 1 + minItems: 0 items: - $ref: "#/components/schemas/RefundItem" - RefundItem: + $ref: "#/components/schemas/Refund" + Webhook: + type: object + required: + - notificationUrl + properties: + notificationUrl: + type: string + description: Callback URL to allow asynchronous delivery of refund related events + example: "https://myservice.com/refund/events" + notificationAuthToken: + type: string + description: Authentification token for callback endpoint + example: "c8974e592c2fa383d4a3960714" + ChargingInformation: type: object required: - amount @@ -500,7 +495,7 @@ components: format: float multipleOf: 0.001 minimum: 0.001 - description: Specific amount to be refunded referred to a specific item. + description: Amount to be refunded. example: 100 currency: type: string @@ -508,7 +503,7 @@ components: example: "EUR" description: type: string - description: Description text to be used for information and billing text referred to a specific item. + description: Description text to be used for information and billing text example: "FIFA EA Sports 24" isTaxIncluded: type: boolean @@ -522,7 +517,20 @@ components: description: | The tax amount refunded by the merchant. Indicated when the merchant is the one applying taxes. This field also provides an indicator to the downstream billing system. example: 21 - ChargingInformation: + ChargingMetaData: + type: object + properties: + merchantIdentifier: + type: string + description: Indicates the merchant identifier. Allows aggregators/partners to specify the actual merchant identifier + example: "eas-12345" + RefundDetails: + type: array + description: Detailed description of the concepts/items considered within a specific refund procedure. + minItems: 1 + items: + $ref: "#/components/schemas/RefundItem" + RefundItem: type: object required: - amount @@ -534,7 +542,7 @@ components: format: float multipleOf: 0.001 minimum: 0.001 - description: Amount to be refunded. + description: Specific amount to be refunded referred to a specific item. example: 100 currency: type: string @@ -542,7 +550,7 @@ components: example: "EUR" description: type: string - description: Description text to be used for information and billing text + description: Description text to be used for information and billing text referred to a specific item. example: "FIFA EA Sports 24" isTaxIncluded: type: boolean @@ -556,13 +564,6 @@ components: description: | The tax amount refunded by the merchant. Indicated when the merchant is the one applying taxes. This field also provides an indicator to the downstream billing system. example: 21 - ChargingMetaData: - type: object - properties: - merchantIdentifier: - type: string - description: Indicates the merchant identifier. Allows aggregators/partners to specify the actual merchant identifier - example: "eas-12345" CloudEvent: description: The notification format required: