Transactions

If you do not use our Credit Core or our Authorizer, you will need to implement and expose the “Authorization” and “Adjustments” endpoints in your backend so that we can communicate.

We are going to consume your endpoints at this moment:

  • During the online flow, each time a user uses their card at any store or e-commerce.
  • When the network (Mastercard, Visa, etc.) requests the reconciliation of all payments presented by merchants.

Considerations:

  • If there is a discrepancy in the reconciliation, we will request an adjustment to your API.
  • We will need your endpoints to respond as quickly as possible to ensure a good user experience. If the response is delayed, we will reject the transaction.
  • We will use an idempotency header to avoid creating two or more resources for the same request. Learn more
  • You will need to validate and sign the authorizations following the steps in this documentation.

How to test your implementation and sample code


You can test your backend implementation with some typical operations that we will send with a Postman collection included in our public examples repository. You will be able to import the collection into a Postman instance and simulate real requests to your backend, including the signature generation and verification algorithm.

 

Reconciliation file


Daily we will send you two files in CSV format via SFTP (Secure File Transfer Protocol) so you can reconcile all transactions between your system and ours.

 

Authorize

The endpoint /transactions/authorizations/{type} allows authorizing debit or credit transactions that come through the online flow to the Authorization stage.

We will send you a request to authorize or reject the transaction.

Considerations

We expect a quick response to ensure a good experience. If the response is delayed, we will reject the transaction.

In addition to validating the signature we sent you, when generating the response you must sign your body along with the timestamp and the response endpoint with your api-secret after impacting the operation. Please note that we will validate the signature and reject the transaction if the signature does not match or has expired.

You can find more information in Webhook Configuration.

Available parameters
Body Parameters
transactionobject
Information related to the transaction.
merchantobject
Information related to the merchant.
cardobject
Non-sensitive information related to the card.
installmentsobject
Information related to the installments of the transaction; this parameter will only be received for credit card purchase authorizations with installments.
userobject
Information related to the user who performed the transaction.
amountobject
Information related to the amounts of the transaction. These amounts can be greater than or equal to zero.
extra_dataobject
Information related to extra fields of the transaction.
Path Parameters
typestringrequired
The type of operation that we will execute on your client's balance. If it is debit, you must deduct the amount from the user's balance. If it is credit, you must add funds to the user's balance. NOTE: If you have already integrated the authorization endpoint without /debit, you will not see changes in behavior.
Enum: debitcredit
Response details
statusstring
A status that indicates whether we should approve or reject the transaction
Enum: APPROVEDREJECTED
messagestring
Descriptive message with the result of the operation.
status_detailstring
Allows tracking the reason why the transaction was not approved
Enum: APPROVEDINSUFFICIENT_FUNDSINVALID_MERCHANTINVALID_AMOUNTSYSTEM_ERROROTHER
balanceobject
Account balance. It is returned only if the type 'BALANCE_INQUIRY' is sent. Available only for Mexico.

Was this section helpful to you?

POST/transactions/authorizations/{type}
{
"transaction":{
"id":
"ctx-200kXoaEJLNzcsvNxY1pmBO7fEx"
"type":
"PURCHASE"
"point_type":
"POS"
"entry_mode":
"MANUAL"
"country_code":
"ARG"
"origin":
"DOMESTIC"
"source":
"ONLINE"
"network":
"MASTERCARD"
"cardless_withdrawal_user_id":
"string"
"cardless_withdrawal_token":
"string"
"tl_id":
"string"
"original_transaction_id":
"ctx-200kirg6qicg1qHSCbgaStrEHjI"
"local_date_time":
"2019-08-24T14:15:22"
}
"merchant":{
"id":
"string"
"mcc":
"string"
"address":
"string"
"name":
"string"
"terminal_id":
"string"
"country":
"string"
"city":
"string"
}
"card":{
"id":
"c-1625519392748E6XZBK"
"product_type":
"PREPAID"
"provider":
"MASTERCARD"
"last_four":
"1573"
}
"installments":{
"quantity":
"12"
"credit_type":
"NO_PROMOTION"
"grace_period":
"0"
"current_installment":
"1"
"promotion_type":
"MSI_PROMOTION"
}
"user":{
"id":
"u-1625758043579BAR6D4"
}
"amount":{
"local":{
...
}
"settlement":{
...
}
"transaction":{
...
}
"details":[
...
]
}
"extra_data":{
"cardholder_verification_method":
"FAIL_PROCESSING"
"pin_presence":
"ONLINE"
"pin_validation":
"VALID"
"cvv_presence":
"PRESENT"
"cvv_validation":
"MATCHING"
"expiration_date_presence":
"PRESENT"
"expiration_date_validation":
"EXPIRED"
"function_code":
"STANDARD"
"tokenization_wallet_name":
"Apple_Pay"
"tokenization_wallet_id":
"0"
"cardholder_presence":
"CARDHOLDER_PRESENCE_PRESENT"
"card_presence":
"PRESENT"
"pin_change_send":
"SENT"
"pin_change_result":
"APPLIED"
}
}
Response examples
{
"status":
"APPROVED"
"message":
"string"
"status_detail":
"APPROVED"
"balance":{
"total":
"982345.12"
"currency":
"ARS"
}
}

Adjustments

The endpoint /transactions/adjustments/{type} allows us to make credit and debit adjustments on transactions.

Additionally, through this endpoint, we will send you an adjustment request when the networks (Mastercard or Visa) force a transaction. You may also receive Payments that come to us through the offline flow Compensation stage.

It is not possible to reject transactions from this endpoint. We will always consider them effective and financially impactful, regardless of the response we receive. We will wait for you to inform us of the transaction result in your system. It will not generate changes in our operations, but it may be useful for cases of manual review.

Considerations

This endpoint is used during reconciliation and online flows, mainly to make adjustments during the settlement process and also in case of refunds.

In addition to validating the signature we sent you, when generating the response you must sign your body along with the timestamp and the response endpoint with your api-secret after impacting the operation. Please note that we will validate the signature and reject the transaction if the signature does not match or has expired.

You can find more information in Webhook Configuration.

Available parameters
Body Parameters
transactionobject
Information related to the transaction.
merchantobject
Information related to the merchant.
cardobject
Non-sensitive information related to the card.
installmentsobject
Information related to the installments of the transaction; this parameter will only be received for credit card purchase authorizations with installments.
userobject
Information related to the user who performed the transaction.
amountobject
Information related to the amounts of the transaction. These amounts can be greater than or equal to zero.
Path Parameters
typestringrequired
The type of operation that we will execute on your client's balance. If it is debit, you must deduct the amount from the user's balance. If it is credit, you must add funds to the user's balance. NOTE: You may receive adjustments with very small values, it will be up to you to impact them on your clients' balances or not.
Enum: debitcredit
Response details
status_detailstring
Allows informing the transaction result
Enum: APPROVEDINSUFFICIENT_FUNDSINVALID_MERCHANTINVALID_AMOUNTSYSTEM_ERROROTHER
messagestring
Descriptive message with the transaction result

Was this section helpful to you?

POST/transactions/adjustments/{type}
{
"transaction":{
"id":
"ctx-200kXoaEJLNzcsvNxY1pmBO7fEx"
"type":
"PURCHASE"
"point_type":
"POS"
"entry_mode":
"MANUAL"
"country_code":
"ARG"
"origin":
"DOMESTIC"
"source":
"ONLINE"
"network":
"MASTERCARD"
"cardless_withdrawal_user_id":
"string"
"cardless_withdrawal_token":
"string"
"tl_id":
"string"
"original_transaction_id":
"ctx-200kirg6qicg1qHSCbgaStrEHjI"
"local_date_time":
"2019-08-24T14:15:22"
}
"merchant":{
"id":
"string"
"mcc":
"string"
"address":
"string"
"name":
"string"
"terminal_id":
"string"
"country":
"string"
"city":
"string"
}
"card":{
"id":
"c-1625519392748E6XZBK"
"product_type":
"PREPAID"
"provider":
"MASTERCARD"
"last_four":
"1573"
}
"installments":{
"quantity":
"12"
"credit_type":
"NO_PROMOTION"
"grace_period":
"0"
"current_installment":
"1"
"promotion_type":
"MSI_PROMOTION"
}
"user":{
"id":
"u-1625758043579BAR6D4"
}
"amount":{
"local":{
...
}
"settlement":{
...
}
"transaction":{
...
}
"details":[
...
]
}
}
Response examples
{
"status_detail":
"APPROVED"
"message":
"string"
}

Notifications.

This service allows notifying when a transaction is resolved, either by Pomelo or by the network (Mastercard, Visa, etc.).

Considerations

We expect a response of type 2XX to ensure that the notification was received. Otherwise, we will resend it.

You can find more information in Webhook Configuration.

Available parameters
Body Parameters
event_idstring
Event identifier.
Example: authorization-advice
event_detailobject
Information related to the event. This may vary depending on the type of event.
idempotency_keystring
Idempotent identifier for event creation.
Example: ctx-2CIllOHdIcC5qWjpiwRlFy2nZM8

Was this section helpful to you?

POST/transactions/v1/notifications
{
"event_id":
"authorization-advice"
"event_detail":{
"transaction":{
...
}
"merchant":{
...
}
"card":{
...
}
"installments":{
...
}
"user":{
...
}
"amount":{
...
}
"status":
"REJECTED"
"status_detail":
"string"
"extra_detail":
"string"
"extra_data":{
...
}
}
"idempotency_key":
"ctx-2CIllOHdIcC5qWjpiwRlFy2nZM8"
}
Response examples