×
Menu

Handepay Payment Gateway

 
This page details the inputs, secure inputs and outputs available for the Handepay Payment Gateway, how to complete each field, and an external link to the Handepay integration documentation.
 
PCI Pal must check any payment gateway integrations prior to going live.  The documentation disclaimer (which applies throughout this guide) should be read before commencing any configuration of payment gateways.
 

Inputs

Input Fields
Required
Character Limits/Required Input
Description
action
Yes
Char
The action requested.
 
Possible values are: PREAUTH, SALE, REFUND, REFUND_SALE, VERIFY.
amount
Yes
Num
The amount of the transaction in minor
currency. For the UK, this is pence, so
£10.99 should be sent as 1099.
Numeric values only – no decimal
points or currency symbols.
countryCode
Yes
3 char
Merchant’s location.
Valid ISO-3166 alpha or numeric code
currencyCode
Yes
3 char
Transaction currency.
Valid ISO-4217 alpha or numeric code.
customerAddress
Yes
Char
For AVS checking this must be a registered billing address for the card.
customerPostCode
Yes
16 char
For AVS checking this must be a registered postcode for the card
merchantID
Yes
Num
The client’s Gateway Merchant ID
orderRef
No
Char
Free format test field to store order details, reference numbers, etc. for the Merchant’s records
transactionUnique
No
Char
Unique identifier for the transaction.
type
Yes
1 num
The type of transaction.
Refer to section A-13 for details.
Possible values are:
1 – E-commerce (ECOM)
2 - Mail Order/Telephone Order (MOTO).
9 – Continuous Authority (CA)
signature
Yes
Char
Hash of the request contents combined with the security key to sign the transaction
 

Secure Inputs

Input Fields
Required
Character Limits/Required Input
Description
cardNumber
Yes
19 chars
Secure input of the card number
cardExpiryDate
Yes
4 chars
Secure input of the card expiry in MMYY format
cardCVV
Yes
3 or 4 chars
Secure input of the card CVV, either three or four digits long depending on the card
 

Outputs

Output Fields
Description
typeOut
The type as provided in the request. Should always be 2 for MOTO.
xref
The cross reference for the transaction to be sued to refer to it for refunds etc.
state
Transaction state. Possible values: Received, Approved, Verified, Declined, Referred, Reversed, Captured, Tendered, Deferred, Accepted, Rejected, Cancelled, Finished
actionOut
The action for this transaction, as provided in the request. For example: SALE
amountOut
The amount that was sent in the original request
cardType
The description of the card used
cv2Check
Description of the AVS/CV2 CV2 check.
 
Possible values are: not known, not
checked, matched, not matched,
partially matched
orderRefOut
The order reference as sent in the request
caEnabled
Is CA enabled for this merchant account. Returns Y or N only.
requestId
A unique identifier of the specific payment
request
cardFlags
Any flags that have been placed on the card by the issuer.
signatureOut
 
Timestamp
Time the transaction was created or last
modified
cardIssuer
The card issuer (when known).
cardScheme
The description of the card scheme used
cftEnabled
Is cft enabled on the merchant account. Returns Y or N.
merchantIdOut
The merchant ID used for this transaction
rtsEnabled    
Is rts enabled on the merchant account. Returns Y or N.
countryCodeOut
The country code that was sent in the request
addressCheck
Description of the AVS/CV2 address check
 
Possible values are: not known, not
checked, matched, not matched,
partially matched.
cardTypeCode
The code of card used, relating to the card scheme
currencyCodeOut
The currency code that was sent in the request
cv2CheckPref
The cv2 results that are allowed, if the cv2 result is not allowed then the transaction will be declined
responseCode
A numeric code providing the outcome
of the transaction:
Possible values are:
0 - Successful / authorised transaction.
2 - Card referred.
4 - Card declined – keep card.
5 - Card declined
paymentMethod
The payment method as used in the request
postcodeCheck
Description of the AVS/CV2 postcode
check.
 
Possible values are: not known, not
checked, matched, not matched,
partially matched.
transactionId
A unique ID assigned by the Gateway
amountApproved
 
amountReceived
The amount the Acquirer authorised.
This should always be the full amount
requested.
amountRetained
 
cardExpiryDateOut
The card expiry date, as sent in the request
cardExpiryYear
The year of the provided expiry date
cardNumberMask
The masked PAN, as sent in the request
cardSchemeCode
The code of the card scheme used
responseStatus
A numeric code providing the outcome
of the transaction:
Possible values are:
0 - Successful / authorised transaction.
2 - Card referred.
4 - Card declined – keep card.
5 - Card declined
threeDSEnabled
Is 3DS enabled for this Merchant Account?
Possible values are:
N – Merchant Account is not enabled.
Y – Merchant Account is enabled.
cardExpiryMonth
The month from the provided card expiry date.
cardNumberValid
Is the provided card number a valid card, returns Y or N only
responseMessage
The message received from the Acquiring bank, or any error message
vcsResponseCode
Velocity Control System (VCS) error code. Normally 5.
addressCheckPref
The address check results that are allowed, if the address result is not allowed then the transaction will be declined
avscv2AuthEntity
Textual description of the AVS/CV2
authorizing entity.
 
Possible values are: not known,
merchant host, acquirer host, card
scheme, issuer.
cardCVVMandatory
Is this CVV required for transactions under this merchant account. Returns Y or N only.
currencyExponent
The exponent for the transaction currency. Usually 2 for any western currency.
customerPostCodeOut
The customer’s post code, as sent in the request
eReceiptsEnabled
Is eReceipts™ enabled for this Merchant Account?
Possible values are:
N – Merchant Account is not enabled.
Y – Merchant Account is enabled.
eReceiptsStoreId
Merchant’s eReceipts™ store identifier.
riskCheckEnabled
Is the risk check enabled on the merchant account? Returns Y or N only.
surchargeEnabled
Is a surcharge enabled for the merchant account? Returns Y or N only.
threeDSCheckPref
The 3DS results that are allowed, if the 3DS result is not allowed then the transaction will be declined
authorisationCode
Authorisation code received from Acquirer.
cardIssuerCountry
Name of card issuing country (when
known).
postCodeCheckPref
The postcode check results that are allowed, if the postcode result is not allowed then the transaction will be declined
processMerchantId
ID of Merchant Account request was
processed by.
requestMerchantId
ID of Merchant Account request was sent to (usually same as merchantID)
transactionUniqueOut
The unique transaction identifier as sent in the request
avscv2CheckEnabled
Is AVS/CV2 checking enabled for this
Merchant Account?
Possible values are:
N – Merchant account is not enabled.
Y – Merchant account is enabled
avscv2ResponseCode
The result of the AVS/CV2 check
vcsResponseMessage
Description of the VCS response code or list
of controls that broken by this transaction.
avscv2ResponseMessage
The message received from the Acquiring
bank, or any error message with regards
to the AVS/CV2 check.
cardIssuerCountryCode
ISO-3166 Alpha 2 code of the card
issuing country (when known)
customerReceiptsRequired
Is a receipt required for the customer, returns Y or N only
 
Further information can be found by viewing the integration documentation:
 
 
The help manual was created with Dr.Explain