Update Authorization
Request to update an existing authorization. If successful, this operation allows you to extend the authorization period and/or update the authorized amount for this order.
URL | https://test-gateway.mastercard.com/api/rest/version/81/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
HTTP Method | PUT |
Authentication |
This operation requires authentication via one of the following methods:
|
Request Parameters
apiOperation String =UPDATE_AUTHORIZATION FIXED
Existence
FIXED
Fixed value
UPDATE_AUTHORIZATION
Validation Rules
Any sequence of zero or more unicode characters.
XSD type
string
apiOperation String =UPDATE_AUTHORIZATION FIXED
Existence
FIXED
Fixed value
UPDATE_AUTHORIZATION
Validation Rules
Any sequence of zero or more unicode characters.
XSD type
string
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.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100
initiator.userId String = OPTIONAL
The person who initiated this transaction.
This field is automatically populated by the gateway if the transaction was created via Merchant Administration (gatewayEntryPoint=MERCHANT_ADMINISTRATION) or Merchant Manager (MERCHANT_MANAGER).
In this case this is the name that the person used to log in to Merchant Administration or Merchant Manager respectively.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
256
order = OPTIONAL
Information about the order associated with this transaction.
Fixed value
order.custom String = OPTIONAL
Information about this order that is of interest to you.
For example order.custom.X, where 'X' is defined by you and must be less than 100 characters from the set A-Z, a-z, 0-9. For example, order.custom.salesRegion. You can specify up to 50 such fields. They are not sent to acquirers.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
250
order.discount.amount Decimal = OPTIONAL
The total amount of the discount you have applied to the order.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
JSON type
String
minimum length
1
maximum length
14
order.dutyAmount Decimal = OPTIONAL
The duty amount (also known as customs tax, tariff or dues) for the order.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3
order.gratuityAmount Decimal = OPTIONAL
The amount the payer has chosen to provide as a gratuity or tip in addition to the amount they are paying for the goods or services they are purchasing from you.
If you provide a gratuity amount, you must include it in the amount you provide in transaction.amount or order.netAmount.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
JSON type
String
minimum length
1
maximum length
14
order.merchantCharge = OPTIONAL
Information about additional fees that you are charging the payer for processing the payment for this order, for example, a surcharge.
Fixed value
order.merchantCharge.amount Decimal = OPTIONAL
The amount of the additional fee that you are charging the payer.
If you provide a charge amount, you must include it in the total amount for the order.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
JSON type
String
minimum length
1
maximum length
14
order.merchantCharge.type Enumeration = COMPULSORY
The type of the additional fee that you are charging the payer.
Existence
COMPULSORY
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
SURCHARGE
A fee that covers your cost of accepting accepting a payment method.
order.netAmount Decimal = OPTIONAL
The amount payable for the order before merchant charge amount is applied.
If you specify a net amount the gateway will calculate the merchant charge amount for you based on the charge type (order.merchantCharge.type) provided in the request. Alternatively, you can specify the merchant charge amount (order.merchantCharge.amount) yourself.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
JSON type
String
minimum length
1
maximum length
14
order.reference String = OPTIONAL
An optional identifier for the order.
For example, a shopping cart number, an order number, or an invoice number.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40
order.shippingAndHandlingAmount Decimal = OPTIONAL
The total shipping and handling amount for the order, including taxes on the shipping and/or handling.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
JSON type
String
minimum length
1
maximum length
14
order.shippingAndHandlingTaxAmount Decimal = OPTIONAL
The tax amount levied on the shipping and handling amount for the order.
This amount is included in the shipping and handling amount provided in field order.shippingAndHandlingAmount.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3
order.shippingAndHandlingTaxRate Decimal = OPTIONAL
The tax rate applied to the shipping and handling amount for the order to determine the shipping and handling tax amount.
For a tax rate of 2.5% provide 0.025.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000000000
minimum value
0
maximum post-decimal digits
4
order.taxAmount Decimal = OPTIONAL
The total tax amount for the order if the Authorization for the order has successfully been updated.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
JSON type
String
minimum length
1
maximum length
14
partnerSolutionId String = OPTIONAL
If, when integrating with the gateway, you are using a solution (e.g. a shopping cart or e-commerce solution) provided, supported or certified by your payment service provider, enter the solution ID issued by your payment service provider here.
If your payment service provider has not provided you with a solution ID, you should ignore this field.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40
responseControls = OPTIONAL
Container for fields that control the response returned for the request.
Fixed value
responseControls.sensitiveData String = OPTIONAL
Indicates how sensitive data is returned in the response.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50
transaction = OPTIONAL
Information about this transaction.
Fixed value
transaction.amount Decimal = OPTIONAL
You need to provide this field if you want to change the authorized amount for this order.
If you only want to extend the validity period of the Authorization, you do not need to provide the field.
The transaction amount expressed as a decimal number in the units of the currency. For example 12.34 in USD is the amount 12 dollars and 34 cents.
The order amount for the order will be updated to the new authorized amount.
The transaction amount expressed as a decimal number in the units of the currency. For example 12.34 in USD is the amount 12 dollars and 34 cents.
The order amount for the order will be updated to the new authorized amount.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
JSON type
String
minimum length
1
maximum length
14
transaction.currency Upper case alphabetic text = OPTIONAL
The currency of the transaction expressed as an ISO 4217 alpha code, e.g. USD.
Existence
OPTIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
JSON type
String
minimum length
3
maximum length
3
transaction.merchantNote String = OPTIONAL
Your note about this transaction.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
250
transaction.reference String = OPTIONAL
An optional identifier for this transaction.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40
{merchantId} Alphanumeric + additional characters COMPULSORY
The unique identifier issued to you by your payment provider.
Existence
COMPULSORY
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '-', '_'
XSD type
string
minimum length
1
maximum length
40
{orderid} String COMPULSORY
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 you create using your merchant profile.
Existence
COMPULSORY
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40
{transactionid} String COMPULSORY
Unique identifier for this transaction to distinguish it from any other transaction on the order.
An order can have transactions representing:
If you attempt an operation and it fails (eg you try to PAY on a card with no funds), then you need a new id for each retry.
- Movement of money. For example, payments and refunds.
- Validations. For example, account verification or 3-D Secure authentication of the payer.
- Undoing other transactions. For example, voiding a payment transaction.
- Chargebacks.
- Fees from your payment service provider.
If you attempt an operation and it fails (eg you try to PAY on a card with no funds), then you need a new id for each retry.
Existence
COMPULSORY
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40
Response Parameters
browserPayment = CONDITIONAL
Information used to manage interactions with the payment provider if you are offering your payment page on a website or are redirecting the payer's browser to the provider's website.
If you are offering your payment page in an app or are redirecting the payer to the provider's app, use the appPayment parameter group.
Fixed value
browserPayment.redirectUrl Url = CONDITIONAL
The URL to which you must redirect the payer's browser to complete the payment when using the payment provider's website.
If you are redirecting the payer to the payment provider's app use appPayment.redirectUrl.
If you want to present the payment provider's checkout flow in a modal window on top of your payment page, use the functions provided in the JavaScript library instead.
Existence
CONDITIONAL
Fixed value
Validation Rules
Ensure that this is a valid URL according to RFC 1738.
JSON type
String
merchant Alphanumeric + additional characters = Always Provided
The unique identifier issued to you by your payment provider.
Existence
Always Provided
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '-', '_'
JSON type
String
minimum length
1
maximum length
40
order = Always Provided
Information about the order associated with this transaction.
Fixed value
order.amount Decimal = Always Provided
The total amount for the order. This is the net amount plus any merchant charge amounts.If you provide any sub-total amounts, then the sum of these amounts (order.itemAmount, order.taxAmount, order.shippingAndHandlingAmount, order.cashbackAmount, order.gratuityAmount, order.merchantCharge.amount and order.dutyAmount), minus the order.discountAmount must equal the net amount.
The value of this field in the response is zero if payer funds are not transferred.
Existence
Always Provided
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3
order.creationTime DateTime = Always Provided
Indicates the date and time the gateway considers the order to have been created.
Existence
Always Provided
Fixed value
Validation Rules
An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"
JSON type
String
order.currency Upper case alphabetic text = Always Provided
The currency of the order expressed as an ISO 4217 alpha code, e.g. USD.
Existence
Always Provided
Fixed value
Validation Rules
Data must consist of the characters A-Z
JSON type
String
minimum length
3
maximum length
3
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.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40
order.lastUpdatedTime DateTime = Always Provided
Indicates the date and time the gateway considers the order to have last been updated.
Existence
Always Provided
Fixed value
Validation Rules
An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"
JSON type
String
order.merchantAmount Decimal = Always Provided
The total amount for the order in order.merchantCurrency units.
This is derived from the rate quote and order.amount for this order when Multi-Currency Pricing was used.
Existence
Always Provided
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3
order.merchantCurrency Upper case alphabetic text = Always Provided
The currency in which you priced your inventory for this order, expressed as an ISO 4217 alpha code, e.g. USD.
This value (along with merchantAmount) is applicable if you are doing Multi-Currency Pricing, as it gives you a consistent currency across all your orders that involve foreign exchange (FX).
If there is FX on this order, this is based on the rate quote you provided on the payment transactions, if not then this is the order.currency.
If there is FX on this order, this is based on the rate quote you provided on the payment transactions, if not then this is the order.currency.
Existence
Always Provided
Fixed value
Validation Rules
Data must consist of the characters A-Z
JSON type
String
minimum length
3
maximum length
3
order.totalAuthorizedAmount Decimal = Always Provided
The amount that has been successfully authorized for this order.
Existence
Always Provided
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3
order.totalCapturedAmount Decimal = Always Provided
The amount that has been successfully captured for this order.
Existence
Always Provided
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3
order.totalDisbursedAmount Decimal = Always Provided
The amount that has been successfully disbursed for this order.
Existence
Always Provided
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3
order.totalRefundedAmount Decimal = Always Provided
The amount that has been successfully refunded for this order.
Existence
Always Provided
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3
response = Always Provided
Fixed value
response.gatewayCode Enumeration = Always Provided
Summary of the success or otherwise of the operation.
Existence
Always Provided
Fixed value
Validation Rules
JSON type
String
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_AUTO
The transaction was automatically approved by the gateway. it was not submitted to the acquirer.
APPROVED_PENDING_SETTLEMENT
Transaction Approved - pending batch settlement
AUTHENTICATION_FAILED
Payer authentication failed
AUTHENTICATION_IN_PROGRESS
The operation determined that payer authentication is possible for the given card, but this has not been completed, and requires further action by the merchant to proceed.
BALANCE_AVAILABLE
A balance amount is available for the card, and the payer can redeem points.
BALANCE_UNKNOWN
A balance amount might be available for the card. Points redemption should be offered to the payer.
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. The payer cannot redeem points.
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. Points redemption should not be offered to the payer.
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.
Existence
Always Provided
Fixed value
Validation Rules
JSON type
String
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
transaction = Always Provided
Information about this transaction.
Fixed value
transaction.amount Decimal = Always Provided
The total amount for the transaction.
Existence
Always Provided
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3
transaction.currency Upper case alphabetic text = Always Provided
The currency of the transaction expressed as an ISO 4217 alpha code, e.g. USD.
Existence
Always Provided
Fixed value
Validation Rules
Data must consist of the characters A-Z
JSON type
String
minimum length
3
maximum length
3
transaction.id String = Always Provided
Unique identifier for this transaction to distinguish it from any other transaction on the order.
An order can have transactions representing:
If you attempt an operation and it fails (eg you try to PAY on a card with no funds), then you need a new id for each retry.
- Movement of money. For example, payments and refunds.
- Validations. For example, account verification or 3-D Secure authentication of the payer.
- Undoing other transactions. For example, voiding a payment transaction.
- Chargebacks.
- Fees from your payment service provider.
If you attempt an operation and it fails (eg you try to PAY on a card with no funds), then you need a new id for each retry.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40
transaction.type Enumeration = Always Provided
Indicates the type of action performed on the order.
Existence
Always Provided
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
AUTHENTICATION
Authentication
AUTHORIZATION
Authorization
AUTHORIZATION_UPDATE
Authorization Update
CAPTURE
Capture
CHARGEBACK
Chargeback
DISBURSEMENT
Disbursement
FUNDING
The transaction transfers money to or from the merchant, without the involvement of a payer. For example, recording monthly merchant service fees from your payment service provider.
PAYMENT
Payment (Purchase)
REFUND
Refund
REFUND_REQUEST
Refund Request
VERIFICATION
Verification
VOID_AUTHORIZATION
Void Authorization
VOID_CAPTURE
Void Capture
VOID_PAYMENT
Void Payment
VOID_REFUND
Void Refund
Response parameters are the same as Transaction: Retrieve Transaction
error = CONDITIONAL
Information on possible error conditions that may occur while processing an operation using the API.
Fixed value
error.cause Enumeration = CONDITIONAL
Broadly categorizes the cause of the error.
For example, errors may occur due to invalid requests or internal system failures.
Fixed value
Validation Rules
JSON type
String
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 = CONDITIONAL
Textual description of the error based on the cause.
This field is returned only if the cause is INVALID_REQUEST or SERVER_BUSY.
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
1000
error.field String = CONDITIONAL
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.
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100
error.supportCode String = CONDITIONAL
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.
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100
error.validationType Enumeration = CONDITIONAL
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.
Fixed value
Validation Rules
JSON type
String
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 = CONDITIONAL
A system-generated high level overall result of the operation.
Fixed value
Validation Rules
JSON type
String
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.