Handle pre-authorizations

Applicable only when integrating with our Smart Checkout solution.

Pre-authorizations are not available with recurring payments or instalments.

The below examples use basic auth for authentication.

Pre-auth transactions with a debit card or credit card hold the balance as unavailable either until the merchant clears the transaction or the hold ‘falls off’. This is automatically done after a certain period, then you ‘lose’ the pre-auth and cannot capture a payment. In the case of debit cards, authorization holds can fall off the account (thus rendering the balance available again) anywhere from 1–5 days after the transaction date depending on the issuing bank’s policy; in the case of credit cards, holds may last as long as 30 days. You are not automatically notified when a pre-auth falls off; there is no webhook or message sent to give you this information.

To start with, you need to create a payment order, using the isPreAuth parameter (set to true). Following on from that, the customer needs to successfully submit their card details against the payment order, after which you have a preauthorized charge (not actual charge yet). You can then subsequently capture the preauth, thus making the charge and taking the payment directly from the customer card without any customer interaction.

On this page:

Create a pre-auth

Creating a pre-auth involves requesting the customer’s card details via a payment order and placing the approved amount on hold.

Step 1: Create payment order for pre-auth

Request example

curl -L -X POST 'https://demo.vivapayments.com/api/orders' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic OTZjYjVhMDctNDhjZS00ZDgxLTg3NmQtYTZjM2RmOGRiZDE2OkFEMmUqKA==' \
--data-raw '{
"amount": 10000,
"fullName": "Customer full name",
"email": "customer@example.com",
"isPreAuth": "true",
"customerTrns": "Pre-auth request",
"merchantTrns": "Pre-auth request Joe Bloggs",
"requestLang": "en-gb",
"sourceCode": "7862"
}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo.vivapayments.com/api/orders',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "amount": 10000,
  "fullName": "Customer full name",
  "email": "customer@example.com",
  "isPreAuth": "true",
  "customerTrns": "Pre-auth request",
  "merchantTrns": "Pre-auth request Joe Bloggs",
  "requestLang": "en-gb",
  "sourceCode": "7862"
  }',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Basic OTZjYjVhMDctNDhjZS00ZDgxLTg3NmQtYTZjM2RmOGRiZDE2OkFEMmUqKA=='
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response example

{
    "OrderCode": 7846182689168959,
    "ErrorCode": 0,
    "ErrorText": null,
    "TimeStamp": "2021-07-21T10:57:06.8916895+03:00",
    "CorrelationId": null,
    "EventId": 0,
    "Success": true
}

Step 2: Redirect customer to submit card details for the pre-auth

Next, the customer needs to successfully complete the Smart Checkout payment page of the created payment order.

Redirect customer to the below URL replacing [OrderCode] with the order code from Step 1:

https://demo.vivapayments.com/web/checkout?ref=[OrderCode]

Payment page example

Payment page of the above URL:

Pre-auth request Smart Checkout

Step 3: Confirm the payment

After the customer clicks on the payment button, which appears on the Viva Wallet page that is used to pay the payment order, the customer is redirected back to your website. If the payment has been successful or is pending, the customer is redirected to the Success URL, otherwise (i.e. if the payment has been unsuccessful) they are redirected to your Failure URL.

The redirection uses the HTTP GET method and appends the following query string parameters to the redirect Success / Failure URL:

Capture a pre-auth

Capturing a pre-auth involves taking the pre-authorized payment out of hold status and receiving it into your account. You can capture either the full amount or a partial payment below the full amount. The hold is released once a single full or partial capture has been actioned.

Via banking app

  1. Log in to Viva Wallet, demo or live , and select the required account.

  2. From your dashboard go to Sales > Sales Transactions.

  3. Find the pre-authorization you wish to capture and click on the Capture button:

Capture button next to sales transaction

Via API

To capture a pre-auth via the Viva Wallet Payment API, use the Create transaction API call in the same way that you would to create a payment.

Request example

curl -L -X POST 'https://demo.vivapayments.com/api/transactions/f60c357d-e940-4832-9f13-ab3e9dd7e3d4' \
-H 'Authorization: Basic OTZjYjVhMDctNDhjZS00ZDgxLTg3NmQtYTZjM2RmOGRiZDE2OkFEMmUqKA==' \
-H 'Content-Type: application/json' \
--data-raw '{
  "amount": 10000,
  "customerTrns": "Capture of hotel booking for customer xyz"
}'\'''

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo.vivapayments.com/api/transactions/f60c357d-e940-4832-9f13-ab3e9dd7e3d4',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "amount": 10000,
    "customerTrns": "Capture of hotel booking for customer xyz"
  }',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Basic OTZjYjVhMDctNDhjZS00ZDgxLTg3NmQtYTZjM2RmOGRiZDE2OkFEMmUqKA=='
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response example (successful)

A successful payment capture is identified by “statusId”:”F” (finished or finalised) in the response as shown in the example below.

{
    "Emv": null,
    "Amount": 100.00,
    "StatusId": "F",
    "RedirectUrl": null,
    "CurrencyCode": "826",
    "TransactionId": "14c59e93-f8e4-4f5c-8a63-60ae8f8807d1",
    "ReferenceNumber": 838982,
    "AuthorizationId": "838982",
    "Ctap": null,
    "RetrievalReferenceNumber": "109012838982",
    "Loyalty": null,
    "ThreeDSecureStatusId": 2,
    "ErrorCode": 0,
    "ErrorText": null,
    "TimeStamp": "2021-07-21T18:16:49.9034973+03:00",
    "CorrelationId": null,
    "EventId": 0,
    "Success": true
}

Response example (unsuccessful)

An unsuccessful payment capture is identified by “statusId”:”E” (error) in the response as shown in the example below. This will be returned if the pre-auth has fallen off or already been captured.

{
    "Emv": null,
    "Amount": null,
    "StatusId": "E",
    "RedirectUrl": null,
    "CurrencyCode": null,
    "TransactionId": null,
    "ReferenceNumber": null,
    "AuthorizationId": null,
    "Ctap": null,
    "RetrievalReferenceNumber": null,
    "Loyalty": null,
    "ThreeDSecureStatusId": null,
    "ErrorCode": 403,
    "ErrorText": "Preauth has expired or already captured",
    "TimeStamp": "2021-07-22T12:39:27.900582+03:00”,
    "CorrelationId": null,
    "EventId": 1,
    "Success": false
}

Cancel a pre-auth

Via banking app

  1. Log in to Viva Wallet, demo or live , and select the required account.

  2. From your dashboard go to Sales > Sales Transactions.

  3. Find the pre-authorization you wish to cancel and click on the Cancel button:

    Cancel button next to sales transaction
    An issuer alert is displayed in a popup:

    Cancel transaction alert

  4. Click on the Yes button to go ahead with the cancellation.

Via API

To cancel a pre-auth via the Viva Wallet Payment API, use the Cancel transaction API call in the same way that you would to reverse a payment.

Request example

curl -L -X DELETE 'https://demo.vivapayments.com/api/transactions/[transactionId]/?amount=10000 \
-H 'Authorization: Basic [Base64-encoded Merchant ID and API key]'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo.vivapayments.com/api/transactions/[transactionId]/?amount=10000',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'DELETE',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Basic [Base64-encoded Merchant ID and API key]'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response example (successful)

A successful cancellation is identified by “statusId”:”F” (finished or finalised) in the response as shown in the example below.

{
    "Emv": null,
    "Amount": 100.00,
    "StatusId": "F",
    "RedirectUrl": null,
    "CurrencyCode": "826",
    "TransactionId": "1289e200-6891-4739-afe5-5c13e839545b",
    "ReferenceNumber": 839335,
    "AuthorizationId": null,
    "RetrievalReferenceNumber": "109110839335",
    "Loyalty": null,
    "ThreeDSecureStatusId": 2,
    "ErrorCode": 0,
    "ErrorText": null,
    "TimeStamp": "2021-07-21T18:07:40.5164237+03:00",
    "CorrelationId": null,
    "EventId": 0,
    "Success": true
}

Response example (unsuccessful)

An unsuccessful cancelation of a pre-auth is identified by “statusId”:”E” (error) in the response as shown in the example below. This will be returned if the pre-auth has fallen off or already been cancelled.

{
    "Emv": null,
    "Amount": null,
    "StatusId": "E",
    "RedirectUrl": null,
    "CurrencyCode": null,
    "TransactionId": null,
    "ReferenceNumber": null,
    "AuthorizationId": null,
    "RetrievalReferenceNumber": null,
    "Loyalty": null,
    "ThreeDSecureStatusId": null,
    "ErrorCode": 403,
    "ErrorText": "PaymentsNonReversibleTransaction: Request to reverse transaction aborted",
    "TimeStamp": "2021-07-22T12:49:40.8336001+03:00",
    "CorrelationId": null,
    "EventId": 2055,
    "Success": false
}

Further information

Check out the following tutorials for more details about some of the above topics:

*Relevant transaction feedback parameters: “TransactionTypeId”: 0 (card capture); 1 (card pre-auth)