Payment Result

Receiving the Payment Result

Following the completion of the transaction the result is communicated back to the host website in one of the following ways.

Successful Transaction

Result sent to the URL provided in the postLink field in the transaction request.

Unsuccessful Transaction

Result sent to the URL provided in the failurePostLink field is present in the transaction request. If the field was not present the URL in the postLink field is used.

Payment Result

paymentResult
Field NameData TypeDescription
accountIdStringUnique reference for the store processing the transaction, as passed in the request.
amountDecimalTotal amount of the order including decimal places where applicable. 'Whole' amounts (e.g. '1') on a GBP account represents £1.00.
authCodeStringAuthorisation code issued for the transaction.
authDateTimeUTCStringDate and time of when the transaction was authorised with the acquirer.
avsHouseNumberResultStringConfirms the result of the Address Verification System (AVS) house number check.
NotSetHouse Number check was not requested.
NotCheckedHouse Number could not be checked.
MatchedHouse Number matched.
NotMatchedHouse Number did not match.
PartialMatchHouse Number partially matched.
avsPostcodeResultStringConfirms the result of the Address Verification System (AVS) post code check.
NotSetPost Code check was not requested.
NotCheckedPost Code could not be checked.
MatchedPost Code matched.
NotMatchedPost Code did not match.
PartialMatchPost Code partially matched.
cardExpiryDateStringExpiry date for the card used in the transaction. Provided in the “MM/YY” format.
cardholderNameStringCardholder name as entered on the payment form.
cardIssuingCountryString

Country where the card was issued. This information will only be returned when this can be determined.

This information is subject to change and as such we recommend only using this data as a guide.

cardPanStarredStringStarred PAN for the card used in the transaction - for example ************9909.
cardSchemeIdIntegerOptomany Card Scheme ID for the card used in the transaction.
cardSchemeNameStringName of the Card scheme for the card used in the transaction.
cardTokenIdStringOptomany Token ID for the card presented.
charitableDonationDecimalAmount of any charitable donation awarded by the consumer during the transaction process.
cscResultStringConfirms the result of the Card Security Code (CSC) validation check.
NotSetCSC check was not requested.
NotCheckedCSC could not be checked.
MatchedCSC matched.
NotMatchedCSC did not match.
currencyString

Currency of the transaction.

GBPPound Sterling
errorCodeIntegerProvides additional detail should an error have occurred with the transaction.
0No error occurred.
A full list of Error Codes can be found here.
idString

Unique transaction ID.

This ID should be stored as it is required for later transaction actions.

invoiceIdStringOrder/invoice/transaction/basket number generated by the host website, as passed in the request.
messageStringMessage confirming the processing result of the transaction request.
optomanyTerminalIdStringOptomany Terminal ID used when authorising the transaction.

payerAuthenticationResult

String

Result of the Payer Authentication process provided in the following formatenrollment result/authentication result

The possible results are detailed below.

EnrollmentAuthentication
Y

Successful.

Y

Successful.

N

Not enrolled.

N

Not authenticated.

A

Attempted.

A

Attempted.

U

Unable to check.

U

Unable to authenticate.

C

Challenge Required*

R

Authentication Rejected*

X

Not Attempted

X

Not Attempted

* 3D Secure v2 Only

As an example an enrolled card which has been fully authenticated will be returned as Y/Y

paymentMethodString

Payment method used for the transaction.

cardCard payment
paypalPayPal
applepayApple Pay
googlepayGoogle Pay
paybybankappPay by Bank App
ecospendOpen Banking (Ecospend)
KlarnaKlarna
responseCodeStringReturned by the acquirer detailing the result of the transaction. A full list of Response Codes can be found here.
rrnStringUnique reference allocated by Optomany to the authorisation.
schemeReferenceDataStringReference data from the card scheme, returned in the authorisation response.

This data may not always be present.
settledBooleanConfirms whether the transaction has been submitted for overnight settlement.
trueTransaction settled.
falseTransaction not settled.
signatureStringSignature generated for the transaction, for more information on this see Validating the Signature.
successBooleanConfirms whether the transaction has been successful.
trueTransaction approved.
falseTransaction not approved.

Payment Result > Three DS

paymentResult.threeDS
Field NameData TypeDescription
acsTransactionIdStringACS transaction ID.
cardholderAuthenticationStatusString

Indicates whether a transaction qualifies as an authenticated transaction or account verification.

Note: The Final Cres message can contain only a value of Y or N.

YAuthentication Verification Successful.
NNot Authenticated / Account Not Verified, transaction declined.
UAuthentication / Account Verification could not be performed; technical or other problem as indicated in Ares or Rreq.
AAttempts processing performed, not authentication/verified but a proof of attempted authentication/verification is provided.
CChallenge required; additional authentication required using Creq/Cres.
DChallenge required. Decoupled authentication confirmed.
RAuthentication/Account verification rejected, issuer is rejecting authentication/verification and requested authorisation not be performed.
IInformational only, 3DS Requestor challenge preference acknowledged.
cardholderAuthenticationValueDecimalCardholder Authentication Verification Value (CAVV) – a 28-byte base64 encoded value.
dsTransactionIdStringUniversally unique transaction identifier assigned by the 3DS Server to identify a single transaction.
eciStringElectronic Commerce Indicator (ECI) - consists of two digits.
mpiTransactionIdStringMPI transaction ID.
transactionStatusReasonStringProvides information on why the Transaction Status field has the specified value.
  • Card authentication failed
  • Unknown Device
  • Unsupported Device
  • Exceeds authentication frequency limit
  • Expired card
  • Invalid card number
  • Invalid transaction
  • No Card record
  • Security failure
  • Stolen card
  • Suspected fraud
  • Transaction not permitted to cardholder
  • Cardholder not enrolled in service
  • Transaction timed out at the ACS
  • Low confidence
  • Medium confidence
  • High confidence
  • Very High confidence
  • Exceeds ACS maximum challenges
  • Non-Payment transaction not supported
  • 3ri transaction not supported
  • ACS technical issue
  • Decoupled Authentication required by ACS but not requested by 3DS Requestor
  • 3DS Requestor Decoupled Max Expiry Time exceeded
  • Decoupled Authentication was provided insufficient time to authenticate cardholder. ACS will not make attempt
  • Authentication attempted but not performed by the cardholder
typeStringIndicates the type of authentication method the Issuer will use to challenge the Cardholder, whether in the Ares message or what was used by the ACS when in the Rreq message.
staticdynamicoobdecoupled
versionString3D Secure Version.
13D Secure v1.
23D Secure v2.
xidString3D Secure v1 Transaction Id

Payment Result > PayPal

paymentResult.paypal
Field NameData TypeDescription
paypalOrderStatusStringPayPal field = order_status
CREATEDOrder successfully created.
APPROVEDThe customer approved the payment through the PayPal wallet or another form of guest or unbranded payment.
VOIDEDOrder voided.
COMPLETEDThe payment was authorized or the authorized payment was captured for the order.
PAYER_ACTION_REQUIREDThe order requires an action from the payer (e.g. 3DS authentication).
paypalPayerNameStringName of the consumer.
paypalEmailStringPayPal email address used by the consumer.
paypalPayerIDStringPayPal allocated ID for the consumer.
paypalPayerCountryCodeISO 3166Consumers country code.
paypalCaptureStatusStringPayPal field = capture_status_detail
COMPLETEDFunds have been credited to the payee's PayPal account.
DECLINEDFunds could not be captured.
PARTIALLY_REFUNDEDAn amount less than this captured payment's amount was partially refunded to the payer.
PENDINGFunds have not yet credited to the payee’s PayPal account.
REFUNDEDAn amount greater than or equal to this captured payment’s amount was refunded to the payer.
paypalCaptureStatusReasonStringPayPal field = capture_status_details

Populated if the paypalCaptureStatus is PENDING or DENIED

BUYER_COMPLAINTPayer has initiated a dispute for this captured payment with PayPal.
CHARGEBACKFunds reversed due to a dispute.
ECHECKPaid by eCheck which has not yet cleared.
INTERNATIONAL_WITHDRAWALMerchant needs to accept or deny the payment via their PayPal account.
OTHERNo additional specific reason can be provided.
PENDING_REVIEWPayment is pending manual review.
RECEIVING_PREFERENCE_
MANDATES_MANUAL_ACTION
 
REFUNDEDCaptured funds were refunded.
TRANSACTION_APPROVED_
AWAITING_FUNDING
Payer must send funds for this captured payment.
UNILATERALPayee does not have an account.
VERIFICATION_REQUIREDPayPal account not verified.
paypalSellerProtectionStatusStringPayPal field = seller_protection.status
ELIGIBLEPayPal balance remains intact if the customer claims that they did not receive an item or the account holder claims that they did not authorize the payment.
PARTIALLY
_ELIGIBLE
PayPal balance remains intact if the customer claims that they did not receive an item.
NOT_ELIGIBLEThis transaction is not eligible for seller protection.
paypalSellerProtection
DisputeCategories
StringPayPal field = dispute_category
ITEM_NOT_RECEIVEDPayer paid for an item that they did not receive.
UNAUTHORIZED
_TRANSACTION
The payer did not authorize the payment.

Example Payment Results

Successful Card Payment
{
"signature": "Lmo7VGQUPMVHT/42w9GiaBNeckGmpt+axvrHlHT+i70=",
"id": "a59ee97d-b9e9-4423-a23c-06d6766b6bfe",
"amount": 25.67,
"currency": "GBP",
"invoiceId": "47365-3556",
"accountId": "32425",
"rrn": "8653/188/11052020143247000",
"authDateTimeUTC": "2020-05-11T16:33:05Z",
"responseCode": "00",
"errorCode": 0,
"success": true,
"settled": true,
"message": "Authorised and settled",
"authCode": "123ABC",
"avsHouseNumberResult": "Partial Match",
"avsPostcodeResult": "Partial Match",
"cscResult": "Matched",
"payerAuthenticationResult": "C/Y",
"optomanyTerminalId": "31292612",
"charitableDonation": 0.2,
"cardExpiryDate": "09/20",
"cardPanStarred": "************9909",
"cardTokenId": "XZXIx6WNM+vyvTFBOlGObOZazHurxVN6Sgjxq+CYhVcfMQ==",
"cardSchemeId": 8,
"cardSchemeName": "MasterCard",
"cardIssuingCountry": "Brazil",
"threeDS":
{
"eci": "05",
"type": "Dynamic",
"version": "2",
"dsTransactionId": "e36d0da0-4774-42aa-9b41-dcf4069e2add",
"acsTransactionId": "663bc449-052d-440a-bf03-cfe21b60e182",
"mpiTransactionId": "a9328cd9-920f-4b32-aa19-d5b47fe7ff26",
"cardholderAuthenticationValue": "AJkCCReZIncEQFcQBZkiAAAAAAA=",
"cardholderAuthenticationStatus": "C"
},
"paymentMethod": "card",
"cardholderName": "John Smith",
"schemeReferenceData": "abc123987zxy"
}

Validating the Signature

To provide integrators with confidence that the transaction response is genuine, a “signature” value is provided within each response message. By performing a simple calculation using the data in the request integrators can verify that the message is valid.

The mechanism for such a check is shown below.

Step No.Details
Step 1

Concatenate the below values from the response, in this order:

  • id
  • amount
  • currency
  • invoiceId
  • errorCode
  • success

These values are case-sensitive, and should be used as they are presented in the response.

Step 2

Use a hash function with the client_secret acting as the key.

Example:

hash :=hmac.New(sha256.New, secret)
hash.Write(message)

Step 3

Encode the sum of the hash to base 64.

Example:

Signature = base64.StdEncoding.EncodeToString(hash.Sum(nil))

Step 4Verify that the resultant value matches that contained within the request.
If it does the transaction can be accepted, if not the message is not genuine and should be disregarded.
Best Practice - Signature Validation

This step is completely optional, but is highly recommended to protect your solution from 'man-in-the-middle' attacks. We employ this Authentication process on all data you send to us.

Signature Validation Examples

private bool axeptOptomanySignatureCheck(AxeptOptomanyPaymentResultModel model) {
bool returnValue = false;
string message = model.id + model.amount.ToString() + model.currency + model.invoiceId +
model.errorCode.ToString() + model.success.ToString().ToLower();
string secret =
System.Configuration.ConfigurationManager.AppSettings["axeptOptomanyClientSecret"];
UTF8Encoding encoding = new System.Text.UTF8Encoding();
byte[] keyByte = encoding.GetBytes(secret);
byte[] messageBytes = encoding.GetBytes(message);
using(HMACSHA256 hmacsha256 = new HMACSHA256(keyByte)) {
byte[] hash = hmacsha256.ComputeHash(messageBytes);
string calculatedSignature = Convert.ToBase64String(hash);
if (calculatedSignature == model.signature) {
returnValue = true;
}
}
return returnValue;
}

Redirection to Host

Once the consumer has seen the result of the transaction and is happy to continue, they are invited to press the Close button on the payment form. The consumer is then redirected to an address provided in the request from the host website, namely one of the two below.

Successful TransactionURL provided in the payment request field backLink
Unsuccessful TransactionURL provided in the payment request field failureBackLink

Once the consumer is returned to the host website the result can be confirmed and other details such as delivery information etc. can be displayed.