Authorizations (v1.0.3)
Currently the following 6 Authorization stage actionTypes are supported within the Accept Transactions API.
actionType definitions
actionType | definition |
| AUTH | The Authorization (final) message reserves the cardholder amount with Issuer bank. |
| PREAUTH | A PREAUTH reservation at Issuer bank is made when the final purchase amount is not yet known. Example is the amount reserved at hotel check-in for 2 day stay, before mini-bar usage has been take into account. |
| AUTH_REVERSAL | This is used to release the funds RESERVED on the cardholders’ account as a result of an APPROVED AUTHORIZATION. You must not use this follow-up action (operation) if you have already sent a CAPTURE on the transaction. |
| AUTH_INCREMENTAL | Adjusts the pre-authorized amount up. An incremental is a pre-authorization exclusive follow-up action (operation) that can be sent if the final amount is higher than the previously pre-authorized amount. Later on when capturing the transaction you must specify the last correct amount. |
| AUTH_REVERSAL_PARTIAL | Adjusts the pre-authorized amount down. A partial reversal is a pre-authorization exclusive follow-up action (operation) that can be sent to reverse parts of the pre-authorized amount. |
| AUTH_AND_CAPTURE | This action type Triggers card Dual message actionTypes “AUTH” and “CAPTURE”. This action can be used for Service "Purchase" and Service “Refund”. For this action no cancellation is available. |
Key Topics Authorizations
CardholderVerificationMethod and 3DSecure
SCA Exemptions and Merchant Initiated Transactions
Tokenization
Optional Transaction References
Payment Facilitator
Authorization Response
Service Account_Verification
Authorization requests - Basic mandatory
Basic mandatory Card Not Present Authorization request message fields for actionTypes AUTH and PREAUTH are listed in table below.
Request actionType AUTH - Basic mandatory fields
Category | Field | Presence | Comment |
| actionType | Mandatory | Type of action requested. Possible values: -“AUTH” -“PREAUTH” | |
| service | Mandatory | Service requested. The follow-up actions must have the same value as the initial action. Possible values: -“Purchase” -“Refund” -“AccountVerification” | |
| Identification | requestorId | Mandatory | Identifies the system or application that is sending the request. The values are allocated and assigned by Worldline. This field enables Worldline to distinguish the callers and to consider received information in their context (e.g. transaction references). |
| actionId | Mandatory | Identifier assigned by the caller to the transaction. The provided values must be unique with respect to the requestor. That is, two requests generated by the same requestor must have different identifiers. The only exception is a retry/reattempt where the original value must be taken. The identifier must be in UUID format. | |
| acquirerId | Mandatory | Identification of the acquirer, assigned by Worldline | |
| cardAcceptorId | Mandatory | Identification of the merchant, assigned by acquirer | |
| pspId | Conditional | Identification of the PSP, presence is mandated if assigned by Worldline. | |
| Financial | requestAmount (amount + currency) | Conditional | Amount for which authorization is requested. Presence is mandatory if Service is “Purchase” or “Refund” |
| Circumstance | actionDateTime | Mandatory | Date and time in local time zone when the authorization is requested |
| channel | Mandatory | Channel used by the cardholder to purchase the goods or services. Possible values: -“Poi” -“Ecommerce” -“MailOrder” -“PhoneOrder" | |
| Card | cardNumber | Mandatory | Primary Account Number of the card |
| cardExpiryDate | Mandatory | Card Expiration Date |
Cardholder Verification Method and 3DSecure
The Accept Transactions API supports two types of Cardholder Verification Methods: CCV2 and 3DSecure.
According to European Banking Authority (EBA) Payment Service Directive (PSD) 2, Strong Customers Authentication (SCA) is mandated for cards issued within the EEA.
Standard Cardholder Verification Method in EEA is to use EMV 3DSecure for accepting card transactions.
Cardholder Verification Method CCV2 does not qualify as SCA.
Some types of transactions may be exempted from the EBA SCA rule.
Request actionType AUTH - Cardholder Verification Method and 3DSecure fields
Category | Field | Presence | Comment |
| Circumstances | cardholderVerificationMethod | Mandatory | Indicates how the identity of the cardholder is verified. Possible values: -“Cvv2” -“3DSecure” -“OfflinePin” -“OnlinePin” -“Signature” -“None” |
| initiatorType | Mandatory | Indicates who has triggered the action. This could either be the cardholder or the merchant (acceptor). In the first case it is a Cardholder Initiated Transaction (CIT) and in the second a Merchant Initiated Transaction (MIT). Possible values: -“Cardholder” -“Acceptor” | |
| Card | cvv2 | Conditional | Card Verification Code/Card Verification Value printed on the back of the card. |
| 3DSecure | result | Conditional | Result of the 3D secure authentication process. Possible values: -“Full” -“Attempt” -“MerchantRisk” -“IssuerRisk” -“DataOnly” |
| dsTransactionId | Conditional | Transaction Id generated by the directory server (3D Secure version 2.x) | |
| version | Conditional | 3D version used. Possible values: -"V1" -"V2" | |
| authenticationValue | Conditional | Authentication Value according to directory server response of the ACS, which is either the Mastercard UCAF (AAV, SPA) or the VISA/Diners/UnionPay/JCB CAVV data. | |
| dsEci | Conditional | Electronic Commerce Indicator according to directory server response of the ACS. The values are scheme dependent. | |
| subVersion | Conditional | 3D Secure Sub-version used. Mandatory for Mastercard. EMV 3DS minor version should be used to populate the subversion. |
SCA Exemptions and Merchant Initiated Transactions
According to EBA PSD2, Strong Customers Authentication is mandated for cards issued within the EEA.
Under SCA-rules exemptions are possible for e.g. low value payments or Merchant Initiated Transactions.
Request actionType AUTH - PSD2 SCA Exemptions, Merchant Initiated Transactions, Tokenization, Card-On-File Initiation
Category | Field | Presence | Comment |
| Circumstance | cardholderVerificationMethod | Mandatory | Indicates how the identity of the cardholder is verified. Possible values: -“Cvv2” -“3DSecure” -“OfflinePin” -“OnlinePin” -“Signature” -“None” |
| scaExemptionCause | Conditional | In some cases, strong customer authentication is not needed. This field describes which exemption/exclusion is applicable for the transaction so that strong customer authentication is not needed. Possible values: -"LowValue” -“LowFraud” -“Delegation” -“TrustedAcceptor” -“SecureCorporate” -“Recurring” -“Mit” -“AuthenticationOutage” | |
| initiatorType | Mandatory | Indicates who has triggered the action. This could either be the cardholder or the merchant (acceptor). In the first case it is a Cardholder Initiated Transaction (CIT) and in the second a Merchant Initiated Transaction (MIT). Possible values: -“Cardholder” -“Acceptor” | |
| credentialStorage | Conditional | Indicates that a successful CIT transaction will result in storage of the card details for later use in card-on-file transactions. May only be used if initiatorType is “Cardholder” | |
| schemeTransactionId | Conditional | The Trace-ID/TID to be presented to the card scheme for a Merchant Initiated Transaction (MIT). It has to be the one returned for the Cardholder Initiated Transaction (CIT) with which the transaction series has been started and only needs to be provided if no other kind of transaction linking is applicable. | |
| mitCause | Conditional | In case no other indicator is applicable, this field states why the merchant triggers or will (later) trigger a transaction without involvement of the cardholder. Can be present for Merchant Initiated Transactions (MIT) and must be present for Cardholder Initiated Transactions (CIT) that start a series of recurring/installment/unscheduled non one-time transactions. Possible values: -“Unscheduled” -“Recurring” -“FixedRecurring” -“Installment” -“Resubmission” -“DelayedCharge” -“Reauthorization” -“NoShow” -“Deferred” -“Increment” | |
| Card | cvv2 | Conditional | Card Verification Code/Card Verification Value printed on the back of the card. |
| entryMode | Conditional | Method used to fetch the card data for the transaction. File has to be used for Merchant Initiated Transactions (MIT). Possible values: | |
| walletId | Conditional | Mastercard identification of the wallet provider (when a wallet is used for the transaction). See the Mastercard documentation for information about the presence of this field. | |
| Token | acceptorId | Conditional | Merchant ID presented to the cardholder at authentication/checkout time. |
| tavvData | Conditional | Token Authentication Verification Value cryptogram data in hex encoding (VISA TAVV or MasterCard DSRP cryptogram). |
In case of SCA exemption, the Accept Transactions API authorization must include in the scaExemptionCause field for which exemptions/exclusion reason is applied.
For transactions in scope of the SCA rule, the issuer decides on the need for SCA. When an acquirer requests authorization without prior SCA, the issuer may decline indicating SCA is needed (response code 65: soft decline). For example, when the acquirer requests SCA exemption for Low Value Payment, the issuer may decline the authorization because the limit is reached of consecutive payments without SCA.
After a soft decline, the merchant should initiate a 3DS authentication request. In this authentication request the merchant should indicate that the SCA is mandated. After successful authentication, the merchant can send a second authorization request. The second authorization request is a new authorization request and not a follow-up on the first authorization request (i.e. the second request makes no reference to the first request).
Disclaimer: The explanation found on this developer portal about SCA and SCA exemptions is not a comprehensive set of rules. Always consult the Card scheme rules for detail on card processing according to SCA-rule and SCA exemptions. Consult the European Banking Authority (EBA) websites for latest PSD II and SCA rules.
Merchant Initiated Transactions
The Accept Transactions API can accept Merchant Initiated Transactions (MIT). MIT are payments initiated by the merchant without the interaction of the payer.
Such payments require that:
- SCA is applied to the first transaction action mandating the Merchant to initiate payment(s) and
- There is an agreement between the payer and the merchant for the provision of products or services and potential costs associated with these. Such payments can happen in the following cases:
- Recurring Payments for fixed or variable amounts
- Merchant funded installments
- The final amount is higher than the amount used at authentication time. This can happen when additional charges are added to the initially agreed amount such as, a minibar in a hotel or fines with a rented car
Acquirers subject to PSD2 SCA are only allowed to apply Merchant-Initiated Transactions (MIT) when:
- The transaction is triggered by the merchant and the cardholder is typically off-session (off-session means the cardholder is no longer interacting with the merchant page or the merchant app), or
- The transaction is triggered by the merchant, as it could not have been triggered by the cardholder during checkout
Some examples:
- The final amount is not known during the checkout (for example, online groceries shopping)
- An event triggered the transaction after the checkout (for example, miscellaneous rental or service charges)
- The transaction is part of a recurring payment arrangement
- The transaction is broken down into different payments happening at different times (for example, installments, travel bookings, market places)
The field initiatorType should be used to indicate if the transaction is merchant initiated or cardholder initiated. If a cardholder initiated transaction is followed by a (series of) merchant initiated transactions, the field mitCause should be used to specify the type of MIT transactions for which the CIT transaction gives a mandate. The MIT-transactions must reference the CIT transaction with the field schemeTransactionId.
The mandatory field cardholderVerificationMethod should be set to "none" in case of a MIT-transaction.
Tokenization
The Accept Transactions API can accept the scheme token in field PAN and scheme dynamic cryptogram in field tavvData.
Card scheme network tokenization is the replacement of the cardholder’s primary account number (PAN) with an alternative number, referred to as a token.
Use of tokens reduces the risk of fraud in case of data breaches as the PANs are no longer stored. Tokens are used in various places such as wallets, but also by merchants who want to store the cardholders credentials (card-on-file). Tokens can be used in eCommerce transactions in the same way PANs are used. The number of digits of a Token is directly related to the number of digit of the PAN, e.g. a 16-digit token is created for a 16 digit PAN.
When used by merchants, tokens are unique to a merchant. To improve security, tokens are accompanied by a dynamic cryptogram (tavvData attribute in the Accept TRX API). Only the correct merchant can request a cryptogram associated with a unique token, and cryptograms may only be used once. The presence of the cryptogram in the authorization request helps the card scheme to verify that the transaction originated from the correct merchant.
Optional Transaction References
To facilitate tracking some additional PSP and merchant transaction references are available.
In case of a Refund the orginalTransactionId of the Purchase should be included to help connect the two transactions.
Request actionType AUTH – Optional transaction references
Category | Field | Presence | Comment |
| Identification | originalTransactionId | Conditional | Identification of the former transaction flow to which this transaction refers to. For example, with a Refund this would refer to the transactionId of Purchase AUTH. |
| pspReference | Optional | PSP’s reference for the transaction | |
| merchantReference | Optional | Merchant’s reference for the transaction. Typically the merchant’s orderId |
Payment Facilitator
In case of a Payment facilitator, the following acceptor fields are scheme mandated to be sent in for an authorization.
Request actionType AUTH - Payment Facilitator mandatory fields
Category | Field | Presence | Comment |
| Acceptor | merchantCategoryCode | Conditional | Only mandatory for Payment Facilitator |
| name | Conditional | Only mandatory for Payment Facilitator | |
| address | Conditional | Only mandatory for Payment Facilitator | |
| postalCode | Conditional | Only mandatory for Payment Facilitator | |
| city | Conditional | Only mandatory for Payment Facilitator | |
| state | Conditional | Only mandatory for Payment Facilitator | |
| countryCode | Conditional | Only mandatory for Payment Facilitator | |
| paymentFacilitatorId | Conditional | Only mandatory for Payment Facilitator | |
| independentSalesOrgId | Conditional | Only mandatory for ISO | |
| subMerchantId | Conditional | Only mandatory for Payment Facilitator or ISO | |
| schemeMerchantId | Conditional | For various reasons, the card scheme may assign a merchant id to the merchant. If that is the case, this field should be present. |
Authorization request response
In an (pre-)authorization response message, the following data elements can be present.
Response fields request actionType AUTH and PREAUTH
Category | Field | Presence | Comment |
| actionId | Mandatory | Echoed from the request | |
| transactionId | Mandatory | Unique identification assigned by Worldline to a transaction. Present in the first action response of a transaction and must be used in all subsequent action requests for the same transaction. | |
| declined | Mandatory | Boolean (true or false) whether the request has been completely declined or not. | |
| declineCause | Conditional | Reason why a request has been declined. Only present when the request has been declined completely. | |
| hints | Optional | Additional information for cardholder and/or merchant regarding transaction outcome and the next step to be taken. Examples of possible values: -‘DuplicateTransmission” -“TryAgainLater” | |
| tryAgainPeriod | Optional | If hints indicates that the merchant may try again later, this field can be present to advice the recommended time interval (in hours) after which at the earliest an additional attempt should be performed. | |
| responder | Mandatory | Indicates the entity which finally determined the outcome of the transaction. Possible values: -“Recipient” : Worldline -“Partner” : main entity (e.g. issuer or card scheme)involved by Worldline in transaction processing | |
| responderDetails | Mandatory | Response code provided by the entity which determined the final outcome of the transaction. In case this entity is Worldline, it is the internal result code of Worldline. This value is only provided for information purpose since the content is subject to change. That is, it must not be evaluated automatically. For decisions made by a partner this field provides the partners response code. For example, when Worldline directly interacts with the card scheme via ISO 8583 it is the DE 39 field content from the returned response message. | |
| paymentAccountReference | Conditional | A Payment Account Reference (PAR) is a unique value associated with a single PAN and attributed to all tokens associated with that PAN. A PAR can be used to link transactions containing PANs or tokens associated with the same underlying payment account. Present if returned by the card scheme. | |
| approvalCode | Conditional | Code assigned by the issuer when the authorization is approved | |
| schemeTransactionId | Conditional | Transaction id assigned by the scheme | |
| cvv2Result | Conditional | Result of the ccv2 verification. Possible values: -“Correct” -“Wrong” -“Unable” -“Omitted” -“Missing” -“Other” -“Unknown” | |
| Financial | responseAmount (amount + currency) | Conditional | Amount for which authorization is granted |
| Card | brand | Mandatory | (Acceptance) brand as derived by Worldline from the Card Number |
Authorization Reversal
The Authorization follow-up actions AUTH_REVERSAL (full reservation amount) and AUTH_REVERSAL_PARTIAL (part reservation amount) are used to reverse the effect of the authorization and release the funds reserved with an authorization request.
After a transaction is captured, the authorization may no longer be reversed. Instead (e.g. customer returns goods) a refund should be used to credit the cardholder.
Cancellation
When a previously requested authorization is no longer needed use an authorization reversal request for the full amount. This is to ensure an accurate open-to-buy balance of the cardholder.
For an Authorization cancellation use the transactionId as identifier for the transaction lifecycle for which the requestor is trying to release the funds.
Technical reversal
When no response is received to an AUTH or PREAUTH action due to a technical reason (e.g. timeout), the requestor should send in a follow-up action to REVERSE (e.g. actions AUTH_REVERSAL) using the original actionType originalActionId (of e.g. original AUTH).
Request actionType AUTH_REVERSAL and AUTH_REVERSAL_PARTIAL
Category | Field | Presence | Comment |
| actionType | Mandatory | Type of action requested. Possible values: -“AUTH_REVERSAL” -“AUTH_REVERSAL_PARTIAL” | |
| reversalCause | Optional | Indicates why the reversal has been triggered by the caller. Reason could be a problem in receiving and validating the response. But there can also be other issues afterwards related to action handling. Possible values: -"ResponseInvalid" -"ResponseTimeout" -"SubsequentlyDeclined" -"ProcessingFailure" | |
| Identification | actionId | Mandatory | Identifier assigned by the caller to the transaction. The provided values must be unique with respect to the requestor. That is, two requests generated by the same requestor must have different identifiers. The only exception is a retry/reattempt where the original value must be taken. The identifier must be in UUID format. |
| originalActionId | Conditional | In case of a technical reason to reverse the authorization request (e.g. timeout), this data element should be used to link to the original authorization request. | |
| transactionId | Mandatory | Unique identification assigned by Worldline to a business transaction. The value from the initial authorization response must be used to populate this field (if the response reached the PSP). | |
| acquirerId | Mandatory | Identification of the acquirer, assigned by Worldline | |
| cardAcceptorId | Mandatory | Identification of the merchant, assigned by acquirer | |
| pspReference | Optional | PSP’s reference for the transaction | |
| Financial | requestAmount (amount + currency) | Mandatory | Amount for which no longer authorization is requested. In case of a technical reversal, this should be the same amount as in the authorization request. In case of a customer cancellation, the amount should be the amount authorized by the issuer (full reversal) or a lower amount (partial reversal). |
| Circumstance | actionDateTime | Mandatory | Date and time in local time zone when the authorization reversal is requested |
Pre-Authorization
The pre-authorization request is sent in using actionType PREAUTH, service Purchase, and the other mandatory & relevant conditional authorization fields described under actionType AUTH.
The actionType PREAUTH must be used when the transaction amount is not known at the time of authorization. Pre-authorizations are typically used in hotel and the car rental sector.
Depending on scheme rules for some brands (e.g. Maestro) pre-authorization should be used when the amount is known at authorization, but the transaction may possibly not be completed for other than technical reasons. For instance, the products ordered by the cardholder may turn out to be out-of-stock.
Extend Pre-Authorization period
For Mastercard Pre-Authorization period (default is 30 days) can be extended with 30 days using an actionType AUTH_INCREMENTAL with requestAmount set to "0". For VISA Pre-Authorization period (default is 30 days) can be extended using an actionType PREAUTH resubmission using MIT with correct mitCause.
Request actionType PREAUTH
Category | Field | Presence | Comment |
| actionType | Mandatory | Type of action requested. Set to: -“PREAUTH” |
(Pre-)Authorization incremental
The pre-authorization amount can be increased by sending in an follow-up request using the actionType AUTH_INCREMENTAL, the transactionId (lifecycle) from the initial PRE_AUTH request response, the additional requestAmount and the other mandatory fields of the AUTH actionType. For example, a hotel may need to increase the authorization amount due to minibar usage or a 1 day longer stay.
If the Purchase is later CAPTURED, the capture requestAmount must not exceed the accumulated authorization amount.
Extend Pre-Authorization period
For Mastercard Pre-Authorization period (default is 30 days) can be extended with 30 days using an actionType AUTH_INCREMENTAL with requestAmount set to "0". For VISA Pre-Authorization period (default is 30 days) can be extended using an actionType PREAUTH resubmission using MIT with correct mitCause.
Request actionType AUTH_INCREMENTAL
Category | Field | Presence | Comment |
| actionType | Mandatory | Type of action requested. Set to: -“AUTH_INCREMENTAL” | |
| Identification | actionId | Mandatory | Identifier assigned by the caller to the transaction. The provided values must be unique with respect to the requestor. That is, two requests generated by the same requestor must have different identifiers. The only exception is a retry/reattempt where the original value must be taken. The identifier must be in UUID format. |
| transactionId | Mandatory | Unique identification assigned by Worldline to a business transaction. The value from the initial authorization response must be used to populate this field (if the response reached the PSP). | |
| acquirerId | Mandatory | Identification of the acquirer, assigned by Worldline | |
| cardAcceptorId | Mandatory | Identification of the merchant, assigned by acquirer | |
| pspReference | Optional | PSP’s reference for the transaction | |
| Financial | requestAmount (amount + currency) | Mandatory | Additional amount for which pre-authorization incremental is requested |
Authorization and Capture
In some cases such as with a Refund the Merchant may want to request both Authorization and Capture steps at the same time.
The request must then include the actionType “AUTH_AND_CAPTURE”, and the other mandatory and conditional authorization fields described under actionType AUTH.
Request actionType AUTH_AND_CAPTURE fields
Category | Field | Presence | Comment |
| actionType | Mandatory | Type of action requested. Set to: -“AUTH_AND_CAPTURE” | |
| service | Mandatory | Service requested. The follow-up actions must have the same value as the initial action. Possible values: -"Purchase" -“Refund” |
Account Verification
The account verification service (or account status inquiry as it is called by Mastercard) can be used to check that the cardholders account is open and can be used for future transactions. The account verification has no financial impact, i.e. no funds are reserved (requestAmount is absent).
The merchant must send in an request with actionType “AUTH”, service “AccountVerification”, the “requestAmount” left out, and the other mandatory and conditional authorization fields described under actionType AUTH.
The account verification can be used in various situations but is also often used when not only the status of the account is checked but also the cardholder needs to be authenticated such as:
- To establish a recurring or bill payment relationship
- To store the cardholder’s credential on file for use in future transaction
Disclaimer
The Open API specification is leading for integrations purposes. The Accept Transactions API documentation provides guidance on what is to be sent in for a particular transaction acceptance request (use case, action, brand, MCC, etc.).
The developer portal documentation does not provide a comprehensive set of rules and regulations on what request call body to send into the Accept Transactions API. To stay compliant and avoid data integrity issues, always consult the Card scheme processing rules. In addition, always consult your regulatory rules and regulations (for example consult the European Banking Authority websites for latest PSD II and SCA rules).