Chargeback

Operation to create or update Orders with Chargeback transactions

GET https://paymentgateway.commbank.com.au/api/nvp/version/48

Authentication

This operation requires authentication via one of the following methods:


  • Certificate authentication.
  • To authenticate to the API two additional NVP parameters must be supplied in the request. Provide 'MSO.<your gateway MSO ID>' in the apiUsername field and your API password in the apiPassword field.

Request

Fields

apiOperation String = RECORD_CHARGEBACK FIXED

Any sequence of zero or more unicode characters.

correlationId String OPTIONAL

A transient identifier for the request, that can be used to match the response to the request.

The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.

Data can consist of any characters

Min length: 1 Max length: 100
mso Alphanumeric + additional characters REQUIRED

The identifier that uniquely identifies you or an MSO that has authorized you to use this operation on their behalf.

Data may consist of the characters 0-9, a-z, A-Z, '-', '_', ' ', '&', '+', '!', '$', '%', '.'

Min length: 1 Max length: 16
order.amount Decimal REQUIRED

The total amount of the order.

Provide this field when you set transaction.dispute.matchAction = STANDALONE or transaction.dispute.matchAction = MATCHED_FALLBACK.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
order.currency Upper case alphabetic text REQUIRED

The currency of the order expressed as an ISO 4217 alpha code, e.g. USD.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
order.customerOrderDate Date OPTIONAL

The date the payer placed the order.

Data must comply with ISO 8601 extended date format, yyyy-mm-dd.

order.owningEntity String OPTIONAL

Your identifier for the part of your organization that is responsible for the order.

You might provide this data when you want to track the accountability for the order. For example, store number, sales region, branch, or profit center

Data can consist of any characters

Min length: 1 Max length: 40
order.statementDescriptor OPTIONAL

Contact information provided by you for printing on payer's account statements.

order.statementDescriptor.address OPTIONAL

Descriptor address of the merchant.

order.statementDescriptor.address.city String OPTIONAL

The city portion of the address.

Data can consist of any characters

Min length: 1 Max length: 100
order.statementDescriptor.address.company String OPTIONAL

The name of the company associated with this address.

Data can consist of any characters

Min length: 1 Max length: 100
order.statementDescriptor.address.country Upper case alphabetic text OPTIONAL

The 3 letter ISO standard alpha country code of the address.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
order.statementDescriptor.address.postcodeZip Alphanumeric + additional characters OPTIONAL

The post code or zip code of the address.

Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'

Min length: 1 Max length: 10
order.statementDescriptor.address.stateProvince String OPTIONAL

The state or province of the address.

Data can consist of any characters

Min length: 1 Max length: 20
order.statementDescriptor.address.street String OPTIONAL

The first line of the address.

For example, this may be the street name and number, or the Post Office Box details.

Data can consist of any characters

Min length: 1 Max length: 100
order.statementDescriptor.address.street2 String OPTIONAL

The second line of the address (if provided).

Data can consist of any characters

Min length: 1 Max length: 100
order.statementDescriptor.name String OPTIONAL

Descriptor name of the merchant.

Data can consist of any characters

Min length: 1 Max length: 100
order.statementDescriptor.phone String OPTIONAL

Descriptor phone number of the merchant's business.

Data can consist of any characters

Min length: 1 Max length: 20
sourceOfFunds OPTIONAL

Information about the payment type selected by the payer for this payment and the source of the funds.

Depending on the payment type the source of the funds can be a debit or credit card, bank account, or account with a browser payment provider (such as PayPal).

For card payments the source of funds information may be represented by combining one or more of the following: explicitly provided card details, a session identifier which the gateway will use to look up the card details and/or a card token. Precedence rules will be applied in that explicitly provided card details will override session card details which will override card token details. Each of these may represent partial card details, however the combination must result in a full and complete set of card details. See Using Multiple Sources of Card Details for examples.

sourceOfFunds.provided OPTIONAL

Information about the source of funds when it is directly provided (as opposed to via a token or session).

For browser payments, the source of funds details are usually collected from the payer on the payment provider's website and provided to you when you retrieve the transaction details (for a successful transaction). However, for some payment types (such as giropay), you must collect the information from the payer and supply it here.

sourceOfFunds.provided.card OPTIONAL

Details as shown on the card.

sourceOfFunds.provided.card.expiry OPTIONAL

Expiry date, as shown on the card.

This field corresponds to EMV tag 5F24

sourceOfFunds.provided.card.expiry.month Digits OPTIONAL

Month, as shown on the card.

Months are numbered January=1, through to December=12.

Data is a number between 1 and 12 represented as a string.

sourceOfFunds.provided.card.expiry.year Digits OPTIONAL

Year, as shown on the card.

The Common Era year is 2000 plus this value.

Data is a string that consists of the characters 0-9.

Min length: 2 Max length: 2
sourceOfFunds.provided.card.nameOnCard String OPTIONAL

The cardholder's name as printed on the card.

Data can consist of any characters

Min length: 1 Max length: 256
sourceOfFunds.provided.card.number Masked digits OPTIONAL

Credit card number as printed on the card.

By default, the card number will be returned in 6.4 masking format, for example, 000000xxxxxx0000. If you wish to return unmasked card numbers, you must have the requisite permission, set responseControls.sensitiveData field to UNMASK, and authenticate your call to the API using certificate authentication.

Data is a string that consists of the characters 0-9, plus 'x' for masking

Min length: 9 Max length: 19
transaction REQUIRED

Information about this transaction.

transaction.acquirer REQUIRED
transaction.acquirer.additionalResponseData JSON Text OPTIONAL

Provides additional data provided by the acquirer in the transaction response that could be of interest to you.

It might provide additional information that may help you understand unexpected results or provide acquirer-specific response data.
For example, it could provide information about the results of validation of data by the issuer or card scheme of data you provided for card present transactions.
The data is provided as a series of name-value pairs where the name is the acquirer field and the value is exactly as provided by the acquirer.
For example, {"48.74.1":3, "48.74.2:5":48, "48.80":67}

Data is valid Json Format

Min length: 1 Max length: 4000
transaction.acquirer.id String REQUIRED

The ID for the acquirer used to process the transaction.

Data can consist of any characters

Min length: 1 Max length: 40
transaction.acquirer.merchantId String REQUIRED

An identifier allocated by an acquirer to the merchant.

This may also be referred to as the Card Acceptor Identification Code (CAIC), Card Acceptor ID (CAID), or Service Establishment Number (SE Number).

Data can consist of any characters

Min length: 1 Max length: 127
transaction.acquirer.transactionId String OPTIONAL

Identifier used by the acquirer to identify the transaction.

Data can consist of any characters

Min length: 1 Max length: 100
transaction.amount Decimal REQUIRED

The total amount for the transaction.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
transaction.authorizationCode ASCII Text OPTIONAL

Value generated by the issuing bank in response to a proposal to transfer funds.

Data consists of ASCII characters

Min length: 1 Max length: 100
transaction.currency Upper case alphabetic text REQUIRED

The currency of the transaction expressed as an ISO 4217 alpha code, e.g. USD.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
transaction.dispute REQUIRED

Information about the disputed transaction.

transaction.dispute.dateRecurringPaymentCancelled Date OPTIONAL

The date the payer notified the issuer to cancel a recurring payment that is being disputed.

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

transaction.dispute.deadlineDate Date OPTIONAL

The date by which the merchant must take action.

For example, if the acquirer has requested additional information (transaction.dispute.event = INFORMATION_REQUESTED), the merchant must provide a response by this date.

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

transaction.dispute.event Enumeration REQUIRED

The step in the dispute management process that triggered this transaction

Value must be a member of the following list. The values are case sensitive.

CHARGEBACK_DEBITED

The chargeback amount will soon be debited to the merchant's account.

CHARGEBACK_PENDING

The chargeback amount will soon be debited to the merchant's account. The merchant should ensure there is sufficient funds in the account.

CHARGEBACK_REVERSED

The chargeback amount that was debited has been credited back to the merchant's account.

INFORMATION_RECEIVED

The acquirer has received information requested from the merchant.

INFORMATION_REQUESTED

The issuer has requested additional information about a disputed transaction.

INFORMATION_REQUEST_OUTSTANDING

A chargeback is pending. Additional information requested from the merchant has not been received.

RECURRING_PAYMENT_CANCELLED

The payer has disputed a recurring payment transaction and it is cancelled. For example, the recurring payment amount was more than agreed.

transaction.dispute.eventDate Date OPTIONAL

The date of the event in the dispute management process described by transaction.dispute.event

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

transaction.dispute.match OPTIONAL

Parameters used by the gateway to match the chargeback transaction to the original transaction being disputed.

When transaction.dispute.matchAction = MATCHED, then the gateway will attempt to match this chargeback transaction to an existing financial transaction with these parameters. If no match is found then the gateway does not record the chargeback transaction.
When transaction.dispute.matchAction = STANDALONE, the gateway create a new order containing the chargeback transaction and does not attempt to match it to the original transaction.
When transaction.dispute.matchAction = MATCHED_FALLBACK, then the gateway will first attempt to match this chargeback transaction to an existing financial transaction with these parameters. If it cannot be matched, the gateway will create a new order containing the chargeback transaction. When the chargeback transaction can be matched to more than one merchant gateway profile, a new order will be created against each profile. When this occurs it will be noted in order.description.

transaction.dispute.match.acquirerTransactionId String OPTIONAL

Identifier used by the acquirer to identify the disputed transaction.

Data can consist of any characters

Min length: 1 Max length: 100
transaction.dispute.match.date Date OPTIONAL

The date of the disputed transaction.

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

transaction.dispute.match.stan Digits OPTIONAL

The System Trace Audit Number of the disputed transaction.

Data is a string that consists of the characters 0-9.

Min length: 1 Max length: 6
transaction.dispute.matchAction Enumeration REQUIRED

Indicates how you want the gateway to record the chargeback transaction.

Value must be a member of the following list. The values are case sensitive.

MATCHED

Create the chargeback transaction only if it can be matched to the original transaction being disputed.

MATCHED_FALLBACK

Attempt to match the chargeback transaction to the original transaction being disputed. If it cannot be matched, then create a new order containing the chargeback transaction.

STANDALONE

Do not match the chargeback transaction to the original transaction being disputed; create a new order containing the chargeback transaction.

transaction.dispute.reason ASCII Text OPTIONAL

A description of why the transaction is disputed.

Data consists of ASCII characters

Min length: 1 Max length: 100
transaction.dispute.reasonCode ASCII Text OPTIONAL

A code provided by the acquirer to indicate the reason for the chargeback.

Data consists of ASCII characters

Min length: 1 Max length: 10
transaction.merchantNote String OPTIONAL

Your note about this transaction.

Data can consist of any characters

Min length: 1 Max length: 250
transaction.receipt ASCII Text OPTIONAL

A unique reference generated by the acquirer for a specific merchant interaction.

The reference may be used when contacting the acquirer about a specific transaction.

Data consists of ASCII characters

Min length: 1 Max length: 100
transaction.reference String OPTIONAL

An optional identifier for this transaction.

Data can consist of any characters

Min length: 1 Max length: 40
transaction.terminal String OPTIONAL

The terminal configured at the processor/acquirer used to process the transaction.

Data can consist of any characters

Min length: 1 Max length: 16

Response

Fields

correlationId String CONDITIONAL

A transient identifier for the request, that can be used to match the response to the request.

The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.

Data can consist of any characters

Min length: 1 Max length: 100
disputeTransaction[n] ALWAYS PROVIDED

A list containing the merchant, order and transaction identifiers for the dispute transactions created.

disputeTransaction[n].merchant Alphanumeric + additional characters ALWAYS PROVIDED

The unique identifier issued to you by your payment provider.

This identifier can be up to 12 characters in length.

Data may consist of the characters 0-9, a-z, A-Z, '-', '_'

Min length: 1 Max length: 40
disputeTransaction[n].order.id String ALWAYS PROVIDED

A unique identifier for this order to distinguish it from any other order you create.

Use this identifier when referring to this order in subsequent transactions and in retrieval operations.
This value must be unique for every order created by your merchant profile.

Data can consist of any characters

Min length: 1 Max length: 40
disputeTransaction[n].transaction.id String ALWAYS PROVIDED

Unique identifier for this transaction to distinguish it from any other transactions on the order.

Data can consist of any characters

Min length: 1 Max length: 40
response.gatewayCode Enumeration ALWAYS PROVIDED

Summary of the success or otherwise of the proposed operation.

Value must be a member of the following list. The values are case sensitive.

ABORTED

Transaction aborted by payer

ACQUIRER_SYSTEM_ERROR

Acquirer system error occurred processing the transaction

APPROVED

Transaction Approved

APPROVED_PENDING_SETTLEMENT

Transaction Approved - pending batch settlement

AUTHENTICATION_FAILED

Payer authentication failed

BALANCE_AVAILABLE

A balance amount is available for the card.

BLOCKED

Transaction blocked due to Risk or 3D Secure blocking rules

CANCELLED

Transaction cancelled by payer

DECLINED

The requested operation was not successful. For example, a payment was declined by issuer or payer authentication was not able to be successfully completed.

DECLINED_AVS

Transaction declined due to address verification

DECLINED_AVS_CSC

Transaction declined due to address verification and card security code

DECLINED_CSC

Transaction declined due to card security code

DECLINED_DO_NOT_CONTACT

Transaction declined - do not contact issuer

DECLINED_INVALID_PIN

Transaction declined due to invalid PIN

DECLINED_PAYMENT_PLAN

Transaction declined due to payment plan

DECLINED_PIN_REQUIRED

Transaction declined due to PIN required

DEFERRED_TRANSACTION_RECEIVED

Deferred transaction received and awaiting processing

DUPLICATE_BATCH

Transaction declined due to duplicate batch

EXCEEDED_RETRY_LIMIT

Transaction retry limit exceeded

EXPIRED_CARD

Transaction declined due to expired card

INSUFFICIENT_FUNDS

Transaction declined due to insufficient funds

INVALID_CSC

Invalid card security code

LOCK_FAILURE

Order locked - another transaction is in progress for this order

NOT_ENROLLED_3D_SECURE

Card holder is not enrolled in 3D Secure

NOT_SUPPORTED

Transaction type not supported

NO_BALANCE

A balance amount is not available for the card.

PARTIALLY_APPROVED

The transaction was approved for a lesser amount than requested. The approved amount is returned in order.totalAuthorizedAmount.

PENDING

Transaction is pending

REFERRED

Transaction declined - refer to issuer

SUBMITTED

The transaction has successfully been created in the gateway. It is either awaiting submission to the acquirer or has been submitted to the acquirer but the gateway has not yet received a response about the success or otherwise of the payment.

SYSTEM_ERROR

Internal system error occurred processing the transaction

TIMED_OUT

The gateway has timed out the request to the acquirer because it did not receive a response.

UNKNOWN

The transaction has been submitted to the acquirer but the gateway was not able to find out about the success or otherwise of the payment. If the gateway subsequently finds out about the success of the payment it will update the response code.

UNSPECIFIED_FAILURE

Transaction could not be processed

result Enumeration ALWAYS PROVIDED

A system-generated high level overall result of the operation.

Value must be a member of the following list. The values are case sensitive.

FAILURE

The operation was declined or rejected by the gateway, acquirer or issuer

PENDING

The operation is currently in progress or pending processing

SUCCESS

The operation was successfully processed

UNKNOWN

The result of the operation is unknown

Errors

error

Information on possible error conditions that may occur while processing an operation using the API.

error.cause Enumeration

Broadly categorizes the cause of the error.

For example, errors may occur due to invalid requests or internal system failures.

Value must be a member of the following list. The values are case sensitive.

INVALID_REQUEST

The request was rejected because it did not conform to the API protocol.

REQUEST_REJECTED

The request was rejected due to security reasons such as firewall rules, expired certificate, etc.

SERVER_BUSY

The server did not have enough resources to process the request at the moment.

SERVER_FAILED

There was an internal system failure.

error.explanation String

Textual description of the error based on the cause.

This field is returned only if the cause is INVALID_REQUEST or SERVER_BUSY.

Data can consist of any characters

Min length: 1 Max length: 1000
error.field String

Indicates the name of the field that failed validation.

This field is returned only if the cause is INVALID_REQUEST and a field level validation error was encountered.

Data can consist of any characters

Min length: 1 Max length: 100
error.supportCode String

Indicates the code that helps the support team to quickly identify the exact cause of the error.

This field is returned only if the cause is SERVER_FAILED or REQUEST_REJECTED.

Data can consist of any characters

Min length: 1 Max length: 100
error.validationType Enumeration

Indicates the type of field validation error.

This field is returned only if the cause is INVALID_REQUEST and a field level validation error was encountered.

Value must be a member of the following list. The values are case sensitive.

INVALID

The request contained a field with a value that did not pass validation.

MISSING

The request was missing a mandatory field.

UNSUPPORTED

The request contained a field that is unsupported.

result Enumeration

A system-generated high level overall result of the operation.

Value must be a member of the following list. The values are case sensitive.

ERROR

The operation resulted in an error and hence cannot be processed.

Resources

Glossary FAQs