Authorization
Authorization is a process where you verify the customer's payment method and obtain an approval from a card issuer to proceed with the transaction. This involves the exchange of authorization requests and responses between your system and us, ensuring that the transaction meets the necessary security and financial criteria. These authorized/reserved funds could be captured immediately or at a later stage but within the authorization validity period set by respective card scheme.
There are two different authorization types which you could pick based on the use cases or business demands. This section discusses briefly about them, when it could be used & its validity period.
Understanding Final Authorization and Pre-Authorization
Final Authorization also known as “Final-Auth” or "Standard Authorization" or simply as "Authorization", shall be used when the final amount of a sale is known and not expected to be changed thereafter. It is important that the amount authorized is the same as the amount you wish to capture.
It is important to capture the entire amount of final authorization either in single full capture or multiple partial capture transactions to avoid any scheme fines.
Pre-Authorization, also known as “Pre-Auth,” shall be used when the final amount of a sale is not known at the time of transaction initiation and it could either be increased/partly reversed/adjusted to match the final amount when known or captured for the same amount within the authorization validation period.
Pre-Authorization is commonly used to secure bookings, hold orders, to allow time to verify the availability of the ordered item before the final transaction amount is determined.
Pre-authorizations can have a higher cost, but also offer more options related to changing the amount later on.
By understanding the distinctions between Pre-Authorizations and Final Authorizations, you can effectively implement these authorization types within your platform, providing clarity and transparency in the payment process for your customers.
Initiate an Authorization
In this section, we'll discuss about the key properties and values that are applicable to trigger an authorization through the create payment request. You could enhance the API request by including additional parameters that your use case may demand.
Properties |
Explanation |
|---|---|
operationId |
An unique Id for each transaction. We advise you to use a UUID or GUID. |
transactionTimestamp |
Transaction timestamp. |
authorizationType |
Indicate the authorization type with a relevant value from the list below
|
cardPaymentData.cardEntryMode |
Use the property to specify the card entry mode, below is the list of possible values which could be used
|
cardPaymentData.cardholderVerificationMethod |
Set the appropriate value to indicate the cardholder verification method. Possible values are
It is possible to include card security code along with and threeDSecure data in the request. If you do so then set this property to "THREE_DS ". Card security code verification is expected to be performed by the issuer in addition to the 3D-secure verification. |
cardPaymentData.captureImmediately |
You must flag the need of immediate capture by setting a Boolean value
|
cardPaymentData.brand |
Brand of the card that is used in the transaction. Possible values are
|
cardPaymentData.cardData.cardNumber |
Card number / PAN in clear text. |
cardPaymentData.cardData.expiryDate |
Expiry details of the card in MMYYYY format. |
references.merchantReference |
Transaction reference for the merchant, to be found in our merchant settlement reports/files. this could help you in reconciliation of the payments. |
references.dynamicDescriptor |
Transaction reference for the cardholder to be seen in the card account statement. |
amount |
Object with properties to specify the transaction amount and currency. Ensure that the currency used is in the supported processing currencies list. To avoid any miscommunication between you and us, we have introduced numberOfDecimals property where the decimals for the amount and currency shall be specified. This means you have some flexibility in how you send in the amount. |
Below table shows you how the numberOfDecimals property affects the amount we will try to authorize.
currencyCode |
amount |
numberOfDecimals |
Amount we would try to authorize |
|---|---|---|---|
EUR |
100 |
0 |
€100.00 (one hundred Euro and zero cents) |
EUR |
199 |
0 |
€199.00 (one hundred and ninety-nine Euro and zero cents) |
EUR |
100 |
2 |
€1.00 (one Euro and zero cents) |
EUR |
199 |
2 |
€1.99 (one Euro and 99 cents) |
JPY |
100 |
0 |
¥100 (one hundred Japanese Yen) |
JPY |
199 |
0 |
¥199 (one hundred ninety-nine Japanese Yen) |
JPY |
100 |
2 |
¥1 (one Japanese Yen) |
JPY |
199 |
2 |
Expect an error from API, as Japanese Yen doesn’t use decimals |
It is important to note that if you submit a non-zero numberOfDecimals value for a currencyCode that doesn't support decimals and specify an amount that doesn't have zeros where we expect the decimals to be, the API will return an error .
If a payment is initiated using any of the issuer supported wallets, you must include following properties as well in your request.
Properties |
Explanation |
|---|---|
walletId |
Indicating the wallet type . Pick a numeric value from the list below based on wallet type involved in the transaction.
|
networkTokenData.cryptogram |
Network token cryptogram |
networkTokenData.eci |
Electronic Commerce Indicator value that indicates the level of authentication. Contains different values depending on the brand. |
Example Authorization request
Below is an example final Authorization (MOTO) request with immediate capture of 20.00 EUR using a Visa card (PAN in plain text) with no cardholder verification method.
{
"operationId": "63f3de8e-e79f-4228-ae4f-35904e893de6",
"transactionTimestamp": "2024-10-11T13:14:36.944Z",
"authorizationType": "FINAL_AUTHORIZATION",
"amount": {
"amount": 2000,
"currencyCode": "EUR",
"numberOfDecimals": 2
},
"cardPaymentData": {
"cardEntryMode": "MAIL",
"cardholderVerificationMethod": "NONE",
"allowPartialApproval": false,
"captureImmediately": false,
"brand": "VISA",
"cardData": {
"cardNumber": "4176669999000104",
"expiryDate": "122031"
}
},
"references": {
"merchantReference": "Your-Order-d3e8b176-2059-4fa1-be84-b147576f7de1"
}
}Corresponding Authorization response
{
"paymentId": "pay:ch:etu:bQnw3xqLSHuE8f9XPS1Y6Q",
"operationId": "63f3de8e-e79f-4228-ae4f-35904e893de6"
"responseCode": "0",
"responseCodeDescription": "Accepted or completed successfully",
"responseCodeCategory": "APPROVED",
"responder": "WORLDLINE",
"status": "AUTHORIZED",
"initialAuthorizationCode": "082226",
"totalAuthorizedAmount": {
"amount": 2000,
"currencyCode": "EUR",
"numberOfDecimals": 2
},
"references": {
"schemeTransactionId": "304285476773023"
}
}You will notice that an unique paymentId is returned in the response which could be used to perform follow up operations. Please refer to response handling to understand the response code, category, responder and status and build your integration accordingly. References like retrievalReferenceNumber , schemeTransactionId and paymentAccountReference would be returned in the response if we happen to receive one from the scheme/issuer.