- Integration Guidelines
- Implementing a Chargeback API Integration
Implementing a Chargeback API Integration
The Chargeback API allows you to process a chargeback file and record chargebacks against the originating order containing the disputed transaction. A chargeback occurs when a payer disputes a payment, for example, goods not received, unauthorized transaction, in which case the payer's bank reverses all or part of the payment made to the merchant.
To process the chargeback file, the file must conform to certain requirements and specifications. To access these, please contact Commonwealth Bank of Australia.
A typical chargeback dispute process includes the following steps:
- The payer's bank debits the payer's account, at this point either the transaction is pending or the amount has been successfully debited and settled to the merchant.
- The payer initiates a dispute with their bank claiming the funds were incorrectly debited.
- The payer's bank acknowledges the dispute and initiates the chargeback process with the merchant's bank to address the dispute.
- If the merchant's bank does not have enough information to address the dispute, they forward the chargeback to the merchant who can either accept the chargeback or challenge it by providing more information to their bank.
- In the event that the merchant accepts the chargeback, the payer's bank reverses all or part of the payment made to the merchant.
Record Chargebacks
The Record Chargeback request records the chargeback against the originating order for a matching merchant gateway profile.
Record Chargeback API Reference[REST][NVP]
You need to provide the following key fields in the Record Chargeback request, which may be grouped as follows:
Match Information
Provide the following information in the request to enable the gateway to match the chargeback to the original transaction.
transaction.acquirer.id: The ID of the acquirer used to process the transaction.transaction.acquirer.merchantId: The acquirer's identity for the merchant.transaction.dispute.match.date: (Optional) The date of the disputed transaction.- At least one of the following matching criteria:
transaction.dispute.match.acquirerTransactionId: The acquirer’s identifier for the transaction.transaction.dispute.match.stan: The STAN (System Trace Audit Number) of the disputed transaction.transaction.dispute.match.RRN: The Retrieval Reference Number of the disputed transaction. Only applicable wheretransaction.dispute.matchAction=MATCHEDorMATCHED_FALLBACK
transaction.dispute.matchAction: Indicates how you want the gateway to record the chargeback transaction. Valid values for this field are:- MATCHED: The gateway will attempt to match this chargeback transaction to the existing financial transaction using the Date of the original transaction (optional) and at least one of Acquirer Transaction ID, RRN or STAN. If no match is found, then the gateway does not record the chargeback transaction.
- STANDALONE: The gateway creates a new order containing the chargeback transaction and does not attempt to match it to the original transaction. Standalone chargebacks will be identified with the order description "System generated order for an unmatched Chargeback".
- MATCHED_FALLBACK: The gateway will first attempt to match this chargeback transaction to an existing financial transaction using the Date of the original transaction (optional) and at least one of Acquirer Transaction ID, RRN or STAN.
If the chargeback does not match an existing order within a merchant profile or matches multiple orders then the gateway creates a new order with a standalone chargeback transaction.
If the chargeback transaction matches multiple merchant gateway profiles, a standalone chargeback will be created for each merchant profile. Each of these chargeback transactions will contain the order description "Transaction unable to be linked and may be replicated across profiles".
Dispute Information
This is the information about the chargeback such as the chargeback amount, type of dispute, reason, and so on.
transaction.dispute.event: The step in the dispute management process that triggered this transaction. For example,ACTION_REQUIREDindicates that an action from the merchant is required to progress the dispute.transaction.dispute.eventInformation: Additional information provided by the acquirer about the dispute event. For example, when the dispute event isACTION_REQUIRED, you may provide say 'Information Requested' in this field to suggest that the issuer has requested additional information about a disputed transaction.transaction.dispute.reason: A description of why the transaction is disputed.transaction.dispute.reasonCode: A code provided by the acquirer to indicate the reason for the chargeback.transaction.dispute.deadlineDate: The date by which the merchant must take action. For example, if the acquirer has requested additional information (transaction.dispute.event=ACTION_REQUIRED), the merchant must provide a response by this date.transaction.dispute.eventDate: The date of the event in the dispute management process described bytransaction.dispute.event.transaction.dispute.dateRecurringPaymentCancelled: The date the payer notified the issuer to cancel a recurring payment that is being disputed.
A successful Record Chargeback operation returns the matching merchant IDs and the order IDs (existing or new) for the chargeback transactions. The new transaction IDs for chargeback transactions are also returned. The order status is updated and the dispute information will be recorded against the order.
MSO On-Behalf-Of Support
The gateway allows you to submit the Record Chargeback request if you have been authorized to do so on behalf of another MSO. In the Record Chargeback request URL, specify the MSO ID of the MSO that has authorized you to submit this request. Provide your API credentials as configured in Merchant Manager to successfully authenticate to the gateway.
Testing Chargeback API
The Chargeback API does not support a specific testing framework; however, there are ways to test your integration on the gateway.
The first step is to configure your business application to use the gateway's Mastercard Testing Framework (MTF) environment. Contact Commonwealth Bank of Australia for access to the MTF environment.
Once the MTF environment is configured, you can start recording chargeback information against transactions. To allow the chargeback information provided in the request to be associated with a transaction in the gateway, create a test transaction for a production merchant profile, record the STAN and the date of the transaction. Provide the STAN and the date in transaction.dispute.match.stan and transaction.dispute.match.date fields respectively, in the Record Chargeback request.
To check if the chargeback information has been successfully recorded by the gateway, log on to Merchant Manager, Merchant Administration using the production merchant ID, or submit Retrieve Transaction/Retrieve Order operation and verify the data.
Once you are satisfied with the recorded chargeback data, you can start recording chargeback information on the production environment.