Card Authorisations / Payment Hold

Credit card transactions are always made up of an authorisation and a capture. The authorisation component verifies the card is valid and requests the cardholders bank to place a hold on the funds. The capture then instructs the card issuer to send the funds to us for settlement to merchants. Generally when you process a card transaction on our platform we combine both the authorisation and the capture into one call for ease of use and simplicity. We offer the ability to seperate these components into seperate calls allowing you to first authorise a transaction and place a hold on funds with the ability to either capture the funds or void the authorisation at a later date. This feature can save merchants the hassle, fees and risks attached with capturing funds upfront and then having to the transaction in part or in full as the authorisation can easily be voided if required.

This can be useful if you are not sure of the final amount or want to ensure the cardholder has sufficient funds such as:

• Hotel mini-bar, first night of accomodation or security deposit
• Hospitality venues when opening a bar account
• Prior to dispatching goods to allow time to verify a customers identity or verify stock

Whilst an authorisation places a hold on the amount, the cardholders bank is under no obligation to honour this and may revoke the authorisation at their discretion. Generally speaking this would only happen if the card issuing bank or the merchant believe the authorisation was fraudulent or if the card account is cancelled or suspended.

Authorisation Timeframes

To ensure cardholders are not burdened with lengthy hold times, any authorisation is for a finite period and subject to a strict misuse policy.

The timeframe is different for each card scheme however as a rule of thumb these only last 7 days.
If an authorisation is successful we will return a field indicating when the authorisation expires.
You must either capture the funds or void the authorisation before the expiration and should always aim to do this as soon as possible and without delay.
Failure to void or capture by the cutoff may incur a misuse fee.

Handling Amounts

Authorisations should not be performed simply to verify a card. If you need to do this we can perform a live verification of cards automatically when you tokenise them. Card schemes strongly discourage using authorisations for small amounts (Under $10.00).
You are only permitted to perform one capture per authorisation which can be any amount up to the the original authorisation amount.
If you capture less than the original authorisation the balance of the hold will be released back to the cardholder.
If you need to charge more than the authorisation you should capture the full amount of the original authorisation and then perform a new transaction to capture the balance owing.
If you choose to on-charge fees we will perform an authorisation for the amount requested plus the processing fee for the transaction.
Voiding an authorisation releases the funds back to the cardholder for use.
Once an authorisation has been captured no further actions are permitted.

Customer Payment Accounts (CPA)

This new endpoint introduces a new concept called Customer Payment Accounts (CPA). A customer payment account is an account that is linked to a customer and can be either a credit card or a bank account. Only credit card CPA's support the ability to do authorisations. Existing card token codes can by used as a Customer Payment Account code. When processing a transaction which includes a new card we will automatically return back a CPA which can be used for processing future transactions.

Using a CVN with a stored card

When charging a previously stored card you can optionally also pass in the CVN again. This can be useful in verifying the cardholder is the person in fact authorising the new charge. If you don't have the CVN you should not guess this field and should simply omit the field from the call. You are not permitted to ever store a CVN in your system.

CVN Responses

Perform an Authorisation only (without capturing funds)
For a new card

POST: <https://api.payadvantage.com.au/v3/payment_authorizations>  
{  
  "Customer": { "Code": "4E20A1" },  
  "Description":"testing",  
  "ExternalID": "YOUR_ID",  
  "Amount":123.45,  
  "OnchargeFees": true,  
  "CreditCard": {  
    "CardNumber": "4200000000000000",  
    "ExpiryMonth": 12,  
    "ExpiryYear": 2030,  
    "Cardholder": {  
      "FirstName": "John",  
      "LastName": "Smith"  
    }  
  },  
  "CVN": "123"  
}

For an existing card

POST: <https://api.payadvantage.com.au/v3/payment_authorizations>
{  
  "CustomerPaymentAccount": { "Code": "ZYZ123" },  
  "Description":"testing",  
  "ExternalID": "YOUR_ID",  
  "Amount":123.45,  
  "OnchargeFees": true  
}

Successful Response

{  
  "Code": "ZA8SXA",  
  "ExternalID": "abc123",  
  "Description": "testing",  
  "AmountAuthorized": 123.45,  
  "AmountAuthorizedIncFees": 126.09,  
  "CreatedBy": "API",  
  "DateCreated": "2022-03-24T13:11:52.32+11:00",  
  "DateExpires": "2022-03-30T11:13:08.07+11:00", 
  "DateCaptured": null,  
  "AmountCaptured": null,  
  "AmountCapturedIncFees": null,  
  "Payment": null,  
  "DateVoided": null,  
  "VoidedBy": null,  
  "DateFailed": null,  
  "FailReason": null,  
  "FailCode": null,  
  "CvnCheckResponse": "matched",  
  "CustomerPaymentAccount": {  
    "Code": "HA8SXA",  
    "DateFailed": null  
  },  
  "Status": "approved"  
}

Perform a Capture

PATCH: <https://api.payadvantage.com.au/v3/payment_authorizations/[PAYMENT_AUTH_CODE]>  
{  
  "Amount": 123.45  
}  

Response

{  
  "Code": "DA8SXA",  
  "ExternalID": "abc123",  
  "Description": "testing",  
  "AmountAuthorized": 123.45,  
  "AmountAuthorizedIncFees": 126.09,  
  "CreatedBy": "API",  
  "DateCreated": "2022-03-24T13:11:52.32+11:00",  
  "DateExpires": "2022-03-30T11:13:08.07+11:00",  
  "DateCaptured": "2022-03-27T11:13:08.07+11:00",  
  "AmountCaptured": 123.45,  
  "AmountCapturedIncFees": 126.09,  
  "Payment": {  
    "Code": "YA8SXA"  
  },  
  "DateVoided": null,  
  "VoidedBy": null,  
  "DateFailed": null,  
  "FailReason": null,  
  "FailCode": null,  
  "CvnCheckResponse": "matched",  
  "CustomerPaymentAccount": {  
    "Code": "HA8SXA",  
    "DateFailed": null  
  },  
  "Status": "approved"  
}

Return an Authorisation

GET: <https://api.payadvantage.com.au/v3/payment_authorizations/[PAYMENT_AUTH_CODE]>

Void an Authorisation

DELETE: <https://api.payadvantage.com.au/v3/payment_authorizations/[PAYMENT_AUTH_CODE]>

Get a list of Authorisations
Use parameters in the request URL to return filtered or sorted data in the response body. These parameters follow the same rules as any standard HTML query string parameter. The first parameter is separated by ‘?’ and subsequent parameters are separated by ‘&’.

Fields available for filtering: ExternalID, includeVoided, includeCaptured, includeFailed

GET: <https://api.payadvantage.com.au/v3/payment_authorizations?includeVoided=false&includeCaptured=false&includeFailed=false>

🚧

What if I got no response?

If no response is received this is usually due to a delay in us receiving a response from the card issuer or a connectivity issue between our system and yours. If you make a call and do not receive a response you should query the endpoint using your externalid for the transaction to see if we have received and handled the response before attempting another authorisation to a avoid creating multiple holds on a cardholders account

Call get payment_authorisations to validate its status if no response was received

GET: <https://api.payadvantage.com.au/v3/payment_authorizations?externalid=[ExternalID]>