From f8762e8a50df5696587b4c048f2c46f74d637c9f Mon Sep 17 00:00:00 2001 From: Simone Infante Date: Tue, 14 Mar 2023 21:11:14 +0100 Subject: [PATCH 1/6] feat: update openapi --- api-specs/api_spec_PGS.yaml | 422 ++++++++++++++---------------------- 1 file changed, 165 insertions(+), 257 deletions(-) diff --git a/api-specs/api_spec_PGS.yaml b/api-specs/api_spec_PGS.yaml index d95465ff..93b46312 100644 --- a/api-specs/api_spec_PGS.yaml +++ b/api-specs/api_spec_PGS.yaml @@ -1,7 +1,19 @@ -openapi: 3.0.1 -info: - title: OpenAPI definition - version: v0 +openapi: 3.0.3 +info: + title: Openapi for pagopa-payment-transactions-gateway (PGS) + version: 0.0.1 + description: | + Openapi definition for the API exposed by the *pagopa-payment-transactions-gateway* (**PGS**) and + consumed by the pagoPA touchpoints (for example *pagopPA - checkout* via *pagoPA - ecommerce*) to + authorize payments via the following payment gateway: +
    +
  1. xpay
    2. +
  2. vpos
    3. +
  3. bancomatpay
    4. +
  4. postepay
    5. +
+externalDocs: + url: https://pagopa.atlassian.net/wiki/spaces/TKM/overview servers: - url: http://localhost:8080/ description: Generated server url @@ -395,65 +407,150 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /request-payments/xpay: - post: - summary: payment authorization request to xPay - tags: - - XPay - operationId: auth-request-xpay - parameters: - - in: header - name: X-Client-ID - description: channel origin (APP/Web) - example: APP - schema: - type: string - required: true - - in: header - name: MDC-Fields - description: MDC information - example: 97g10t83x7bb0437bbc50sdf58e970gt - schema: - type: string - required: false - requestBody: - content: - application/json: + /payment-authorizations/xpay: + post: + summary: New payment authorization request to xpay + description: Creation of a new payment authorization request to *xpay* and return url on which to complete the frontend authorization flow + tags: + - XPay + operationId: new-auth-payment-request-xpay + parameters: + - in: header + name: x-client-id + description: touchpoint client + schema: + type: string + enum: + - ECOMMERCE_CHECKOUT + - ECOMMERCE_APP_IO + required: true + - in: header + name: MDC-Fields + description: MDC information + example: 97g10t83x7bb0437bbc50sdf58e970gt + schema: + type: string + required: false + requestBody: + content: + application/json: schema: - $ref: '#/components/schemas/XPayAuthRequest' + $ref: '#/components/schemas/XPayPaymentAuthorizationRequest' + required: true + responses: + "202": + description: Authorization requested + content: + application/json: + schema: + $ref: '#/components/schemas/XPayPaymentAuthorizationRequestAccepted' + "400": + description: Bad request + content: + application/json: + schema: + $ref: '#/components/schemas/XPayPaymentAuthorizationError' + "409": + description: transactionId already processed + content: + application/json: + schema: + $ref: '#/components/schemas/XPayPaymentAuthorizationError' + "500": + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/XPayPaymentAuthorizationError' + /payment-authorizations/xpay/{paymentAuthorizationId}: + get: + summary: Retrieve xpay payment authorization + description: Retrieve xpay payment authorization given paymentAuthorizationId + tags: + - XPay + operationId: get-auth-payment-xpay + parameters: + - in: path required: true + name: paymentAuthorizationId + description: Id of the payment authorization + example: "41bc2409-5926-4aa9-afcc-797c7054e467" + schema: + type: string + - in: header + name: MDC-Fields + description: MDC information + example: 97g10t83x7bb0437bbc50sdf58e970gt + schema: + type: string + required: false responses: "200": description: OK - content: - '*/*': + content: + application/json: schema: - $ref: '#/components/schemas/XPayAuthResponseEntity' - "400": - description: Bad request - missing mandatory parameters + $ref: '#/components/schemas/XPayPaymentAuthorization' + "404": + description: payment authorization not found content: application/json: schema: - $ref: '#/components/schemas/XPayAuthResponseEntity400' - "401": - description: transactionId already processed + $ref: '#/components/schemas/XPayPaymentAuthorizationError' + "500": + description: Internal server error content: application/json: schema: - $ref: '#/components/schemas/XPayAuthResponseEntity401' - /request-payments/xpay/{requestId}/resume: - get: - summary: payment request to xPay + $ref: '#/components/schemas/XPayPaymentAuthorizationError' + delete: tags: - XPay - operationId: resumeXPayPayment + summary: refund xpay requests + description: Refund xpay payment authorization given paymentAuthorizationId + operationId: refund-auth-payment-xpay parameters: - - name: requestId - in: path - required: true + - in: path + name: paymentAuthorizationId schema: type: string - - name: esito + format: uuid + required: true + description: PGS-generated GUID of the request to retrieve + example: 77e1c83b-7bb0-437b-bc50-a7a58e5660ac + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/XPayPaymentAuthorization' + "404": + description: payment authorization not found + content: + application/json: + schema: + $ref: '#/components/schemas/XPayPaymentAuthorizationError' + "500": + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/XPayPaymentAuthorizationError' + /payment-authorizations/xpay/{paymentAuthorizationId}/resume: + get: + summary: Resume of a xpay payment authorization + description: Resume of a xpay payment authorization and redirect on touchpoint client frontend + tags: + - XPay + operationId: resume-auth-payment-xpay + parameters: + - name: paymentAuthorizationId + in: path + required: true + schema: + type: string + - name: esito in: query required: false schema: @@ -485,96 +582,19 @@ paths: type: string responses: "302": - description: OK-FOUND - "401": - description: Unauthorized - content: - application/json: + description: Resume completed + headers: + location: + description: CheckOut Url schema: type: string - example: "Unauthorized - transaction already processed" - "400": - description: Not Found - content: - application/json: - schema: - type: string - example: "Bad Request - mandatory parameters missing" - "404": - description: TimeOut - content: - application/json: - schema: - type: string - example: "RequestId not Found" - /request-payments/xpay/{requestId}: - get: - summary: retrieve XPay payment request - tags: - - XPay - operationId: auth-response-xpay - parameters: - - in: path - required: true - name: requestId - description: Id of the request - example: "41bc2409-5926-4aa9-afcc-797c7054e467" - schema: - type: string - - in: header - name: MDC-Fields - description: MDC information - example: 97g10t83x7bb0437bbc50sdf58e970gt - schema: - type: string - required: false - responses: - "200": - description: OK - content: - '*/*': - schema: - $ref: '#/components/schemas/XPayPollingResponseEntity' - "404": - description: Not Found - content: - application/json: - schema: - $ref: '#/components/schemas/XPayPollingResponseEntity404' - /request-payments/xpay{requestId}: - delete: - tags: - - XPay - summary: refund xpay requests - operationId: refund-xpay-request - parameters: - - in: path - name: requestId - schema: - type: string - format: uuid - required: true - description: PGS-generated GUID of the request to retrieve - example: 77e1c83b-7bb0-437b-bc50-a7a58e5660ac - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/XPayRefundResponse200' - "404": - description: Request doesn't exist - content: - application/json: - schema: - $ref: '#/components/schemas/XPayRefundResponse404' + format: uri "500": - description: Generic Error + description: Internal server error content: application/json: schema: - $ref: '#/components/schemas/XPayRefundResponse500' + $ref: '#/components/schemas/XPayPaymentAuthorizationError' /request-payments/vpos: post: summary: payment authorization request to Vpos @@ -952,7 +972,7 @@ components: - paymentId - refundOutcome - error - XPayAuthRequest: + XPayPaymentAuthorizationRequest: required: - cvv - pan @@ -982,98 +1002,45 @@ components: type: string description: Expiration date of the card, yyyyMM format example: 203012 - XPayPaymentRequest: - required: - - esito - type: object - properties: - esito: - type: string - enum: [ OK, KO ] - description: outhcome from xpay - idOperazione: - type: string - description: idOperazione from xpay - example: "123456" - xpayNonce: - type: string - description: nonce from xpay - example: "nonce" - timestamp: - type: string - description: timestamp in ms - example: 16589654852 - mac: - type: string - description: mac from xpay - example: bd2dd7a959e4816b1ba9e767cf2a5287192c8be7 - codice: - type: string - description: error code from xpay - example: 1 - messaggio: - type: string - description: error message from xpay - example: error message from xpay - XPayAuthResponseEntity: + XPayPaymentAuthorizationRequestAccepted: type: object required: - requestId - urlRedirect - - status - - timeStamp properties: - requestId: + paymentAuthorizationId: type: string - description: payment request Id + description: payment authorization Id urlRedirect: type: string - description: redirect URL generated by PGS logic + description: redirect URL generated by PGS logic to complete authorization frontend flow example: "urlRedirect.com" - status: - type: string - enum: [CREATED, AUTHORIZED, DENIED, CANCELLED] - description: status - example: CREATED - timeStamp: - type: string - description: timeStamp - example: 1667484646944 - XPayAuthResponseEntity400: - type: object - required: - - error - properties: - error: - type: string - description: error description - example: Bad Request - mandatory parameters missing - XPayAuthResponseEntity401: + XPayPaymentAuthorizationError: type: object required: - - error + - errorDetail properties: - error: + errorDetail: type: string - description: error description - example: Transaction already processed - XPayPollingResponseEntity: + description: error detail + example: Bad Request - mandatory parameters missing + XPayPaymentAuthorization: type: object required: - status - - requestId + - paymentAuthorizationId properties: html: type: string description: HTML received in response from XPay example: "\u003chtml\u003e\n\u003chead\u003e\n\u003ctitle\u003e\nGestione Pagamento Fraud detection\u003c/title\u003e\n\u003cscript type\u003d\"text/javascript\" language\u003d\"javascript\"\u003e\nfunction moveWindow() {\n document.tdsFraudForm.submit();\n}\n\u003c/script\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n\u003cform name\u003d\"tdsFraudForm\" action\u003d\"https://coll-ecommerce.nexi.it/ecomm/ecomm/TdsMerchantServlet\" method\u003d\"POST\"\u003e\n\u003cinput type\u003d\"hidden\" name\u003d\"action\" value\u003d\"fraud\"\u003e\n\u003cinput type\u003d\"hidden\" name\u003d\"merchantId\" value\u003d\"31320986\"\u003e\n\u003cinput type\u003d\"hidden\" name\u003d\"description\" value\u003d\"7090069933_1606392234626\"\u003e\n\u003cinput type\u003d\"hidden\" name\u003d\"gdiUrl\" value\u003d\"\"\u003e\n\u003cinput type\u003d\"hidden\" name\u003d\"gdiNotify\" value\u003d\"\"\u003e\n\u003c/form\u003e\n\u003cscript type\u003d\"text/javascript\"\u003e\n moveWindow();\n\u003c/script\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n" - requestId: + paymentAuthorizationId: type: string - description: payment request Id + description: payment authorization Id example: affd8e24-f99a-406f-9ded-67a4a20c097f status: type: string - enum: [CREATED, AUTHORIZED, DENIED, CANCELLED] + enum: [CREATED, AUTHORIZED, DENIED, REFUNDED] description: status example: CREATED authOutcome: @@ -1088,65 +1055,6 @@ components: type: string description: redirection URL after a response from XPay has been received example: "http://localhost:8080/payment-gateway/request-payments/xpay/2d75ebf8-c789-46a9-9a22-edf1976a8917" - XPayPollingResponseEntity404: - type: object - required: - - error - properties: - error: - type: object - required: - - code - - message - properties: - code: - type: number - format: integer - description: error code - example: 404 - message: - type: string - description: error message - example: "RequestId not found" - XPayRefundResponse200: - type: object - properties: - requestId: - type: string - example: "77e1c83b-7bb0-437b-bc50-a7a58e5660ac" - refundOutcome: - type: string - enum: [OK, KO] - example: "OK" - error: - type: string - required: - - transactionId - - refundOutcome - XPayRefundResponse404: - type: object - properties: - requestId: - type: string - example: "77e1c83b-7bb0-437b-bc50-a7a58e5660ac" - error: - type: string - example: "RequestId not Found" - required: - - transactionId - - error - XPayRefundResponse500: - type: object - properties: - requestId: - type: string - example: "77e1c83b-7bb0-437b-bc50-a7a58e5660ac" - error: - type: string - example: "Error while requesting refund for requestId: xxx" - required: - - transactionId - - error BPayInfoResponse: type: object properties: From 0855d976af4a9b6f4a56537bb7e9d5b0a4a71546 Mon Sep 17 00:00:00 2001 From: Simone Infante Date: Wed, 15 Mar 2023 09:07:05 +0100 Subject: [PATCH 2/6] feat: add description in externalDocs --- api-specs/api_spec_PGS.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/api-specs/api_spec_PGS.yaml b/api-specs/api_spec_PGS.yaml index 93b46312..3dae6bb1 100644 --- a/api-specs/api_spec_PGS.yaml +++ b/api-specs/api_spec_PGS.yaml @@ -13,7 +13,8 @@ info:
  • postepay
    • externalDocs: - url: https://pagopa.atlassian.net/wiki/spaces/TKM/overview + url: https://pagopa.atlassian.net/wiki/spaces/TKM/overview + description: Design review servers: - url: http://localhost:8080/ description: Generated server url From 2f7d6bab57c2b2f87c9afd6e1c5c9bcb72e5b7a3 Mon Sep 17 00:00:00 2001 From: Simone Infante Date: Tue, 21 Mar 2023 08:40:34 +0100 Subject: [PATCH 3/6] feat: update vpos specs --- api-specs/api_spec_PGS.yaml | 45 +++++++++++++++++++------------------ 1 file changed, 23 insertions(+), 22 deletions(-) diff --git a/api-specs/api_spec_PGS.yaml b/api-specs/api_spec_PGS.yaml index 3dae6bb1..17da29e9 100644 --- a/api-specs/api_spec_PGS.yaml +++ b/api-specs/api_spec_PGS.yaml @@ -408,13 +408,13 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /payment-authorizations/xpay: + /xpay/authorizations: post: - summary: New payment authorization request to xpay - description: Creation of a new payment authorization request to *xpay* and return url on which to complete the frontend authorization flow + summary: New authorization with xpay + description: Creation of a new authorization with *xpay* and return url on which to complete the frontend authorization 3DS2 flow tags: - XPay - operationId: new-auth-payment-request-xpay + operationId: new-authorization-xpay parameters: - in: header name: x-client-id @@ -463,7 +463,7 @@ paths: application/json: schema: $ref: '#/components/schemas/XPayPaymentAuthorizationError' - /payment-authorizations/xpay/{paymentAuthorizationId}: + /xpay/authorizations/{paymentAuthorizationId}: get: summary: Retrieve xpay payment authorization description: Retrieve xpay payment authorization given paymentAuthorizationId @@ -538,7 +538,7 @@ paths: application/json: schema: $ref: '#/components/schemas/XPayPaymentAuthorizationError' - /payment-authorizations/xpay/{paymentAuthorizationId}/resume: + /xpay/authorizations/{paymentAuthorizationId}/resume: get: summary: Resume of a xpay payment authorization description: Resume of a xpay payment authorization and redirect on touchpoint client frontend @@ -585,8 +585,8 @@ paths: "302": description: Resume completed headers: - location: - description: CheckOut Url + Location: + description: client Url schema: type: string format: uri @@ -596,9 +596,10 @@ paths: application/json: schema: $ref: '#/components/schemas/XPayPaymentAuthorizationError' - /request-payments/vpos: + /vpos/authorizations: post: - summary: payment authorization request to Vpos + summary: New authorization with Vpos + description: Creation of a new authorization with vpos and return url on which to complete the frontend authorization 3DS2 flow tags: - Vpos operationId: step0-creditCard @@ -624,7 +625,7 @@ paths: $ref: '#/components/schemas/CreditCardAuthRequest' required: true responses: - "200": + "202": description: OK content: application/json: @@ -648,15 +649,15 @@ paths: application/json: schema: $ref: '#/components/schemas/CreditCardAuthResponseGenericError' - /request-payments/vpos/{requestId}: + /vpos/authorizations/{paymentAuthorizationId}: get: - summary: retrieve vpos payment request + summary: retrieve vpos payment authorization tags: - Vpos parameters: - in: path required: true - name: requestId + name: paymentAuthorizationId description: Id of the request example: "41bc2409-5926-4aa9-afcc-797c7054e467" schema: @@ -691,7 +692,7 @@ paths: parameters: - in: path required: true - name: requestId + name: paymentAuthorizationId description: Id of the request example: "41bc2409-5926-4aa9-afcc-797c7054e467" schema: @@ -715,15 +716,15 @@ paths: 'application/json': schema: $ref: '#/components/schemas/VposDeleteResponse500' - /request-payments/vpos/{requestId}/resume/method: + /vpos/authorizations/{paymentAuthorizationId}/resume/method: post: - summary: resume vpos payment request + summary: resume vpos payment authorization tags: - Vpos parameters: - in: path required: true - name: requestId + name: paymentAuthorizationId description: Id of the request example: "41bc2409-5926-4aa9-afcc-797c7054e467" schema: @@ -749,7 +750,7 @@ paths: 'application/json': schema: $ref: '#/components/schemas/VposResumeResponse' - /request-payments/vpos/{requestId}/resume/challenge: + /vpos/authorizations/{paymentAuthorizationId}/resume/challenge: post: summary: resume vpos payment request tags: @@ -757,7 +758,7 @@ paths: parameters: - in: path required: true - name: requestId + name: paymentAuthorizationId description: Id of the request example: "41bc2409-5926-4aa9-afcc-797c7054e467" schema: @@ -772,7 +773,7 @@ paths: responses: "302": description: "FOUND, Redirect to url" - /request-payments/vpos/{requestId}/method/notifications: + /vpos/authorizations/{paymentAuthorizationId}/method/notifications: post: summary: created webView to execute 'method' tags: @@ -780,7 +781,7 @@ paths: parameters: - in: path required: true - name: requestId + name: paymentAuthorizationId description: Id of the request example: "41bc2409-5926-4aa9-afcc-797c7054e467" schema: From 64aef81512a8216bfc3e87d82509f289fb2b02ed Mon Sep 17 00:00:00 2001 From: Simone Infante Date: Mon, 3 Apr 2023 18:09:23 +0200 Subject: [PATCH 4/6] feat: update openapi --- api-specs/api_spec_PGS.yaml | 103 ++++++++++++++++++++++++++++++++---- 1 file changed, 94 insertions(+), 9 deletions(-) diff --git a/api-specs/api_spec_PGS.yaml b/api-specs/api_spec_PGS.yaml index 17da29e9..7ee93e10 100644 --- a/api-specs/api_spec_PGS.yaml +++ b/api-specs/api_spec_PGS.yaml @@ -1045,14 +1045,8 @@ components: enum: [CREATED, AUTHORIZED, DENIED, REFUNDED] description: status example: CREATED - authOutcome: - type: string - description: authorization outcome received from XPay - example: OK - authCode: - type: string - description: authorization code received from XPay - example: 123 + outcomeXpayGateway: + $ref: '#/components/schemas/OutcomeXpayGateway' redirectUrl: type: string description: redirection URL after a response from XPay has been received @@ -1229,6 +1223,8 @@ components: creq: type: string format: base64 + outcomeVposGateway: + $ref: '#/components/schemas/OutcomeVposGateway' required: - status - requestId @@ -1311,4 +1307,93 @@ components: type: string enum: [CREATED, AUTHORIZED, DENIED, CANCELLED] error: - type: string \ No newline at end of file + type: string + OutcomeVposGateway: + type: object + properties: + outcome: + type: string + enum: + - OK + - KO + rrn: + type: string + authorizationCode: + type: string + errorCode: + type: string + description: error code received from Vpos - https://github.com/pagopa/pagopa-wisp2.0-pp-server/blob/ff0e8e3354fc11d296fe5547b9b00941ead64e96/pp-server/pp-dto/src/main/java/com/pagopa/utils/VposResultCodeEnum.java + enum: + - '00' + - '01' + - '02' + - '03' + - '04' + - '05' + - '06' + - '07' + - '08' + - '09' + - '10' + - '11' + - '12' + - '13' + - '16' + - '17' + - '20' + - '21' + - '25' + - '26' + - '35' + - '37' + - '38' + - '40' + - '41' + - '50' + - '51' + - '98' + - '99' + required: + - outcome + OutcomeXpayGateway: + type: object + properties: + outcome: + type: string + enum: + - OK + - KO + authorizationCode: + type: string + errorCode: + type: number + description: error code received from XPay - https://ecommerce.nexi.it/specifiche-tecniche/tabelleecodifiche/codicierroreapirestful.html + enum: + - 1 + - 2 + - 3 + - 4 + - 5 + - 7 + - 8 + - 9 + - 12 + - 13 + - 14 + - 15 + - 16 + - 17 + - 18 + - 19 + - 20 + - 21 + - 22 + - 50 + - 96 + - 97 + - 98 + - 99 + - 100 + required: + - outcome + \ No newline at end of file From 4fe5468d166167ee133161ff255a571c620f4aa0 Mon Sep 17 00:00:00 2001 From: Simone Infante Date: Tue, 18 Apr 2023 18:58:33 +0200 Subject: [PATCH 5/6] fix: merge specs --- api-specs/api_spec_PGS.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-specs/api_spec_PGS.yaml b/api-specs/api_spec_PGS.yaml index c28d5b37..e7c1381e 100644 --- a/api-specs/api_spec_PGS.yaml +++ b/api-specs/api_spec_PGS.yaml @@ -3,7 +3,7 @@ info: title: Openapi for pagopa-payment-transactions-gateway (PGS) version: 0.0.1 description: | - Openapi definition for the API exposed by the *pagopa-payment-transactions-gateway* (**PGS**) and + Openapi definitÃ¥ion for the API exposed by the *pagopa-payment-transactions-gateway* (**PGS**) and consumed by the pagoPA touchpoints (for example *pagopPA - checkout* via *pagoPA - ecommerce*) to authorize payments via the following payment gateway:
      From 38d7dd1c665d9fd05c37ace16e8f5a1cc292510a Mon Sep 17 00:00:00 2001 From: Simone Infante Date: Wed, 19 Apr 2023 09:41:29 +0200 Subject: [PATCH 6/6] fix: int --- api-specs/api_spec_PGS.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-specs/api_spec_PGS.yaml b/api-specs/api_spec_PGS.yaml index e7c1381e..0f0f5f33 100644 --- a/api-specs/api_spec_PGS.yaml +++ b/api-specs/api_spec_PGS.yaml @@ -1006,7 +1006,7 @@ components: - requestId - urlRedirect - timeStamp - properties: + properties: paymentAuthorizationId: type: string description: payment authorization Id