Authenticate Transactions

On this page:

Overview

The Authenticate and Authorise methods are available to merchants who are either:

  • Unable to fulfil the majority of orders in less than 6 days, or
  • Sometimes unable to fulfil orders after 30 days, or
  • Do not know the exact amount of the transaction at the time the order is placed.

For example, when items are shipped and priced by weight, or items are affected by foreign exchange rates.

How Authenticate and Authorise Transactions Work

Unlike Payment or Deferred transaction types:

  • Authenticate transactions do not obtain an authorisation at the time the order is placed.
  • The card and cardholder are validated using the 3D-Secure mechanism provided by the card-schemes and card issuing banks, and aim to authorise later.

Authenticate

The authenticate process is as follows:

  1. Your site must register the transaction with a transactionType of Authenticate, and the customer is asked to enter their payment details directly on your website.
  2. We verify the card number and check the 3D-Secure directories if the card is part of the scheme. If the card is part of the scheme, you will need to follow the 3D Secure redirection process.
  3. Authentication takes place:
    1. When the customer passed authentication with their bank, we respond with a status of Authenticated. 
    2. If they have not passed authentication, your rule base is consulted to check if they can proceed for authorisation. If not, we will respond with a status of Rejected.
    3. If they failed authentication and your rule base allows them to proceed, we will respond with a status of Registered.

In all cases:

  • The customer’s card is never authorised.
  • There are no shadow transactions placed on the customer’s account.
  • Your acquiring bank is not contacted.

The customer’s card details and their associated authentication status are stored by Opayo. You must Authorise or Cancelthe transaction within 90 days .

An Authenticate request is authenticated and built in the same way as a Payment transaction with the transactionType set to ‘Authenticate’. For example:

 

Sample Authenticate Request:

curl https://pi-test.sagepay.com/api/v1/transactions \-X POST -H "Authorization: Basic aEpZeHN3N0hMYmo0MGNCOHVkRV...ejRqNVVzNXU="  \-H "Content-type: application/json"  \-d 
'{
  "transactionType":"Authenticate",
  "paymentMethod":{
    "card":{
      "merchantSessionKey":"",
      "cardIdentifier":"",
      "save":false
    }
  },
  "vendorTxCode":"demotransaction-",
  "amount":10000,
  "currency":"GBP",
  "description":"Demo transaction",
  "apply3DSecure":"UseMSPSetting",
  "customerFirstName":"Sam",
  "customerLastName":"Jones",
  "billingAddress":{
    "address1":"407 St. John Street",
    "city":"London",
    "postalCode":"EC1V 4AB",
    "country":"GB"
  },
  "entryMethod":"Ecommerce"
}'

Sample Authenticate Response:

After an authenticate transaction is processed Opayo’s response will confirm the result and status of the transaction. For example:

<update with correct fields for response>

{
  "statusCode":"0000",
  "statusDetail":"The transaction was sucessfully authenticated",
  "transactionId": "DB79BA2D-05DA-5B85-D188-1293D16BBAC7",
  "acsTransId": "43b04fd1-692c-4b76-ac20-a75527ad0a25",
  "dsTransId": "7980e36f-907b-4530-84fd-ccc1f40bf9ae",
  "transactionType":"Authenticate",
  "retrievalReference":1777845,
  "paymentMethod":{
    "card":{
      "cardType":"Visa",
      "lastFourDigits":"0006",
      "expiryDate":"0320",
      "cardIdentifier":"DB79BA2D-05DA-5B85-D188-1293D16BBAC7",
      "reusable":false
    }
  },
  "status":"Authenticated",
  "3DSecure":{
    "status":"Checked"
  }
}
Important: For transactions made using the International Maestro card, you must AUTHORISE or CANCEL the transaction within 30 days.
When you carry out an AUTHENTICATE transaction, we will perform a zero value authorisation (ZVA) against that card. This is to remain compliant with industry mandates. No funds will change hands at this point - you will however see an extra row in your MySagePay reports indicating that a ZVA has been carried out. You can still AUTHORISE the transaction (as below) for the amount you wish to take. See here for more details.
If you wish to register a token using an AUTHENTICATE , you may do so, but passing a value of 0 in the amount field - we will still carry out a ZVA in order to remain SCA compliant. No money will change hands until you elect to use that token, however.

Authorise

When you are ready to fulfil the order, to charge the customer you must Authorise the transaction.

You can:

  • Authorise for any amount up to 115% of the value of the original Authentication
  • Use any number of Authorise requests against an original Authentication.

When the total value of the authorisation does not exceed the 115% limit and the requests are inside the 90 days limit, the transactions will be processed by Opayo:

  • Your acquiring bank is contacted for an authorisation code.
  • AVS/CV2 checks are performed and rules applied as normal.

When you have completed all your Authorisations, or when you do not want to take any, you can Cancel the Authenticate and prevent further Authorisations being made against the card. This happens automatically after 90 days.

Sample Authorise request:

{
        "transactionType": "Authorise",
        "referenceTransactionId": "56A59178-EA46-5731-BBAF-B08415CCE499",
        "vendorTxCode": "demotransaction99",
        "amount": 1000,
        "description": "Demo authorise",
        "applyAvsCvcCheck": "UseMSPSetting"
}

Sample Authorise response:

{
"transactionId": "DB79BA2D-05DA-5B85-D188-1293D16BBAC7",
"acsTransId": "43b04fd1-692c-4b76-ac20-a75527ad0a25",
"dsTransId": "7980e36f-907b-4530-84fd-ccc1f40bf9ae",
"transactionType": "Authorise",
"status": "Authorised",
"statusCode": 0,
"statusDetail": "The Authorisation was Successful.",
"retrievalReference": 9493946,
"bankResponseCode": 0,
"bankAuthorisationCode": 999777,
"avsCvcCheck": {
"status": "AllMatched",
"address": "Matched",
"postalCode": "Matched",
"securityCode": "Matched"
},
"paymentMethod": {
"card": {}
},
"amount": 567,
"currency": "GBP",
"3DSecure": {
"status": "Authenticated"
},
"fiRecipient": {
"accountNumber": "1234567890",
"surname": "Surname",
"postcode": "EC1V 8AB",
"dateOfBirth": "19900101"
}
}

 

Cancelling authenticate transactions

Note: All authenticate transactions expire after 30-days. It is not necessary to Cancel all authenticate transactions that will not be authorised.

Sample Cancel request:

'{
"instructionType": "cancel"
}'

Sample Cancel response:

{
  "instructionType":"cancel",
  "date":"2015-08-11T11:45:16.285+01:00"
}