Transaction Service - Core transaccional

Estas APIs permiten afectar el saldo del cliente.

1 API Transfer
- 1.1 Timeouts
- 1.2 Catálogo de errores
- 1.3 Parámetros de entrada
- 1.4 Ejemplo peticiones
  - 1.4.1 Petición
  - 1.4.2 Respuesta de petición exitosa
  - 1.4.3 Respuesta de petición no exitosa
2 API REVERSO
- 2.1 Catálogo de errores
- 2.2 Parámetros de entrada
- 2.3 Ejemplo peticiones
  - 2.3.1 Petición
  - 2.3.2 Respuesta de petición exitosa
  - 2.3.3 Respuesta de petición no exitosa

API Transfer

Esta API permite ejecutar una transacción de débito (retiro) o crédito (abono) sobre el saldo del cliente.

Esta API se encarga de validar si el cliente está autorizado (no bloqueado) para ejecutar la transacción y así como también valida que el cliente tenga saldo suficiente (ver catálogo de errores). El API permite ejecutar en una sola llamada una transacción y si se desea, también puede ejecutar de forma atómica la transacción de comisión.

Timeouts

El API contestará siempre en menos de 10 segundos, si la ejecución demora más de 10 segundos el API devuelve un error HTTP 503 Service unavailable con un error code de respuesta TIMEOUT_HANDLED_ERROR . Cuando se reciba este error, se debe asumir que la transacción fue fallida y el saldo NO fue afectado, es decir, es seguro reintentar. El core ya se encarga de reversar la transacción internamente si es necesario para dejar el saldo inafectado. Si se va a reintentar se recomienda esperar unos 60 segundos para asegurar que el core tenga tiempo de reversar si es necesario.

Catálogo de errores

Respuesta HTTP	Excepción Java en cliente	Error Code	Descripción

Respuesta HTTP	Excepción Java en cliente	Error Code	Descripción
400	`BadRequestException`	`TRANSACTION_TYPE_WITHOUT_ACTION_CODE`	La transacción a ejecutar debe tener un action code válido
400	`BadRequestException`	`EXECUTE_COMMISSION_TRANSACTION_FLAG_IS_REQUIRED`	Si la transacción a ejecutar tiene configurada comisión de transacción, se debe informar esta propiedad
400	`BadRequestException`	`POSITIVE_COMMISSION_IS_REQUIRED`	Si la transacción a ejecutar tiene configurada comisión de transacción y si se informa que la propiedad `executeCommissionTransaction` en true, la propiedad de comisión debe tener valor positivo
400	`BadRequestException`	`TRANSACTION_TYPE_WITHOUT_COMMISSION`	Si la transacción no esta configurada para ejecutar transacción de comisión, no se debe informar la propiedad `executeCommissionTransaction` o debe ester en false
400	`BadRequestException`	`SOURCE_USER_ID_IS_REQUIRED`	La propiedad `sourceUserId` es requerida
400	`BadRequestException`	`SOURCE_TRANSACTION_TYPE_IS_REQUIRED`	La propiedad `sourceTransactionType` es requerida
400	`BadRequestException`	`POSITIVE_AMOUNT_IS_REQUIRED`	El monto es requerido y debe tener valor positivo En caso de informar la propiedad tax esta debe tener valor positivo
400	`BadRequestException`	`TRANSACTION_AMOUNT_AND_COMMISSION_IS_ZERO`	Transacciones a ejecutar con monto + comisión = 0
400	`BadRequestException`	`BAD_REQUEST`	La descripción debe ser de máximo 300 caracteres Cuando el transactionType no existe en SPIN
400	`BadRequestException`	`DUPLICATED_CUSTOM_TRANSACTION_ID`	Cuando se informa la propiedad `customTransactionId` y ya existe una fiserv transacción con este valor
400	`BadRequestException`	`FIELD_LENGTH_VALIDATION_FAILED`	Uno o mas campos enviados a fiserv tienen longitud inválida
401	`UnauthorizedException`	`FISERV_FALCON_REJECTED`	Transacción rechazada por FALCON
409	`ConflictException`	`N1_N2_DAILY_LIMIT_REACHED`	Limite diario de monto alcanzado en cuentas N1 / N2
409	`ConflictException`	`N1_N2_MONTHLY_LIMIT_REACHED`	Limite mensual de monto alcanzado en cuentas N1 / N2
409	`ConflictException`	`BALANCE_LIMIT_REACHED`	Limite de saldo alcanzado
500	`InternalServerErrorException`	`FISERV_FALCON_ERROR`	Error ocurrido en FALCON
503	`ServiceUnavailableException`	`TIMEOUT_HANDLED_ERROR`	La ejecución de la transacción alcanzo el tiempo limite de 10 segundos. En caso de ser exitosa la trx se intentará reversar, de igual forma si existe un fallo y aplica reverso, este se intentará.
503	`ServiceUnavailableException`	`FISERV_CALL_FAILED_NO_CONNECT`	Si el API de fiserv no esta disponible
503	`ServiceUnavailableException`	`USER_NOT_FOUND`	Cuando el userId informado no existe en SPIN
503	`ServiceUnavailableException`	`USER_BLACKLISTED`	Se aplico un código de bloqueo a la cuenta del cliente SPIN que le restringe poder ejecutar la operación.

Parámetros de entrada

Nombre	Tipo de dato	Descripción	Obligatorio

Nombre	Tipo de dato	Descripción	Obligatorio
userId	String	Id de Spin del cliente que se desea afectar	Sí
transactionType	String	Tipo de transacción	Sí
amount	Number	monto de la transacción. Se informa en centavos	Sí
commission	Number	Monto de la comisión. Se informa en centavos	No
tax	Number	Monto del impuesto. Se informa en centavos	No
queueTransaction	boolean	Bandera para ejecutar la transacción de forma asíncrona	No
queueTransactionRetryPolicy	String	Define la forma de ejecución de la transacción. Solo aplica para ejecución asíncrona: `UNTIL_COMPLETE_AMOUNT_IS_FULLFILLED - Intenta ejecutar idefinidamente hasta completar el monto total de la transacción` `SYSTEM_DEFAULT` - Intentos limitados. Dependiendo la configuración de intentos	No
executeCommissionTransaction	boolean	Bandera que habilita o no la ejecución de la comisión. Se debe informar si la transacción soporta comisión	No
transactionData	Object	Propiedades que se mappean en la transacción (FiservTransaction)	No
relatedTransactionId	String	Id de mongo de la transacción con la que se desea vincular la FiservTransaction, quedará persistida en el campo FiservTransaction.relatedTransactionId.	No
description	String	Descripción. Máximo 300 caracteres	No
metadata	Map	propiedades con información adicional sobre la ejecución de las transacciones, para agregar un nuevo metadata es necesario solicitarlo al equipo de desarrollo para incluirlo	No
falconData	Object	Estas propiedades se envían para la validación en Falcon. No son guardadas en la colección FiservTransaction	No
validateAccountBlocks	boolean	Permite habilitar la validación de bloqueos de cuenta, default value true	No
validateAccountLevelLimits	boolean	Permite habilitar la validación de los límites de cuenta, default value true	No

Ejemplo peticiones

Petición

{
    "userId": "c25549d8-85f5-4c4d-9434-XXXXX",
    "transactionType": "CASH_OUT_REMITTANCE",
    "amount": 5000,
    "commission" : 1000,
    "description" : "CASH_OUT_REMITTANCE",
    "executeCommissionTransaction": true
}

Respuesta de petición exitosa

{
    "requestedTransaction": {
        "id": "636d39d12986e05c2e9b5908",
        "userId": "c25549d8-85f5-4c4d-9434-XXXXX",
        "customerNumber": "0995000000000037591",
        "accountNumber": "9500501939559287271",
        "qualification": 2,
        "createdAt": "2022-11-10T17:50:09.149Z",
        "transactionType": "CASH_OUT_REMITTANCE",
        "amount": 5000,
        "commission": 1000,
        "tax": 138,
        "taxPercentage": 0.16,
        "description": "CASH_OUT_REMITTANCE",
        "authCode": "R1XmCe",
        "commissionTransactionId": "636d39d12986e05c2e9b5909",
        "actionCode": "8041",
        "userMetadata": {
            "deviceId": "testDevDeviceId",
            "longitude": 80.56565656565657,
            "latitude": -23.565656565656564,
            "ipAddress": "198.162.123.145"
        },
        "initialBalance": 1772345,
        "finalBalance": 1767345,
        "traceId": "18e1d42f25f81ee0"
    },
    "commissionTransaction": {
        "id": "636d39d12986e05c2e9b5909",
        "userId": "c25549d8-85f5-4c4d-9434-XXXXX",
        "relatedTransactionId": "636d39d12986e05c2e9b5908",
        "customerNumber": "0995000000000037591",
        "accountNumber": "9500501939559287271",
        "qualification": 2,
        "createdAt": "2022-11-10T17:50:09.236Z",
        "transactionType": "CASH_OUT_REMITTANCE_COMMISSION",
        "amount": 1000,
        "commission": 0,
        "tax": 138,
        "taxPercentage": 0.16,
        "description": "CASH_OUT_REMITTANCE",
        "authCode": "vGlVE1",
        "actionCode": "8042",
        "initialBalance": 1767345,
        "finalBalance": 1766345,
        "traceId": "18e1d42f25f81ee0"
    }
}

Respuesta de petición no exitosa

Debido a un input de request inválido que es requerido

{
    "message": "Execute commission transaction flag is required",
    "code": "EXECUTE_COMMISSION_TRANSACTION_FLAG_IS_REQUIRED",
    "description": "Execute commission transaction flag is required",
    "args": [],
    "status": "400 BAD_REQUEST"
}

Por causa de fiserv time out

Cuando un API que consume el servicio transaction-service no esta disponible:

API REVERSO

Esta API permite ejecutar un reverso de una transacción ejecutada exitosamente ya sea de débito (retiro) o crédito (abono) sobre el saldo del cliente.

Esta API se encarga de validar si el cliente está autorizado (no bloqueado) para ejecutar la transacción y así como también valida que el cliente tenga saldo suficiente (ver catálogo de errores). Adicionalmente permite validar si una transacción ya fue reversada o si no es reversible.

El API permite ejecutar en una sola llamada el reverso de una transacción incluyendo su comisión y si se desea, también puede ejecutar de forma atómica la transacción de comisión.

Las transacciones P2P no pueden ser reversadas actualmente

Catálogo de errores

Respuesta HTTP	Excepción Java en cliente	Error Code	Descripción

Respuesta HTTP	Excepción Java en cliente	Error Code	Descripción
400	`BadRequestException`	`BAD_REQUEST`	La propiedad `reverseCommissionTransaction` es requerida
400	`BadRequestException`	`TRANSACTION_DOES_NOT_EXIST`	El id de la transacción a reversar no existe
400	`BadRequestException`	`COMMISSION_TRANSACTION_DOES_NOT_EXIST`	Si se especifica `reverseCommissionTransaction` = true, y no existe la transacción de comisión
412	`PreconditionFailedException`	`TRANSACTION_IS_NOT_REVERSABLE`	Transacción que se intenta reversar no es reversable
412	`PreconditionFailedException`	`TRANSACTION_ALREADY_REVERSED`	La transacción ya ha sido reversada
401	`UnauthorizedException`	`FISERV_FALCON_REJECTED`	Transacción rechazada por FALCON
409	`ConflictException`	`N1_N2_DAILY_LIMIT_REACHED`	Limite diario de monto alcanzado en cuentas N1 / N2
409	`ConflictException`	`N1_N2_MONTHLY_LIMIT_REACHED`	Limite mensual de monto alcanzado en cuentas N1 / N2
409	`ConflictException`	`BALANCE_LIMIT_REACHED`	Limite de saldo alcanzado
500	`InternalServerErrorException`	`FISERV_FALCON_ERROR`	Error ocurrido en FALCON
503	`ServiceUnavailableException`	`FISERV_TRANSFER_EXECUTION_TIMED_OUT`	Cuando se genera un fiserv time out y el api de Fiserv no contesta en tiempo válido. NOTA: La ejecución de la transacción en fiserv podría ser exitosa aunque no se refleje en el sistema de SPIN en la colección fiservTransaction en BD
503	`ServiceUnavailableException`	`FISERV_CALL_FAILED_NO_CONNECT`	Si el API de fiserv no esta disponible
503	`ServiceUnavailableException`	`USER_BLACKLISTED`	Se aplico un código de bloqueo a la cuenta del cliente SPIN

Parámetros de entrada

Nombre	Tipo de dato	Descripción	Obligatorio

Nombre	Tipo de dato	Descripción	Obligatorio
`reverseCommissionTransaction`	boolean	Bandera que permite habilitar la ejecución de la transacción de reverso	Sí
`description`	String	Descripción de la transacción de reverso	No
`postExecutionEventData`	Object	Evento que se ejecuta posterior a ejecutar la transacción de forma exitosa	No
`falconData`	Object	Estas propiedades se envían para la validación en Falcon. No son guardadas en la colección FiservTransaction	No
`validateAccountBlocks`	boolean	Permite habilitar la validación de bloqueos de cuenta, default value true	No
`metadata`	Map	propiedades con información adicional sobre la ejecución de las transacciones, para agregar un nuevo metadata es necesario solicitarlo al equipo de desarrollo para incluirlo	No
`authorizationCode`	String	Authorization Code, solo en caso de reversar transacciones Balance freeze, debe coincidir con el de la transacción ejecutada exitosamente.	No

Ejemplo peticiones

POST /fiserv-transactions/{{fiservTransactionId}}/reversal'

fiservTransactionId - id de la transacción a reversar

Petición

Respuesta de petición exitosa

Respuesta de petición no exitosa

Cuando una transacción no es reversable

Cuando el id de la transacción a reversar no existe