Authorize
The AUTHORIZE transaction verifies your payer's card details, checks that your payer has sufficient funds available against their line of credit, and attempts to reserve the requested funds.
The credit limit of the payer is reduced by the authorized amount, and the funds are reserved for a period of time, in most cases 5 to 8 days, as determined by the card scheme and the payer's card issuing rules. For a successful authorization, the gateway returns result = SUCCESS in the transaction response.
The authorization does not debit funds from your payer's account, but reserves the total order amount, ready for the CAPTURE transaction to debit the card and transfer the funds to your account. AUTHORIZE transactions do not appear on the payer's account statement as opposed to CAPTURE transactions.
Many online banking systems now provide notification of authorization activity.
An AUTHORIZE transaction can be an initial transaction, with no prior related transactions, or a subsequent transaction following a VERIFY or AUTHENTICATE_PAYER. In the latter case, the card details in the VERIFY or AUTHENTICATE_PAYER requests must match AUTHORIZE.
If you capture an amount larger than the one you have authorized or if you capture an authorization you have performed outside the gateway, see Using Excessive Captures and Standalone Capture, respectively.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| HTTP Method | PUT |
{
"apiOperation": "AUTHORIZE",
"order": {
"amount": "100.00",
"currency": "EUR"
},
"sourceOfFunds": {
"token": "<token>"
}
}
Setting order certainty
You can indicate a certainty level on the authorization amount to be captured by providing the order.certainty field in the AUTHORIZE request. To do this, you must have the Change Order Certainty privilege enabled on your merchant profile by your payment service provider. You can set the field to either of the following values:
- Final
Full authorized amount is expected to be captured with one or more captures within the mandated time, typically 7 days. The order will only be canceled in exceptional circumstances, for example, a payer canceled the purchase. Providing this value on your transaction can qualify the transaction for lower processing fees.
- Estimated
Amount authorized is an estimate of the amount to be captured within the mandated time, typically 30-31 days. It is possible that the amount captured will be less or not captured at all, or the authorization can be canceled. Providing this value on your transaction can cost you higher processing fees.
The request is rejected if you do not have the privilege to change the order certainty and the value you provide in this field does not match the default order certainty value configured on your merchant profile.
Reversing authorizations
The gateway can reverse outstanding authorization amounts for uncaptured, partially captured, or expired authorizations, where supported for the acquirer. This allows you to comply with the card scheme requirements for full and partial reversals.
- Uncaptured authorizations
If you do not want to capture the authorized amount after submitting an AUTHORIZE request, you must void your authorization by submitting a VOID request. Provide the transaction ID for the authorization to be voided in the
transaction.targetTransactionIdfield. - Partially captured authorizations
When submitting a CAPTURE request for an order, you can provide a CAPTURE amount lower than the authorized amount for the order
order.AuthorizedAmountdefined in your AUTHORIZE request. If you do not intend to capture the remaining authorized amount, you can void the outstanding authorized amount, where supported for the acquirer. - Submit a VOID request with the transaction ID for the AUTHORIZE transaction to be voided in the
transaction.targetTransactionIdfield. Provide the expected number of CAPTURES for the order in the
order.expectedNumberOfCapturesfield in the CAPTURE request or through the Merchant Administration. If the total number of CAPTURES for the order, including the current CAPTURE, exceeds or equals the total expected number of CAPTURE requests, the gateway automatically triggers a VOID of the outstanding authorized amount, where this is supported for the acquirer.To allow the automatic trigger, you must have the Automatically Reverse Outstanding Authorization Amounts privilege enabled on your merchant profile by your payment service provider.
- Expired authorizations
Authorizations have a validity period after which they expire. The authorization validity period can be configured in the gateway for an acquirer, card type, and order certainty combination.
When you submit an Authorize request to the gateway, the gateway determines the authorization expiry date and time based on the configured authorization validity period, using card type, acquirer, order certainty combination.
Where supported for the acquirer, the authorization expiry is returned in the
authorizationResponse.autoExpiryfield in theRetrieve Transactionoperation response. This field contains the date and time the gateway will automatically expire the authorization.Once the authorization validity period expires, the gateway:
- Automatically attempts to void the authorization and release funds back to the payer, where supported for the acquirer. To allow this, your payment service provider must enable the Automatically Reverse Expired Authorizations privilege on your merchant profile.
If the order is partially captured, and if your acquirer supports voiding authorizations for partial captures, then the gateway will attempt to void or reverse the outstanding authorization amount.
- Rejects any Capture requests against the order.
- Automatically attempts to void the authorization and release funds back to the payer, where supported for the acquirer. To allow this, your payment service provider must enable the Automatically Reverse Expired Authorizations privilege on your merchant profile.
- Updating authorizations
- Deferring authorizations
- If you are a merchant accepting card-present payments on a POS terminal where the POS authorization system is offline.
- If you are a retail merchant accepting payments through telephone orders where the POS authorization system is offline.
You can attempt to void, reverse the outstanding authorization amount in two ways:
For example, if you provide order.expectedNumberOfCaptures = 2 in the first CAPTURE request, the gateway automatically reverses the remaining authorized amount upon processing the second CAPTURE request.
If you decrease the expected number of captures in the subsequent CAPTURE requests, for example, update order.expectedNumberOfCaptures = 1 in the second CAPTURE request, the gateway automatically reverses the remaining authorized amount upon processing the second CAPTURE request.
This is because 2, the total number of CAPTURES for the order, including the current CAPTURE, exceeds 1, the expected number of CAPTURES. However, if you increase the expected number of CAPTURES in subsequent CAPTURE requests, for example, update order.expectedNumberOfCaptures = 3 in the second CAPTURE request, the gateway does not reverse the outstanding amount until upon receiving the third CAPTURE request.
The gateway allows you to extend the authorization period and optionally increase or decrease the authorization amount for valid authorizations, if supported for the acquirer. To do this, your payment service provider must enable the Update Authorization privilege on your merchant profile. For more information, see Update Authorization.
You can defer an authorization if you are unable to submit an AUTHORIZE or PAY transaction at the time it was completed with the payer. The failure may be due to connectivity, system issues, or other limitations that require you to submit the authorization downstream when the system is back online.
Identifying deferred authorizations is mandatory to comply with Visa scheme requirements.
Following are a few scenarios where you must indicate the authorization as a deferred authorization for Visa card payments.
To defer an authorization, provide the transaction.deferredAuthorization field in the AUTHORIZE, PAY, or STANDALONE CAPTURE request and set its value to TRUE. If you do not provide this field, the default value is FALSE.
Capture
The Capture transaction, also known as bill or complete uses the authorization obtained after the initial AUTHORIZE operation to transfer funds from the payer's account to your account. A CAPTURE must always be preceded by a successful authorization. The currency used when capturing an amount must match the currency used in the authorization transaction.
Captures are normally batched by the gateway or by the acquirer's host, so the funds are not effectively transferred until the batch is closed and the settlement occurs.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| HTTP Method | PUT |
{
"apiOperation": "CAPTURE",
"transaction": {
"amount": "100.00",
"currency": "EUR"
}
}
To capture an Authorization performed outside the gateway see Standalone Capture.
Using excessive captures
The total amount you capture can exceed the original authorized amount if the Perform Excessive Captures privilege is enabled on your merchant profile.
Excessive capture is a variation of the CAPTURE transaction where you perform a capture for an amount greater than the authorized amount. The excess permitted is specified as a percentage of the original authorized amount and is determined by your payment service provider.
When you submit an excessive CAPTURE request, the gateway automatically attempts to update the authorization amount to the amount you want to capture. If the acquirer supports updating authorizations, the gateway submits the UPDATE AUTHORIZATION request to the acquirer. If not, the gateway automatically approves an authorization update, up to the excessive capture limit configured for your merchant profile.
If you do not want the gateway to attempt to update the authorization before submitting the capture to the acquirer, set the transaction.authorizationAjustmentAction field to NO_ACTION in the request.
Chargeback
A CHARGEBACK transaction occurs when a payer disputes a payment made to you. For example, the goods were not received or the payer did not authorize the payment to you.
Your payment service provider can import the details of the chargeback transactions into the gateway so that they are available to you for search and reporting purposes. Your payment service provider can record each chargeback transaction against the original order or create a new order with a standalone chargeback transaction.
- If you share your SE Number or Bank merchant ID, the identifier allocated to you by your acquiring bank, across multiple merchant profiles, a standalone chargeback transaction is created for each profile.
- The gateway records the chargeback transactions for information purposes only, the transaction is not sent for downstream processing to the acquirer.
The gateway can create multiple chargeback transactions for a single order. You can perform subsequent transactions on an order containing a chargeback transaction, for example, voids or refunds.
A successfully recorded CHARGEBACK transaction returns the following fields in the RETRIEVE TRANSACTION and RETRIEVE ORDER transaction responses:
order.statusWhen a chargeback transaction is created, the status of the corresponding order is updated to represent that there is a dispute that a payer has raised.
order.statusDISPUTED indicates that a dispute is raised but no funds are moved yet.
order.statusCHARGEBACK_PROCESSED indicates that a chargeback claim is processed and funds will be moved either from or to the merchant account.
order.chargeback.amount- Chargeback amount.order.chargeback.currency- Chargeback currency.transaction.dispute object- Information about the chargeback dispute, for example dispute event and date.transaction.type- CHARGEBACKtransaction.source- SERVICE_PROVIDERgatewayEntryPoint- SERVICE_PROVIDER_API
Disbursement
With the DISBURSEMENT transaction, you can send funds to a payer's card account, for example, for gaming or betting winnings or when paying towards a payer's credit card bill.
In a DISBURSEMENT request, the payer's billing and shipping details are not required and the Card Security Code (CSC) validation is not applicable.
A DISBURSEMENT transaction can be an initial transaction, with no prior related transactions, or a subsequent transaction following a VERIFY used to verify the payer's account details.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| HTTP Method | PUT |
{
"apiOperation": "DISBURSEMENT",
"disbursementType": "GAMING_WINNINGS",
"order": {
"amount": "100.00",
"currency": "EUR"
},
"sourceOfFunds": {
"token": "<token>"
}
}
Pay
The PAY transaction also known as purchase or sale combines an AUTHORIZE and CAPTURE into one message.
A single transaction authorizes the payment and transfers funds from your payer's account into your account at one go. You can provide an indicator in the PAY request to defer the authorization. For more information, see Deferring Authorizations.
A PAY transaction can be an initial transaction, with no prior related transactions, or a subsequent transaction following a VERIFY used to verify the payer's account details. In the latter case, the card details in the VERIFY and PAY requests must match.
The order certainty level for a PAY transaction is set to FINAL. For more information, see Setting Order Certainty.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| HTTP Method | PUT |
{
"apiOperation": "PAY",
"order": {
"amount": "100.00",
"currency": "EUR"
},
"sourceOfFunds": {
"token": "<token>"
}
}
Using auto-capture
Auto-capture is a variant of the PAY transaction that allows a merchant to perform a PAY transaction with an acquirer that only supports AUTHORIZE and CAPTURE transactions.
When the gateway receives a PAY request and determines that the acquirer does not support it, the gateway automatically transforms the PAY request into an AUTHORIZE request, followed by an auto-triggered CAPTURE.
To do this, your payment service provider must enable the PAY privilege on your merchant profile. The transaction identifier for both, the AUTHORIZE and CAPTURE requests is the transaction identifier supplied by you in the original PAY request.
In the PAY response, the transaction.type field indicates the last transaction attempted to fulfill the request, AUTHORIZE or CAPTURE.
You can use the RETRIEVE TRANSACTION operation to retrieve the results of an auto-capture. The result of the last transaction attempted to fulfill the request is returned.
You can void an auto-captured PAY transaction using the VOID transaction. When you send a VOID request for an auto-capture, the gateway:
- Attempts a VOID for the CAPTURE transaction.
- If that first VOID is successful, a second VOID is attempted for the AUTHORIZATION transaction. If the first VOID is unsuccessful, the response indicates that the VOID failed, and no second VOID is attempted.
transaction.authorizationCode, in the request. If the referral succeeds, the gateway automatically performs the CAPTURE request for it.
Referral
The REFERRAL transaction is needed when an AUTHORIZE or PAY transaction fails with a Refer to Issuer acquirer response that is provided in the response.gatewaycode field of the response.
The payer must provide additional information in order for the issuer to approve the transaction and provide an authorization code or manual authorization ID.
Use the REFERRAL transaction to resubmit the referred initial transaction as a new AUTHORIZE or PAY transaction with an authorization code obtained from the issuer.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| HTTP Method | PUT |
{
"apiOperation": "REFERRAL",
"transaction": {
"authorizationCode": "123456"
}
}
Refund
With the REFUND transaction, you can credit funds for an existing order back to the payer's account if, for example, they return unwanted, incorrect, or faulty goods. Refunds can only be performed where a fund transfer is completed through a PAY, CAPTURE, or STANDALONE CAPTURE transaction.
You can perform any number of REFUND transactions on the original transaction but you cannot refund more than the total amount that is obtained through the PAY or CAPTURE transactions associated with the order.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| HTTP Method | PUT |
{
"apiOperation": "REFUND",
"transaction": {
"amount": "100.00",
"currency": "EUR"
}
}
Using refund authorization
Before submitting your refund request to the acquirer for clearing and settlement, by default, the gateway automatically attempts to authorize your refund with the issuer, where supported by the acquirer.
This allows the issuers to verify the card details provided in the refund request to ensure that the refund is successful.
The refund authorization is performed online and returns a response in real time. This has many benefits:
- You get immediate notification from card issuers if the refund cannot be made and can take appropriate actions. For example, if the card used for the REFUND transaction is no longer valid, the issuer rejects the refund authorization. You can contact the payer to arrange a refund through a different payment instrument.
- Card issuer gets immediate notification of the refund request, which allows issuers to instantly display information about the refund to the payer. It also allows them to manage payer queries or complaints effectively.
If you do not want the gateway to submit authorization requests for your REFUND transactions, contact your payment service provider to enable the Enable Refunds without Authorizations privilege. Even when you have this privilege enabled, you can request authorization on a specific refund by setting the action.refundAuthorization field to true in the REFUND request.
If the refund authorization is successful, the gateway proceeds with the refund. The outcome of the REFUND transaction is returned in the response. You can view the authorization code received from the issuer in the Merchant Administration.
Refunding a specific capture
If multiple captures are performed for a single order, you must identify which captures to refund when refunding all or part of the order:
- To refund a specific capture in the Merchant Administration, select the targeted capture in the Refund section, and enter the refund amount. If the order has multiple captures, a new UI window is displayed to allow you to select which capture to refund.
- To refund a specific capture with an API request, include the
transaction.targetTransactionldfield in the request to identify the specific capture to be refunded and set it to the transaction ID of the applicable CAPTURE request.
Using excessive refunds
The total refunded amount for an order can exceed the amount that is successfully captured, if the Perform Excessive Refunds privilege is enabled on your merchant profile.
The excess permitted over the captured amount for API transactions can be configured on a per currency basis on the Admin > Integration Settings page in the Merchant Administration. If you do not set an excessive refund limit for a currency, excessive refunds for orders in this currency are rejected.
When submitting a refund, the total refunded amount for the order, inclusive of the attempted refund must not exceed the total amount captured for the order by more than the maximum excess permitted.
For example, if you are submitting an excessive refund through API for an order where the total captured amount is 100 USD and you have set the excessive refund limit for API transactions as 20 USD, you can refund up to 120 USD.
For refunds submitted through the Merchant Administration, the excess permitted for the order is checked against the refund limit set for the operator on the Admin > Operators > Operator Details page in the Merchant Administration.
Standalone capture
A STANDALONE CAPTURE transaction is a CAPTURE where the authorization was performed outside the gateway. When submitting a STANDALONE CAPTURE request to the gateway, you must provide the externally generated authorization code in the transaction.authorizationCode field.
You must also provide all the card details that you would usually provide as mandatory fields in an AUTHORIZATION transaction, as the gateway does not yet have that information due to the external authorization.
You can submit a STANDALONE CAPTURE if you have the Perform Stand Alone Captures privilege enabled on your merchant profile.
transaction.source field is set to CARD_PRESENT. This allows STANDALONE CAPTURE transactions to be performed on card-present payments authorized offline.If you have to capture an amount larger than the one you have authorized, see Using Excessive Captures.
You can provide an indicator in the STANDALONE CAPTURE request to indicate that the external authorization is a deferred authorization, when needed. For more information, see Deferring Authorizations.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| HTTP Method | PUT |
{
"apiOperation": "CAPTURE",
"order": {
"amount": "100.00",
"currency": "EUR"
},
"sourceOfFunds": {
"token": "<token>"
},
"transaction": {
"authorizationCode": "123456",
"amount": "100.00",
"currency": "EUR"
},
}
Standalone refund
A STANDALONE REFUND transaction is a REFUND transaction that allows you to transfer funds from your account back to the payer without a previous purchase. You can use a STANDALONE REFUND when you want to credit the payer's account without associating that credit to a previous transaction.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| HTTP Method | PUT |
{
"apiOperation": "REFUND",
"sourceOfFunds": {
"token": "<token>"
},
"transaction": {
"amount": "100.00",
"currency": "EUR"
}
}
Update authorization
The UPDATE AUTHORIZATION transaction allows you to:
- Extend the validity period of an existing authorization.
- Optionally increase or decrease the authorization amount.
If you want to only extend the authorization period, do not submit the transaction.amount field in the request. The updated authorization expiry date and time is returned in the authorizationResponse.autoExpiry field in the RETRIEVE TRANSACTION response.
If you provide a transaction amount that is greater than the amount of the existing authorization, the authorization amount is updated to the new amount. For example, if the existing authorization amount is 100 USD, and you provide 120 USD as the transaction amount in the UPDATE AUTHORIZATION request, the new authorization amount available for capture is 120 USD.
If you provide a transaction amount that is less than the amount of the existing authorization, the authorization amount is updated to the new amount. For example, if the existing authorization amount is 100 USD, and you provide 80 USD as the transaction amount in the UPDATE AUTHORIZATION request, the new authorization amount available for capture is 80 USD.
The gateway automatically processes a reversal request for the remaining authorization amount of 20 USD, where supported for the acquirer.
The gateway can update an existing authorization only if the following conditions are met:
- Your merchant profile on the gateway must be enabled for the Update Authorization privilege by your payment service provider.
- Order currency must match the currency on the existing authorization.
- Existing authorization must be valid, successful, and fully approved.
- For Mastercard card transactions, increasing the authorization amount automatically extends the authorization validity period. For other card brands, the scheme rules determine the effect on the validity period.
- The UPDATE AUTHORIZATION operation is not fully supported for S2I acquirers of any card brand. They can only decrease the authorization amount using this operation.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| HTTP Method | PUT |
{
"apiOperation": "UPDATE_AUTHORIZATION"
}
Managing order totals
After a successful UPDATE AUTHORIZATION request, for a card or PayPal, the order amount, order.amount and the total authorized amount, order.totalAuthorizedAmount are updated to the transaction amount, transaction.amount of the UPDATE AUTHORIZATION transaction.
This applies regardless of whether the UPDATE AUTHORIZATION transaction was submitted to the acquirer or automatically approved by the gateway, response.gatewayCode = APPROVED_AUTO.
If you choose to bypass the authorization update for an excessive CAPTURE request, by submitting transaction.authorizationAdjustmentActions = NO_ACTION, see Using Excessive Captures, and the gateway submits an excessive CAPTURE to the acquirer, the order totals are not updated.
response.gatewayCode = APPROVED_AUTO, is only applicable when the provided amount is greater than the amount of the existing authorization.Managing order subtotals
You can provide the following subtotal amounts in the UPDATE AUTHORIZATION request for card or PayPal payments:
- order.itemAmount
- order.shippingAndHandlingAmount
- order.taxAmount
- order.discount.amount (card payments only)
- order.gratuityAmount (card payments only)
Providing order.cashbackAmount in the UPDATE AUTHORIZATION request is not supported.
The gateway does not validate if the subtotal amounts add up to the transaction.amount, order.amount.
Surcharging
You can update a surcharge amount in the UPDATE AUTHORIZATION request using either of the following fields:
order.merchantCharge.amount- Use this field if you are providing a pre-calculated surcharge amount.order.merchantCharge.type- Set this field to SURCHARGE to indicate that the charge type is a surcharge.order.netAmount- Use this field if the gateway calculates the surcharge amount based on your surcharging rules. The net amount is the amount payable for the order before surcharging is applied.
order.surchargeAmount is not supported and requests with this field are rejected. If you provide order.netAmount on a PayPal payment, the transaction is processed without a surcharge being applied.Verify
The VERIFY transaction allows you to verify the payer's account details before performing a PAY or AUTHORIZE transaction. It verifies the payment details using the verification method supported by the acquirer. For example, if the gateway determines that the acquirer supports Address Verification Service (AVS), the gateway sends to the acquirer an AVS Only transaction with the transaction amount of zero and the address details of the payer to get the verification result.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| HTTP Method | PUT |
{
"apiOperation": "VERIFY",
"order": {
"currency": "EUR"
},
"sourceOfFunds": {
"token": "<token>"
}
}
Void
The VOID transaction attempts to immediately remove or reverse a previous transaction request.
You can void AUTHORIZE, CAPTURE, PAY, REFUND, STANDALONE CAPTURE, STANDALONE REFUND, and UPDATE AUTHORIZATION transactions.
For an AUTHORIZE, a VOID immediately releases any reserved funds. For all other transaction types, a VOID prevents the fund transfer from occurring.
For all other transaction types, a VOID prevents the fund transfer from occurring. Void transactions may only be successful, when they are sent not long after the original transaction.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| HTTP Method | PUT |
{
"apiOperation": "VOID",
"transaction": {
"targetTransactionId": "<ID_of_transaction_to_be_voided>"
}
}