Transactions

This service allows you to authorize transactions.

There are two possibilities for the state of transactions created:

  • APPROVED: If the transaction is approved.
  • REJETED: If the transaction is rejected.

All transactions that are approved modify the account balance by the amount specified.

All transaction sums are given in the account’s currency with a positive sign. To determine whether the transaction is to deposit or withdraw money from an account, the entry_type parameter must be used. This parameter may be filled out as follows:

  • DEBIT: for transactions withdrawing money from the account.
  • CREDIT: for transactions depositing money into the account.

All transactions have a type, indicated with the type parameter. Each type has different data sent along with the transaction in the tx_properties object.

You can request extra data from all transactions using the metadata object.

The details property may be used to break down the total transaction sum into its constituent parts. For example, suppose you are processing a transaction in a digital store totaling $149.99. Let us further suppose that this total is composed of:

  • $119.00 purchase
  • $40.00 taxes
  • -$10.00 discounts

This breakdown may be reported by adding multiple items to the details list. Each detail must have a type associated with it:

  • BASE: transaction base expense.
  • FEE: commission expenses.
  • TAX: Taxes.
  • EXTRACASH: money withdrawals.
  • DISCOUNT: Discounts.

More than one detail may be added with the same type. The only restriction is that the details total is equal to the transaction total.

Processing types

Each transaction has a process_type field that can take any of these values:

  • ORIGINAL: New transaction.
  • ADJUSTMENT: Settings.
  • REFUND: refund or return.
  • REVERSAL: Reversal.

For REFUND, REVERSAL or ADJUSTMENT transactions that are or can specify the original transaction they are based on. This transaction is known as a “parent transaction“, indicated by the parent_tx_id field.

Idempotency

Transaction authorization requests have an idempotency mechanism to prevent duplicate processing.

For the transaction to be processed you must accompany each authorization request with an X-Idempotency-Key header that has a unique identifier. If you do not get a response or receive one with status code type 5xx, repeat the request with the same idempotency key until you get a successful response (code 201).

Repeated requests using the same idempotency key will only result in a transaction being created. The first request creates the transaction and the next one gives the same response but does not create a new transaction.

If an authorization request has an idempotency key already used in another transaction, an error is returned.

Answers

Correctly processed transactions are reported with a status code 201. This status does not indicate whether the transaction was approved or not. Read the answer 'result' field and note if it is APPROVED or REJECTED.

Any other status code indicates that something went wrong and the reason for rejection is given in the rejection_reason field. This field may be filled out as follows:

  • INSUFFICIENT_FUNDS: The account does not have sufficient funds.
  • ACCOUNT_DISABLED: the account has been disabled.
  • ACCOUNT_FROZEN: The account cannot process debit transactions.
  • CLIENT_MONTHLY_AMOUNT_LIMIT_REACHED: exceeded the monthly movement limit it had.
  • CLIENT_DAILY_AMOUNT_LIMIT_REACHED: exceeded the limit of daily movements it had.
  • BRIDGE_ACCOUNT_MONTHLY_AMOUNT_LIMIT_REACHED: Exceeded the limit of monthly movements they had for bridge account.
  • BRIDGE_ACCOUNT_DAILY_AMOUNT_LIMIT_REACHED: Exceeded the limit of daily movements they had for bridge account.
  • PROCESS_TIME_EXPIRED: The transaction did not start processing before the time indicated in the process_before field, which is optional.

When a transaction cannot be processed an error response is returned with the error_code field indicating the reason:

  • ACCOUNT_NOT_FOUND: account could not be found.
  • INVALID_AUTHORIZATION_REQUEST: The transaction authorization request is not valid.
  • INVALID_PARENT_TX_ID: The parent transaction specified is invalid.
  • DUPLICATED_IDEMPOTENCY_KEY: You already used the idempotency key in another transaction.

Authorize transaction

The /core/transactions/v1 endpoint allows you to authorize inbound and outbound money transactions from digital accounts. Successfully processed transactions will return status code 201, whether approved or rejected. Check the result field to see the result.
Available parameters
Header Parameters
X-Idempotency-Keystring(maxLength: 256, minLength: 0)required
Body Parameters
account_idoneOfrequired
ID de una cuenta de Pomelo
Example: acc-23GMRyaPjVbczjGtLfQ6zgUJmLv
typestringrequired
Transaction type.
Enum: CARD_PURCHASEEXTRACASHCASHOUT_STORECASHOUT_ATMBANK_TRANSFER_INBANK_TRANSFER_OUTCASHINCASHOUTMANUAL_MOVEMENTCLIENT_PAYMENTPAYMENT_INPAYMENT_OUT
process_typestringrequired
Used to indicate if the transaction is original, refund, reversal or adjustment.
Example: REFUND
Enum: ORIGINALADJUSTMENTREFUNDREVERSAL
parent_tx_idoneOf
ID de una transacción.
Example: 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.
Example: DEBIT
Enum: CREDITDEBIT
total_amountstring(maxLength: 256, minLength: 0)required
Total transaction amount.
Example: 999.99
process_beforestring(format: date-time)
This field is optional and gives a deadline for processing the transaction. It is useful for asynchronous flows.
Response details
idstringrequired
Example: atx-230ReKOtS2lv0yUi2FKG98ycdXZ
resultstringrequired
Example: REJECTED
Enum: APPROVEDREJECTED
rejection_reasonstring
Example: 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
Was this section helpful to you?
POST/core/transactions/v1
{
"account_id":
"acc-23GMRyaPjVbczjGtLfQ6zgUJmLv"
"type":
"CARD_PURCHASE"
"process_type":
"REFUND"
"parent_tx_id":
"atx-23GMkfOa7V1MqUlvEic4Dp7XhTT"
"data":{
"description":{
...
}
"details":[
...
]
"metadata":
"string"
}
"entry_type":
"DEBIT"
"total_amount":
"999.99"
"process_before":
"2022-09-28T15:49:15.586Z"
}
Response examples

Authorize P2P transaction

The endpoint /core/transactions/v1/p2p allows you to authorize third-party (P2P) movements of money in and out between the user account and bridge account. Successfully processed transactions will return status code 201, whether approved or rejected. Check the result field to see the result.
Available parameters
Header Parameters
X-Idempotency-Keystring(maxLength: 256, minLength: 0)required
Body Parameters
source_account_idstringrequired
ID de la cuenta de origen
Example: acc-23GMRyaPjVbczjGtLfQ6zgUJmLv
destination_account_idstringrequired
ID de la cuenta de destino.
Example: acc-76SOlsOklsdl92OsldllKzgUVjUu
source_dataobjectrequired
Data de la transacción de destino.
destination_dataobjectrequired
Data de la transacción de destino.
total_amountstringrequired
Total transaction amount.
Example: 1200.15
process_beforestring(format: date-time)
This field is optional and gives a deadline for processing the transaction. It is useful for asynchronous flows.
Response details
source_account_txobject
destination_account_txobject
Was this section helpful to you?
POST/core/transactions/v1/p2p
{
"source_account_id":
"acc-23GMRyaPjVbczjGtLfQ6zgUJmLv"
"destination_account_id":
"acc-76SOlsOklsdl92OsldllKzgUVjUu"
"source_data":{
"metadata":
"string"
"description":{
...
}
"details":[
...
]
}
"destination_data":{
"metadata":
"string"
"description":{
...
}
"details":[
...
]
}
"total_amount":
"1200.15"
"process_before":
"2022-09-28T15:49:15.587Z"
}
Response examples