Chargebacks

Chargebacks

The Pomelo Chargeback Service is a comprehensive solution designed to facilitate and optimize the chargeback management of payment transactions made through the Pomelo platform.

What is a chargeback?

A chargeback is a refund request for a payment made through the Pomelo platform.

Chargebacks status

All chargebacks have a status field describing which state of the management process they are in. The possible chargeback statuses are the following:

  • PENDING: The chargeback is in pending status.
  • UNDER_EVALUATION: A first analysis of the chargeback is underway, and more information is needed to continue with the dispute.
  • DISPUTE_OPEN: The transaction dispute was opened with the brand (Mastercard or Visa) and we are waiting for their response.
  • DISPUTE_REJECTED: The dispute was rejected by the brand since the transaction did not meet the requirements to be disputed.
  • DISPUTE_WON: The dispute was won in favor of the issuer.
  • DISPUTE_LOST: The dispute was lost; in this case, the liability remains on the issuer's or cardholder's side.
  • DISPUTE_NOT_PROCESSED: No pudimos procesar el contracargo dadas las características del pago.
  • TRANSACTION_NOT_PRESENTED: La transacción aún no ha sido presentada por el adquirente, por lo que no es posible solicitar un contracargo.

Create chargeback

The endpoint /chargebacks/v2/ permits the creation of a chargeback.

Validations

To create a chargeback, the following validations must be fulfilled:

  • Only one chargeback can exist for each transaction.
  • The amount input must be greater than 0.
  • The amount input must be less than or equal to the transaction amount.
  • The transaction associated with the chargeback must have occurred less than 90 days ago.

Considerations

When creating a chargeback of type CONTROVERSY, we can add attachments to support the dispute. For this, use the resource /chargebacks/v2/{chargebackId}/attachments

Available parameters
Header Parameters
Authorizationstringrequired
Authorization header
Example: `Bearer {access_token}`
Body Parameters
card_replacementboolean
This field represents if the user has already received a new card as
country_idstringrequired
ISO country identifier (can be a 2 or 3 letter code)
descriptionstring
A brief description of what happened in the case
dispute_amountnumber
Chargeback amount, if not specified, it will be the full amount of the transaction
dispute_typestringrequired
Type of dispute; FRAUD is used for transactions where the user is unaware of the transaction, while CONTROVERSY is used for when there is a disagreement between merchant and user
Enum: CONTROVERSYFRAUD
reasonstringrequired
The chargeback reason. The values PHYSYCAL_PAYMENT and VIRTUAL_PAYMENT are only accepted if the dispute_type field is set to FRAUD
Enum: VIRTUAL_PAYMENTPHYSICAL_PAYMENTPRODUCT_NOT_DELIVERYPURCHASE_CANCELLATIONSERVICE_NOT_PERFORMEDOTHER
transaction_idstringrequired
Identifier of the transaction to be charged back
trust_credit_appliedboolean
Indicate whether the user reporting the chargeback was given credit in trust or not. This only applies in Mexico
Response details
amountnumber
Chargeback amount, the associated currency is in the currency_id field
attachmentsarray
List of attachments metadata
card_replacementboolean
Represents whether a replacement card was sent
country_idstring
ISO identifier of the country associated with the transaction
Example: ARG
created_atstring
Chargeback creation date
currencystring
Currency in which the transaction was made
Example: ARS
descriptionstring
Description provided by the user at the time of the chargeback creation
reasonstring
The chargeback reason. The values PHYSYCAL_PAYMENT and VIRTUAL_PAYMENT are only accepted if the dispute_type field is set to FRAUD
Enum: VIRTUAL_PAYMENTPHYSICAL_PAYMENTPRODUCT_NOT_DELIVERYPURCHASE_CANCELLATIONSERVICE_NOT_PERFORMEDOTHER
dispute_typestring
Dispute type; FRAUD is used for transactions in which the user does not recognize the transaction, while CONTROVERSY is used when there is a disagreement between the merchant and user
Enum: CONTROVERSYFRAUD
idstring
Chargeback identifier
Example: `cbk-1ab2c3d4`
liabilitystring
The financial institution responsible for paying the cost generated by the chargeback
Enum: MERCHANTISSUERUSERPOMELO
dispute_reasonstring
statusstring
Status in which the chargeback is
Enum: PENDINGUNDER_EVALUATIONDISPUTE_OPENSECOND_PRESENTMENTDISPUTE_REJECTEDDISPUTE_WONDISPUTE_LOSTDISPUTE_NOT_PROCESSEDTRANSACTION_NOT_PRESENTED
transaction_idstring
Identifier of the transaction associated to the chargeback
trust_credit_appliedboolean
updated_atstring
Last chargeback update date
user_idstring
User Id associated with the chargeback transaction

Was this section helpful to you?

POST/chargebacks/v2
{
"card_replacement":
true
"country_id":
"string"
"description":
"string"
"dispute_amount":
"number"
"dispute_type":
"CONTROVERSY"
"reason":
"VIRTUAL_PAYMENT"
"transaction_id":
"string"
"trust_credit_applied":
true
}
Response examples
{
"amount":
"number"
"attachments":[
0:{
...
}
]
"card_replacement":
true
"country_id":
"ARG"
"created_at":
"string"
"currency":
"ARS"
"description":
"string"
"reason":
"VIRTUAL_PAYMENT"
"dispute_type":
"CONTROVERSY"
"id":
"`cbk-1ab2c3d4`"
"liability":
"MERCHANT"
"dispute_reason":
"string"
"status":
"PENDING"
"transaction_id":
"string"
"trust_credit_applied":
true
"updated_at":
"string"
"user_id":
"string"
}

Attach file to a chargeback

The endpoint /chargebacks/v2/$ID/attachments enables the attachment of files to a chargeback in order to send it to the brand and simplify the dispute resolution

Restrictions

  • The attached file must be an image or a PDF file.
  • The attached file must be smaller than 3 MB.
  • Cada contracargo puede tener hasta 10 archivos adjuntos.

How to attach the file?

The file must be attached in the request body as a multipart/form-data, under the fileUpload key.

Available parameters
Header Parameters
Authorizationstringrequired
Authorization header
Example: `Bearer {access_token}`
Path Parameters
chargebackIdstringrequired
Chargeback identifier
Example: `cbk-a1b2c3d4`
Response details
errorboolean
infostring
msg

Was this section helpful to you?

POST/chargebacks/v2/{chargebackId}/attachments
Response examples
{
"error":
true
"info":
"string"
}

Find chargebacks

The endpoint /chargebacks/v2/ performs a search for customer chargebacks. Filters can be added to tailor the search results.

Considerations

Filters must be specified as parameters following this pattern: filter[field]=value. For example: filter[status]=APPROVED

The results will be paginated and you can specify the amount of data per page and also which page you wish to view.

Date range

There is a filter for the field created_at, which you can use to get the chargebacks created within a date range. For example: filter[created_at][from]=2022-07-27&filter[created_at][to]=2022-07-28

You can also filter by the last update date using updated_at.

Sorting

You can specify the order of the results with certain parameters that you must send as list of strings in the sort filter type. For example: ?sort=status,created_at

The default sorting will be ascending. To specify a descending sorting, you must send the character '-' as a prefix of the attribute. For example: ?sort=status,-created_at

Available parameters
Header Parameters
Authorizationstringrequired
Authorization header
Example: `Bearer {access_token}`
Query Parameters
filter[user_id]string
User ID
Example: `usr-1a2b3c`
filter[status]string
Status of chargebacks to be returned by the endpoint
Enum: PENDINGUNDER_EVALUATIONDISPUTE_OPENSECOND_PRESENTMENTDISPUTE_REJECTEDDISPUTE_WONDISPUTE_LOSTDISPUTE_NOT_PROCESSEDTRANSACTION_NOT_PRESENTED
filter[transaction_id]string
Transaction identifier
Example: `trx-a1b2c3d4`
Response details
dataarray
metaobject

Was this section helpful to you?

GET/chargebacks/v2/
Response examples
{
"data":[
0:{
...
}
]
"meta":{
"filter":[
...
]
"pagination":{
...
}
}
}

Obtain chargeback

Returns a chargeback with the Identifier given by parameter
Available parameters
Header Parameters
Authorizationstringrequired
Authorization header
Example: `Bearer {access_token}`
Path Parameters
chargebackIdstringrequired
Chargeback identifier
Example: `cbk-a1b2c3e4`
Response details
dataobject

Was this section helpful to you?

GET/chargebacks/v2/{chargebackId}
Response examples
{
"data":{
"amount":
"number"
"attachments":[
...
]
"card_replacement":
true
"country_id":
"ARG"
"created_at":
"string"
"currency":
"ARS"
"description":
"string"
"reason":
"VIRTUAL_PAYMENT"
"dispute_type":
"CONTROVERSY"
"id":
"`cbk-1ab2c3d4`"
"liability":
"MERCHANT"
"dispute_reason":
"string"
"status":
"PENDING"
"transaction_id":
"string"
"trust_credit_applied":
true
"updated_at":
"string"
"user_id":
"string"
}
}

Chargebacks notifications

This service will be responsible for notifying you when a chargeback is modified.

If you have doubts about how to set up a webhook, visit our documentation.

You can also find more information about the Verification Process of the digital signature.

Available parameters
Header Parameters
X-Api-Keystringrequired
This header helps you identify which api-secret to use if multiple api-key and api-secret pairs were configured.
Example: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
This header contains the digital signature (timestamp + endpoint + body) that must be verified to ensure the integrity of the request. If the signature does not match, the order must be rejected.
Example: X-Signature: hmac-sha256 N70BkBKch1gwQDPj0jF0ooB9QQVXBEp5VQE+SGe6Z0k=
X-Timestampstringrequired
This header has the moment the order was signed in unix-epoch format so that you can verify the signature has not expired.
Example: X-Timestamp: 1637117179
X-Endpointstringrequired
The endpoint where the order is placed and used to create the signature. Use this header to regenerate the signature to be validated, check with your service endpoint and confirm that they match.
Example: X-Endpoint: /client/api/chargeback/done
Body Parameters
event_idstringrequired
Event identifier.
Example: chargeback_notification
Enum: chargeback_notification
idempotency_keystringrequired
Idempotent identifier for creating the event.
Example: 27Ky00tAZ0Rdi7G2Vt9iino8AYs
transaction_idstringrequired
Identifier of the transaction to be charged back
Example: ctx-1a2b3c4b
statusstringrequired
Estado del Contracargo
Example: PENDING
Enum: PENDINGUNDER_EVALUATIONDISPUTE_OPENSECOND_PRESENTMENTDISPUTE_REJECTEDDISPUTE_WONDISPUTE_LOSTDISPUTE_NOT_PROCESSEDTRANSACTION_NOT_PRESENTED
status_ticketstringrequired
Estado del Ticket del Contracargo
Example: DONE
Enum: WAITING_FOR_SUPPORTWAITING_FOR_CUSTOMERESCALATEDDONECLOSED
idstringrequired
Chargeback identifier
Example: cbk-1a2b3c
amountnumberrequired
Monto del contracargo.
Example: 10
currencystringrequired
Moneda del contracargo.
Example: ARS
countrystringrequired
País del contracargo.
Example: ARG
client_idstringrequired
Cliente del contracargo.
Example: cli-1a2b3c
liabilitystringrequired
The financial institution responsible for paying the cost generated by the chargeback
Enum: MERCHANTISSUERUSERPOMELO
created_atstringrequired
Chargeback creation date

Was this section helpful to you?

POST/chargebacks/<session-event-client-url>
{
"event_id":
"chargeback_notification"
"idempotency_key":
"27Ky00tAZ0Rdi7G2Vt9iino8AYs"
"transaction_id":
"ctx-1a2b3c4b"
"status":
"PENDING"
"status_ticket":
"DONE"
"id":
"cbk-1a2b3c"
"amount":
10
"currency":
"ARS"
"country":
"ARG"
"client_id":
"cli-1a2b3c"
"liability":
"MERCHANT"
"created_at":
"string"
}
Response examples