Merge pull request #49 from placetopay-org/feature/reverse-doc

Feature/reverse doc

src/assets/apis/checkout/en.yaml

@@ -840,7 +840,7 @@ paths:
                 - auth
   /api/reverse:
     post:
-      summary: Reversar pago (ReversePayment)
+      summary: Reembolsar pago (ReversePayment)
       operationId: post-api-reverse
       requestBody:
         content:
@@ -970,7 +970,7 @@ paths:
                     status:
                       status: FAILED
                       reason: BR
-                      message: La transacción ya ha sido reversada
+                      message: La transacción ya ha sido reembolsada
                       date: '2021-12-07T16:03:41-05:00'
   /api/notify:
     post:
@@ -990,7 +990,7 @@ paths:
                     - number
                     - integer
                   description: |
-                    Referencia interna de la transacción a reversar que se encuentra en el listado de transacciones del getRequestInformation (payment).
+                    Referencia interna de la transacción a reembolsar que se encuentra en el listado de transacciones del getRequestInformation (payment).
                 reference:
                   type: string
                   description: Referencia del pago

src/assets/apis/checkout/es.yaml

@@ -840,7 +840,7 @@ paths:
                 - auth
   /api/reverse:
     post:
-      summary: Reversar pago (ReversePayment)
+      summary: Reembolsar pago (ReversePayment)
       operationId: post-api-reverse
       requestBody:
         content:
@@ -856,7 +856,7 @@ paths:
                 internalReference:
                   $ref: '#/components/schemas/InternalReference'
                 amount:
-                  description: 'Información del monto a cobrar. Esta propiedad se envía cuando se desea realizar un reverso con un valor menor al monto total de la transacción.'
+                  description: 'Información del monto a cobrar. Esta propiedad se envía cuando se desea realizar un reembolso con un valor menor al monto total de la transacción.'
                   $ref: '#/components/schemas/Amount'
             examples:
               Ejemplo:
@@ -970,7 +970,7 @@ paths:
                     status:
                       status: FAILED
                       reason: BR
-                      message: La transacción ya ha sido reversada
+                      message: La transacción ya ha sido reembolsada
                       date: '2021-12-07T16:03:41-05:00'
   /api/notify:
     post:
@@ -990,7 +990,7 @@ paths:
                     - number
                     - integer
                   description: |
-                    Referencia interna de la transacción a reversar que se encuentra en el listado de transacciones del getRequestInformation (payment).
+                    Referencia interna de la transacción a reembolsar que se encuentra en el listado de transacciones del getRequestInformation (payment).
                 reference:
                   type: string
                   description: Referencia del pago
@@ -2358,7 +2358,7 @@ components:
           example: PS_VS
         refunded:
           type: boolean
-          description: Se utiliza para definir si la transacción ha sido reversada
+          description: Se utiliza para definir si la transacción ha sido reembolsada
           default: false
         authorization:
           type: string
@@ -2483,7 +2483,7 @@ components:
           $ref: '#/components/schemas/AmountConversion'
         refunded:
           type: boolean
-          description: Se utiliza para definir si la transacción ha sido reversada
+          description: Se utiliza para definir si la transacción ha sido reembolsada
           default: false
         paymentMethod:
           type: string
@@ -2958,7 +2958,7 @@ components:
           description: |
             Tipo de operación a realizar sobre la transacción
             
-            `reverse` para reversar una transacción.   
+            `reverse` para reembolsar una transacción.   
             `reauthorization` para modificar una transacción de checkin.   
             `checkout` para cerrar y cobrar una transacción de checkin.
           enum:

src/assets/apis/gateway/en.yaml

@@ -1270,7 +1270,7 @@ paths:
                 - "action"
                 - "internalReference"
             examples: 
-              Reverso: 
+              Reembolso: 
                 value: 
                   auth: 
                     login: "6dd490faf9cb87a9862245da41170ff2"

src/assets/apis/gateway/es.yaml

@@ -9,7 +9,7 @@ info:
 
 Para usar el servicio web, deberás tener un lenguaje de programación que pueda comunicarse con un servicio REST.
 
-El método de integración contempla las operaciones básicas para el procesamiento de tarjetas no presenciales, esto es tipos de crédito, intereses, generación de OTP, autorización, reverso.
+El método de integración contempla las operaciones básicas para el procesamiento de tarjetas no presenciales, esto es tipos de crédito, intereses, generación de OTP, autorización, reembolso.
 
 A continuación se describirán cada uno de los usos y los datos requeridos en la trama para cada uno de los casos.  La respuesta para cada operación está unificada en un solo tipo de trama resultante.
 
@@ -1233,7 +1233,7 @@ paths:
                       bin: "411076"
                       expiration: "1228"
                       installments: "1"
-      description: "Permite realizar un reverso, re-autorización, reembolso o cash out sobre una transacción existente"
+      description: "Permite realizar un reembolso, re-autorización o cash out sobre una transacción existente"
       tags: 
         - "Acciones sobre transacciones"
       requestBody: 
@@ -1268,7 +1268,7 @@ paths:
                 - "action"
                 - "internalReference"
             examples: 
-              Reverso: 
+              Reembolsos: 
                 value: 
                   auth: 
                     login: "6dd490faf9cb87a9862245da41170ff2"

src/constants/navigations.js

@@ -41,6 +41,7 @@ export const TAB_NAVIGATION = {
                 title: 'Prueba tu integración',
                 href: '/checkout/test-your-integration',
               },
+              { title: 'Reembolsos', href: '/checkout/refund'}
             ],
           },
         ],
@@ -111,6 +112,7 @@ export const TAB_NAVIGATION = {
                 title: 'Test your integration',
                 href: '/checkout/test-your-integration',
               },
+              { title: 'Refund', href: '/checkout/refund'},
             ],
           },
         ],

src/pages/checkout/api/changelog.mdx

@@ -58,7 +58,7 @@ Este archivo contiene las mejoras y actualizaciones que se hagan en Checkout API
 
 ### Nuevo:
 
-- Se agrega soporte de idioma para el endpoint Reversar pago `/api/reverse`.
+- Se agrega soporte de idioma para el endpoint reembolsar pago `/api/reverse`.
 
 ## `2.17.1` 2023-06-01
 

src/pages/checkout/api/reference/payment.mdx

@@ -9,12 +9,14 @@ export const apiRefs = ['/api/reverse','/api/transaction']
 Se identifica como pago, a una transacción realizada por el usuario dentro de una sesión de pago. {{ className: 'lead' }}
 
 ---
+# Reembolsos
+El endpoint de reembolsos permite revertir una transacción aprobada. Ver más en [Reembolsos](/checkout/refund)
 
-## Reversar pago {{ id: 'reverse-payment', tag: 'POST', label: '/api/reverse' }}
+## Reembolsar pago {{ id: 'refund-payment', tag: 'POST', label: '/api/reverse' }}
 
 <Row>
     <Col>
-        Permite revertir un pago aprobado con el código de referencia interna `internalReference`.
+        Permite reembolsar un pago aprobado con el código de referencia interna `internalReference`.
 
         <ApiReader
             path="/api/reverse"

src/pages/checkout/create-session.mdx

@@ -192,7 +192,7 @@ Para el envió de impuestos, es importante que se encuentre en la estructura de
 
 Una sesión de preautorización es una sesión en la cual el usuario completa el proceso y el monto solicitado es reservado en su tarjeta de crédito, luego de la reserva el monto puede ser modificado, confirmado o cancelado.
 
-Este flujo de trabajo es usado con el fin de reservar (CHECKIN) un monto de dinero en el tarjetahabiente para posteriormente hacer el débito del mismo, en este caso (CHECKOUT). Este monto en el transcurso del tiempo puede cambiar (REAUTHORIZATION) según las necesidades del comercio o cambios en los servicios elegidos por el tarjetahabiente. Por último, el reverso (REVERSE) es un tipo de transacción, el cual permite reversar un pago aprobado o debitado con el código de referencia interna.
+Este flujo de trabajo es usado con el fin de reservar (CHECKIN) un monto de dinero en el tarjetahabiente para posteriormente hacer el débito del mismo, en este caso (CHECKOUT). Este monto en el transcurso del tiempo puede cambiar (REAUTHORIZATION) según las necesidades del comercio o cambios en los servicios elegidos por el tarjetahabiente. Por último, el reembolso (REVERSE) es un tipo de transacción, el cual permite reembolsar un pago aprobado o debitado con el código de referencia interna.
 
 
 ```json {{ 'title': 'CreateSessionRequest - Preauthorization Payment' }}

src/pages/checkout/refund.mdx

@@ -0,0 +1,39 @@
+export const description = 
+    'Conoce el proceso de reembolsos de transacciones en Placetopay'
+
+# Reembolsos {{ id: 'refunds' }}
+
+Desde nuestro API puedes realizar el reembolso y cancelación de transacciones aprobadas.
+
+Para realizar un reembolso debes conocer la referencia interna de la transacción a reembolsar `payment.internalReference`. Este dato se puede obtener al [consultar una sessión](/checkout/api/reference/session#query-a-session).
+
+## ¿Cómo realizar un reembolso? {{ id: 'how-to-make-a-refund' }}
+
+Para realizar un reembolso se debe hacer una petición al endpoint [Reembolsar Transacción](/checkout/api/reference/payment#reverse-payment). Existen dos tipos de reembolsos *total* o *parcial*:
+
+### Reembolso total
+
+Se utiliza para reembolsar la totalidad del monto aprobado en la transacción.
+
+Si la transacción no ha sido conciliada en la red bancaria, el reembolso será tratado como una "cancelación" de la transacción.
+
+### Reembolso parcial
+
+Se utiliza para reembolsar una parte del monto aprobado en la transacción.
+
+Se debe enviar la propiedad `amount` en la petición, este dato debe corresponder al monto que se quiere reembolsar.
+
+Los reembolsos parciales se pueden realizar tantas veces como sea necesario hasta que se complete el monto total aprobado en la transacción. Una vez que una transacción se ha reembolsado por completo, no es posible realizar otro reembolso. 
+
+Si se realiza una petición de reembolso sobre una transacción completamente reembolsada, este método devolverá un error `status.message` `La transacción ya ha sido reembolsada`
+
+Si la transacción no ha sido conciliada en la red bancaria, no se pueden realizar reembolsos parciales, se debe reliazar un reembolso total.
+
+<Note>
+    La disponibilidad de reembolsos y reembolsos parciales puede variar según el medio de pago, país y/o proveedor usado.  
+    La fecha de conciliación de transacciones puede variar según el medio de pago, país y/o proveedor usado.
+</Note>
+
+## Verificar una transacción reembolsada {{ id: 'verify-a-refund' }}
+
+Para verificar que una transacción fue reembolsada total o parcialmente, se debe [consultar la sesión](/checkout/api-reference/session#query-a-session) de la transacción original donde encontraras en la respuesta la propiedad `payment.refunded` con valor `true`.

src/pages/en/checkout/api/changelog.mdx

@@ -58,7 +58,7 @@ This file contains the improvements and updates made to the Checkout API.
 
 ### Added:
 
-- Language support is added for the Reverse pay `/api/reverse` endpoint.
+- Language support is added for the refund payment `/api/reverse` endpoint.
 
 ## `2.17.1` 2023-06-01
 

src/pages/en/checkout/api/reference/payment.mdx

@@ -9,12 +9,15 @@ export const apiRefs = ['/api/reverse','/api/transaction']
 A transaction made by the user within a payment session is identified as payment.. {{ className: 'lead' }}
 
 ---
+# Refund
+The refund endpoint allows to refund an approved transaction. See more in [Refund](/en/checkout/refund)
 
-## Reverse payment {{ id: 'reverse-payment', tag: 'POST', label: '/api/reverse' }}
+
+## Refund payment {{ id: 'refund-payment', tag: 'POST', label: '/api/reverse' }}
 
 <Row>
     <Col>
-        Allows you to reverse an approved payment with the internal reference code `internalReference`.
+        Allows you to refund an approved payment with the internal reference code `internalReference`.
 
         <ApiReader
             path="/api/reverse"

src/pages/en/checkout/refund.mdx

@@ -0,0 +1,39 @@
+export const description = 
+    'Learn about the refund process for Placetopay transactions'
+
+# Refund {{ id: 'refunds' }}
+
+From our API, you can process refunds and cancellations of approved transactions.
+
+To process a refund, you need to know the internal reference of the transaction to be refunded, `payment.internalReference`. This information can be obtained by [Query a session](/en/checkout/api/reference/session#query-a-session).
+
+## How to make a refund? {{ id: 'how-to-make-a-refund' }}
+
+To process a refund, you need to make a request to the [Refund Transaction](/en/checkout/api/reference/payment#reverse-payment) endpoint. There are two types of refunds: *full* or *partial*:
+
+### Full Refund
+
+It is used to refund the entire approved amount of the transaction.
+
+If the transaction has not been settled in the bank network, the refund will be treated as a "cancellation" of the transaction.
+
+### Partial Refund
+
+It is used to refund a portion of the approved transaction amount.
+
+You must include the `amount` property in the request, corresponding to the amount you wish to refund.
+
+Partial refunds can be made as many times as necessary until the total approved amount of the transaction has been refunded. Once a transaction has been fully refunded, no further refunds can be processed.
+
+If a refund request is made for a transaction that has already been fully refunded, this method will return an error `status.message` `Transaction already refunded`.
+
+If the transaction has not been settled in the bank network, partial refunds cannot be made; a full refund must be processed instead.
+
+<Note>
+    The availability of refunds and partial refunds may vary depending on the payment method, country, and/or provider used.
+    The settlement date of transactions may vary depending on the payment method, country, and/or provider used.
+</Note>
+
+## Verify a refunded transaction {{ id: 'verify-a-refund' }}
+
+To verify whether a transaction has been fully or partially refunded, you need to [query the session](/en/checkout/api/reference/session#query-a-session) of the original transaction, where you will find the `payment.refunded` property with a value of `true` in the response.

src/pages/gateway/api/reference/transaction.mdx

@@ -130,7 +130,7 @@ export const apiRefs = ['/gateway/process', '/gateway/query', '/gateway/search',
 
 <Row>
     <Col>
-        Permite realizar un reverso, re-autorización, reembolso o cash out sobre una transacción existente
+        Permite realizar un reembolso, re-autorización o cash out sobre una transacción existente
 
         <ApiReader
             path="/gateway/transaction"

src/pages/gateway/testing-card.mdx

@@ -89,8 +89,8 @@ Para realizar un proceso exitoso usa 55555 como código postal
 ZIP Code | Comportamiento
 ---------|----------
 55555 | Retorna transacción aprobada con AVS exitoso (Y)
-44444 | Retorna transacción aprobada con AVS fallido (A) y reversa la transacción
-33333 | Retorna transacción aprobada con AVS fallido (A) rechaza el reverso, pero cuando se consulta el reverso fue exitoso.
+44444 | Retorna transacción aprobada con AVS fallido (A) y reembolsar la transacción
+33333 | Retorna transacción aprobada con AVS fallido (A) rechaza el reembolso, pero cuando se consulta el reembolso fue exitoso.
 
 ## OTP para casos de prueba
 

src/pages/gateway/transaction-flow.mdx

@@ -13,7 +13,7 @@ Se trata de un proceso para realizar la transacción que involucra el consumo de
     * Si la respuesta trae el parámetro `requireOtp` en true, se debe hacer el consumo al servicio de generación de OTP (otpGeneration) y obtener del usuario el código que será de 6 dígitos para enviarlo posteriormente en el servicio de validación de OTP `otp/validate` una vez se tenga una respuesta se enviará el resultado signature bajo el campo OTP de la solicitud de procesamiento.
 
 3. Una vez se haya obtenido el tipo de crédito (si lo hay), el código postal, el bolsillo, la cuenta verificada, el OTP (si se requiere) se consume el servicio de procesamiento de transacción `process` y se analiza la respuesta que puede ser final aprobada, declinada o fallida o que puede estar pendiente. En ambos casos se retornará un valor para internalReference que es muy importante almacenar porque le permitirá realizar consultas posteriores con el servicio `query`.
-    * Si se aprobó la transacción es importante almacenar también el número de autorización, le permitirá realizar reversos posteriormente si fuese necesario.
+    * Si se aprobó la transacción es importante almacenar también el número de autorización, le permitirá realizar reembolsos posteriormente si fuese necesario.
     * Generalmente las transacciones son culminadas en un tiempo corto (menos de 3 seg), pero si la transacción queda en estado pendiente es importante tener un cron job o similar que esté consultando cada 5 minutos por las transacciones pendientes hasta que se resuelvan.
 
 4. Generalmente las transacciones son culminadas en un tiempo corto (menos de 3 seg), pero se pueden dar los siguientes escenarios que deben controlarse

src/pages/gateway/transaction-types.mdx

@@ -77,7 +77,7 @@ En caso de que una transacción quede pendiente las demás transacciones pendien
 
 En caso de que una transacción falle o sea rechazada, las demás transacciones pendientes automáticamente también serán rechazadas, sin establecer contacto con la red. Si una transacción hija ya hubiese sido aprobada anteriormente, esta mantiene su estado y la transacción padre cambiará su estado a `APPROVED_PARTIAL`.
 
-Las transacciones pueden ser reversadas juntas o separadas. Si se envía una reversión a una transacción hija, solo esta será reversada. Si se envía una reversión a la transacción padre, todas las transacciones serán reversadas.
+Las transacciones pueden ser reversadas juntas o separadas. Si se envía una reversión a una transacción hija, solo esta será reembolsada. Si se envía una reversión a la transacción padre, todas las transacciones serán reversadas.
 
 ### Dispersión de aerolínea
 Cuando una dispersión es realizada a una aerolínea, esta será priorizada y procesada primero. Si 3DS o crédito están configurados, esta configuración será utilizada solamente en el procesamiento de la transacción de la aerolínea.