|
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: