Transacciones

Este servicio te permite autorizar transacciones.

Las transacciones solo tienen dos estados posibles:

  • APPROVED: Si la transacción es aprobada.
  • REJECTED: Si la transacción es rechazada.

Todas las transacciones que son aprobadas modificarán el balance de la cuenta por el monto especificado.

Todos los montos de las transacciones están expresados en la moneda de la cuenta y con signo positivo. Para distinguir si la intención de la transacción es ingresar o retirar dinero de una cuenta utiliza el parámetro entry_type. Este parámetro puede tomar estos valores:

  • DEBIT: Para transacciones que quieran retirar dinero de la cuenta.
  • CREDIT: Para transacciones que quieran ingresar dinero a la cuenta.

Todas las transacciones tienen un tipo, que indicamos con el parámetro type. Cada tipo de transacción tiene distintos datos que se envían con la transacción dentro del objeto tx_properties.

Podrás solicitar datos extras de todas las transacciones usando el objeto metadata.

La propiedad details se puede usar para descomponer el monto total de una transacción en las partes que lo componen. Por ejemplo supongamos que se está procesando una transacción que representa una compra en una tienda digital por un total de $149,99. Supongamos además, que este total se compone por:

  • $119,00 de la compra.
  • $40,00 de impuestos.
  • -$10,00 de descuentos.

Esta descomposición se puede informar agregando multiples items a la lista details. Cada detalle debe tener un tipo asociado:

  • BASE: Gasto base de la transacción.
  • FEE: Gastos de comisión.
  • TAX: Impuestos.
  • EXTRACASH: Extracciones de dinero.
  • DISCOUNT: Descuentos.

Es posible agregar más de un detalle con el mismo tipo. La única restricción es que la sumatoria de los montos de los detalles sea igual al monto total de la transacción.

Tipos de procesamiento

Cada transacción lleva un campo process_type que puede tomar alguno de estos valores:

  • ORIGINAL: Transacción nueva.
  • ADJUSTMENT: Ajuste.
  • REFUND: Reintegro o devolución.
  • REVERSAL: Reversa.

Para las transacciones que sean REFUND, REVERSAL o ADJUSTMENT se puede especificar la transacción originaria que las motiva. Esa transacción se conoce como “transacción padre” y la indicamos mediante el campo parent_tx_id.

Idempotencia

Los pedidos de autorización de transacciones tienen un mecanismo de idempotencia para prevenir el procesamiento duplicado.

Deberás acompañar cada request de autorización con un header X-Idempotency-Key que tenga un identificador único para la transacción a procesar. En caso de que no obtengas respuesta o recibas una respuesta con status code del tipo 5xx, deberás volver a repetir el request con la misma key de idempotencia hasta obtener una respuesta exitosa (code 201).

Los requests repetidos que utilicen la misma key de idempotencia solo tendrán como resultado la creación de una transacción. El primer request creará la transacción y los siguientes devolverán la misma respuesta que se devolvió para el primer request, pero no crearán una transacción nueva.

Si un pedido de autorización tiene una key de idempotencia que ya usaste en otra transacción, responderemos con un error.

Respuestas

Las transacciones que procesamos correctamente se informan con un status code 201. Pero atención: este estado no indica si la transacción fue aprobada. Para saber eso, tendrás que leer el campo 'result' de la respuesta e identificar si su valor es APPROVED o REJECTED.

Cualquier otro status code indica que algo salió mal y te indicaremos el motivo de rechazo en el campo rejection_reason. Este campo puede tomar los siguientes valores:

  • INSUFFICIENT_FUNDS: La cuenta no tiene fondos suficientes.
  • ACCOUNT_DISABLED: La cuenta está deshabilitada.
  • ACCOUNT_FROZEN: La cuenta no puede procesar transacciones de débito (DEBIT).
  • CLIENT_MONTHLY_AMOUNT_LIMIT_REACHED: Superó el límite de movimientos mensual que tenía
  • CLIENT_DAILY_AMOUNT_LIMIT_REACHED: Superó el límite de movimientos diarios que tenía.
  • BRIDGE_ACCOUNT_MONTHLY_AMOUNT_LIMIT_REACHED: Superó el límite de movimientos mensuales que tenía para cuenta bridge.
  • BRIDGE_ACCOUNT_DAILY_AMOUNT_LIMIT_REACHED: Superó el límite de movimientos diarios que tenía para cuenta bridge.
  • PROCESS_TIME_EXPIRED: La transacción no comenzó a procesarse antes del tiempo indicado por el campo process_before, que es opcional.
  • MAX_BRIDGE_ACCOUNT_FUNDING_LIMIT_EXCEEDED: Superó el límite máximo de fondeos para cuenta bridge.
  • SOURCE_ACCOUNT_TX_REJECTED: Este motivo de rechazo solo aplica para transacciones P2P. La transacción fue rechazada debido a que la cuenta de origen rechazó la transacción.
  • DESTINATION_ACCOUNT_TX_REJECTED: Este motivo de rechazo solo aplica para transacciones P2P. La transacción fue rechazada debido a que la cuenta de destino rechazó la transacción.
  • FRAUD_SCORING_REJECTED: La transacción fue rechazada debido a que el análisis de prevención de fraude no la permitió.
  • MONTHLY_AMOUNT_LIMIT_REACHED: Superó el límite de transacción mensual.
  • DAILY_AMOUNT_LIMIT_REACHED: Superó el límite de transacción diario.

Cuando no podemos procesar una transacción devolveremos una respuesta de error con el campo error_code indicando el motivo:

  • ACCOUNT_NOT_FOUND: No encontramos la cuenta.
  • INVALID_AUTHORIZATION_REQUEST: El request para autorizar la transacción no es válido.
  • INVALID_PARENT_TX_ID: La transacción padre que especificaste es inválida.
  • DUPLICATED_IDEMPOTENCY_KEY: Ya usaste la key de idempotencia en otra transacción.

Autorizar Transacción

El endpoint /core/transactions/v1 te permite autorizar transacciones de entrada y salida de dinero de las cuentas digitales. Las transacciones procesadas correctamente devolverán el status code 201, ya sea que fueran aprobadas o rechazadas. Revisa el campo result para ver el resultado.
Parámetros disponibles
Header Parameters
X-Idempotency-Keystring(maxLength: 256, minLength: 0)required
Body Parameters
account_idoneOfrequired
ID de una cuenta de Pomelo
Ejemplo: acc-23GMRyaPjVbczjGtLfQ6zgUJmLv
typestringrequired
Tipo de la transacción.
Enum: CARD_PURCHASEEXTRACASHCASHOUT_STORECASHOUT_ATMBANK_TRANSFER_INBANK_TRANSFER_OUTCASHINCASHOUTMANUAL_MOVEMENTCLIENT_PAYMENTPAYMENT_INPAYMENT_OUTBILL_PAYMENT_OUTCASHIN_INVOICE
process_typestringrequired
Sirve para indicar si la transacción se trata de un movimiento original, un reintegro, reversa o un ajuste.
Ejemplo: REFUND
Enum: ORIGINALADJUSTMENTREFUNDREVERSAL
parent_tx_idoneOf
ID de una transacción.
Ejemplo: atx-23GMkfOa7V1MqUlvEic4Dp7XhTT
dataobject
entry_typestringrequired
Indica si la transacción quiere ingresar o debitar dinero de una cuenta. Para ingresar dinero se debe usar CREDIT y para debitar DEBIT.
Ejemplo: DEBIT
Enum: CREDITDEBIT
total_amountstring(maxLength: 256, minLength: 0)required
Monto total de la transacción.
Ejemplo: 999.99
process_beforestring(format: date-time)
Este campo es opcional y sirve para indicar una fecha limite para el procesamiento de una transacción. Es útil para flujos asincrónicos.
Detalle de respuestas
idstringrequired
Ejemplo: atx-230ReKOtS2lv0yUi2FKG98ycdXZ
resultstringrequired
Ejemplo: REJECTED
Enum: APPROVEDREJECTED
rejection_reasonstring
Ejemplo: INSUFFICIENT_FUNDS
Enum: INSUFFICIENT_FUNDSACCOUNT_DISABLEDACCOUNT_FROZENMONTHLY_AMOUNT_LIMIT_REACHEDDAILY_AMOUNT_LIMIT_REACHEDCLIENT_MONTHLY_AMOUNT_LIMIT_REACHEDCLIENT_DAILY_AMOUNT_LIMIT_REACHEDBRIDGE_ACCOUNT_MONTHLY_AMOUNT_LIMIT_REACHEDBRIDGE_ACCOUNT_DAILY_AMOUNT_LIMIT_REACHEDMAX_BRIDGE_ACCOUNT_FUNDING_LIMIT_EXCEEDEDPROCESS_TIME_EXPIREDSOURCE_ACCOUNT_TX_REJECTEDDESTINATION_ACCOUNT_TX_REJECTEDFRAUD_SCORING_REJECTED
created_atstring(format: date-time)required
¿Te resultó útil esta sección?
POST/core/transactions/v1
{
"account_id":
"acc-23GMRyaPjVbczjGtLfQ6zgUJmLv"
"type":
"CARD_PURCHASE"
"process_type":
"REFUND"
"parent_tx_id":
"atx-23GMkfOa7V1MqUlvEic4Dp7XhTT"
"data":{
"tx_properties":{
...
}
"description":{
...
}
"details":[
...
]
"metadata":{
...
}
}
"entry_type":
"DEBIT"
"total_amount":
"999.99"
"process_before":
"2023-01-30T18:57:44.110Z"
}
Ejemplo de respuestas

Autorizar Transacción P2P

El endpoint /core/transactions/v1/p2p te permite autorizar movimientos de terceros (P2P) de entrada y salida de dinero entre la cuenta de usuario y cuenta bridge. Las transacciones procesadas correctamente devolverán el status code 201, ya sea que fueran aprobadas o rechazadas. Revisa el campo result para ver el resultado.
Parámetros disponibles
Header Parameters
X-Idempotency-Keystring(maxLength: 256, minLength: 0)required
Body Parameters
source_account_idstringrequired
ID de la cuenta de origen
Ejemplo: acc-23GMRyaPjVbczjGtLfQ6zgUJmLv
destination_account_idstringrequired
ID de la cuenta de destino.
Ejemplo: acc-76SOlsOklsdl92OsldllKzgUVjUu
source_dataobjectrequired
Data de la transacción de destino.
destination_dataobjectrequired
Data de la transacción de destino.
total_amountstringrequired
Monto total de la transacción.
Ejemplo: 1200.15
process_beforestring(format: date-time)
Este campo es opcional y sirve para indicar una fecha limite para el procesamiento de una transacción. Es útil para flujos asincrónicos.
Detalle de respuestas
source_account_txobject
destination_account_txobject
¿Te resultó útil esta sección?
POST/core/transactions/v1/p2p
{
"source_account_id":
"acc-23GMRyaPjVbczjGtLfQ6zgUJmLv"
"destination_account_id":
"acc-76SOlsOklsdl92OsldllKzgUVjUu"
"source_data":{
"metadata":{
...
}
"description":{
...
}
"details":[
...
]
}
"destination_data":{
"metadata":{
...
}
"description":{
...
}
"details":[
...
]
}
"total_amount":
"1200.15"
"process_before":
"2023-01-30T18:57:44.112Z"
}
Ejemplo de respuestas