Estas APIs permiten afectar el saldo del cliente.

Table of Contents

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

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

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

1{ 2 "userId": "c25549d8-85f5-4c4d-9434-XXXXX", 3 "transactionType": "CASH_OUT_REMITTANCE", 4 "amount": 5000, 5 "commission" : 1000, 6 "description" : "CASH_OUT_REMITTANCE", 7 "executeCommissionTransaction": true 8}


Respuesta de petición exitosa

1{ 2 "requestedTransaction": { 3 "id": "636d39d12986e05c2e9b5908", 4 "userId": "c25549d8-85f5-4c4d-9434-XXXXX", 5 "customerNumber": "0995000000000037591", 6 "accountNumber": "9500501939559287271", 7 "qualification": 2, 8 "createdAt": "2022-11-10T17:50:09.149Z", 9 "transactionType": "CASH_OUT_REMITTANCE", 10 "amount": 5000, 11 "commission": 1000, 12 "tax": 138, 13 "taxPercentage": 0.16, 14 "description": "CASH_OUT_REMITTANCE", 15 "authCode": "R1XmCe", 16 "commissionTransactionId": "636d39d12986e05c2e9b5909", 17 "actionCode": "8041", 18 "userMetadata": { 19 "deviceId": "testDevDeviceId", 20 "longitude": 80.56565656565657, 21 "latitude": -23.565656565656564, 22 "ipAddress": "198.162.123.145" 23 }, 24 "initialBalance": 1772345, 25 "finalBalance": 1767345, 26 "traceId": "18e1d42f25f81ee0" 27 }, 28 "commissionTransaction": { 29 "id": "636d39d12986e05c2e9b5909", 30 "userId": "c25549d8-85f5-4c4d-9434-XXXXX", 31 "relatedTransactionId": "636d39d12986e05c2e9b5908", 32 "customerNumber": "0995000000000037591", 33 "accountNumber": "9500501939559287271", 34 "qualification": 2, 35 "createdAt": "2022-11-10T17:50:09.236Z", 36 "transactionType": "CASH_OUT_REMITTANCE_COMMISSION", 37 "amount": 1000, 38 "commission": 0, 39 "tax": 138, 40 "taxPercentage": 0.16, 41 "description": "CASH_OUT_REMITTANCE", 42 "authCode": "vGlVE1", 43 "actionCode": "8042", 44 "initialBalance": 1767345, 45 "finalBalance": 1766345, 46 "traceId": "18e1d42f25f81ee0" 47 } 48}

Respuesta de petición no exitosa

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

1{ 2 "message": "Execute commission transaction flag is required", 3 "code": "EXECUTE_COMMISSION_TRANSACTION_FLAG_IS_REQUIRED", 4 "description": "Execute commission transaction flag is required", 5 "args": [], 6 "status": "400 BAD_REQUEST" 7}

Por causa de fiserv time out

1{ 2 "message": "The fiserv transfer request timed out", 3 "code": "FISERV_TRANSFER_EXECUTION_TIMED_OUT", 4 "description": "The fiserv transfer request timed out", 5 "args": [ 6 { 7 "arg": "CODE", 8 "value": "tTvnFZ" 9 } 10 ], 11 "status": "503 SERVICE_UNAVAILABLE" 12}

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

1{ 2 "message": "Transaction Inquiry Service API is unavailable", 3 "code": "TRANSACTION_INQUIRY_SERVICE_API_UNAVAILABLE", 4 "description": "Transaction Inquiry Service API is unavailable", 5 "args": [], 6 "status": "503 SERVICE_UNAVAILABLE" 7}

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

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

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

1{ 2 "reverseCommissionTransaction" : true 3}

Respuesta de petición exitosa

1{ 2 "reversalTransaction": { 3 "id": "636d6cca2986e05c2e9b59bd", 4 "userId": "c25549d8-85f5-4c4d-9434-95842a16ee5a", 5 "relatedTransactionId": "636d6ca62986e05c2e9b59bc", 6 "customerNumber": "0995000000000037596", 7 "accountNumber": "9500501939559287274", 8 "qualification": 2, 9 "createdAt": "2022-11-10T21:27:38.011Z", 10 "transactionType": "CASH_OUT_REMITTANCE_REVERSAL", 11 "amount": 500, 12 "commission": 0, 13 "tax": 0, 14 "taxPercentage": 0.16, 15 "description": "El movimiento #636d6ca62986e05c2e9b59bc no pudo realizarse", 16 "authCode": "hIoPxD", 17 "actionCode": "8043", 18 "userMetadata": { 19 "deviceId": "testDevDeviceId", 20 "longitude": 80.56565656565657, 21 "latitude": -23.565656565656564, 22 "ipAddress": "198.162.123.145" 23 }, 24 "finalBalance": 1738845, 25 "traceId": "110b489f6c7d268f" 26 } 27}

Respuesta de petición no exitosa

Cuando una transacción no es reversable

1{ 2 "message": "The transaction is not reversable", 3 "code": "TRANSACTION_IS_NOT_REVERSABLE", 4 "description": "The transaction is not reversable", 5 "args": [ 6 { 7 "arg": "TRANSACTION_TYPE", 8 "value": "DISPUTE_FEE" 9 } 10 ], 11 "status": "412 PRECONDITION_FAILED" 12}

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

1{ 2 "message": "The target transaction does not exist", 3 "code": "TRANSACTION_DOES_NOT_EXIST", 4 "description": "The target transaction does not exist", 5 "args": [ 6 { 7 "arg": "TRANSACTION_ID", 8 "value": "636d6c272986e05c2e9b59bby" 9 } 10 ], 11 "status": "400 BAD_REQUEST" 12}