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 Name	Data Type	Description
accountId	String	Unique reference for the store processing the transaction, as passed in the request.
amount	Decimal	Total amount of the order including decimal places where applicable. 'Whole' amounts (e.g. '1') on a GBP account represents £1.00.
authCode	String	Authorisation code issued for the transaction.
authDateTimeUTC	String	Date and time of when the transaction was authorised with the acquirer.
avsHouseNumberResult	String	Confirms the result of the Address Verification System (AVS) house number check. Not Set House Number check was not requested. Not Checked House Number could not be checked. Matched House Number matched. Not Matched House Number did not match. Partial Match House Number partially matched.
avsPostcodeResult	String	Confirms the result of the Address Verification System (AVS) post code check. Not Set Post Code check was not requested. Not Checked Post Code could not be checked. Matched Post Code matched. Not Matched Post Code did not match. Partial Match Post Code partially matched.
cardExpiryDate	String	Expiry date for the card used in the transaction. Provided in the “MM/YY” format.
cardholderName	String	Cardholder name as entered on the payment form.
cardIssuingCountry	String	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.
cardPanStarred	String	Starred PAN for the card used in the transaction - for example ************9909.
cardSchemeId	Integer	Optomany Card Scheme ID for the card used in the transaction.
cardSchemeName	String	Name of the Card scheme for the card used in the transaction.
cardTokenId	String	Optomany Token ID for the card presented.
charitableDonation	Decimal	Amount of any charitable donation awarded by the consumer during the transaction process.
cscResult	String	Confirms the result of the Card Security Code (CSC) validation check. Not Set CSC check was not requested. Not Checked CSC could not be checked. Matched CSC matched. Not Matched CSC did not match.
currency	String	Currency of the transaction. GBP Pound Sterling
errorCode	Integer	Provides additional detail should an error have occurred with the transaction. 0 No error occurred. A full list of Error Codes can be found here.
id	String	Unique transaction ID. This ID should be stored as it is required for later transaction actions.
invoiceId	String	Order/invoice/transaction/basket number generated by the host website, as passed in the request.
message	String	Message confirming the processing result of the transaction request.
optomanyTerminalId	String	Optomany 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. Enrollment Authentication 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
paymentMethod	String	Payment method used for the transaction. card Card payment paypal PayPal applepay Apple Pay googlepay Google Pay paybybankapp Pay by Bank App ecospend Open Banking (Ecospend) Klarna Klarna
responseCode	String	Returned by the acquirer detailing the result of the transaction. A full list of Response Codes can be found here.
rrn	String	Unique reference allocated by Optomany to the authorisation.
schemeReferenceData	String	Reference data from the card scheme, returned in the authorisation response. This data may not always be present.
settled	Boolean	Confirms whether the transaction has been submitted for overnight settlement. true Transaction settled. false Transaction not settled.
signature	String	Signature generated for the transaction, for more information on this see Validating the Signature.
success	Boolean	Confirms whether the transaction has been successful. true Transaction approved. false Transaction not approved.

Payment Result > Three DS

paymentResult.threeDS
Field Name	Data Type	Description
acsTransactionId	String	ACS transaction ID.
cardholderAuthenticationStatus	String	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. Y Authentication Verification Successful. N Not Authenticated / Account Not Verified, transaction declined. U Authentication / Account Verification could not be performed; technical or other problem as indicated in Ares or Rreq. A Attempts processing performed, not authentication/verified but a proof of attempted authentication/verification is provided. C Challenge required; additional authentication required using Creq/Cres. D Challenge required. Decoupled authentication confirmed. R Authentication/Account verification rejected, issuer is rejecting authentication/verification and requested authorisation not be performed. I Informational only, 3DS Requestor challenge preference acknowledged.
cardholderAuthenticationValue	Decimal	Cardholder Authentication Verification Value (CAVV) – a 28-byte base64 encoded value.
dsTransactionId	String	Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.
eci	String	Electronic Commerce Indicator (ECI) - consists of two digits.
mpiTransactionId	String	MPI transaction ID.
transactionStatusReason	String	Provides 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
type	String	Indicates 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. static dynamic oob decoupled
version	String	3D Secure Version. 1 3D Secure v1. 2 3D Secure v2.
xid	String	3D Secure v1 Transaction Id

Payment Result > PayPal

paymentResult.paypal
Field Name	Data Type	Description
paypalOrderStatus	String	PayPal field = order_status CREATED Order successfully created. APPROVED The customer approved the payment through the PayPal wallet or another form of guest or unbranded payment. VOIDED Order voided. COMPLETED The payment was authorized or the authorized payment was captured for the order. PAYER_ACTION_REQUIRED The order requires an action from the payer (e.g. 3DS authentication).
paypalPayerName	String	Name of the consumer.
paypalEmail	String	PayPal email address used by the consumer.
paypalPayerID	String	PayPal allocated ID for the consumer.
paypalPayerCountryCode	ISO 3166	Consumers country code.
paypalCaptureStatus	String	PayPal field = capture_status_detail COMPLETED Funds have been credited to the payee's PayPal account. DECLINED Funds could not be captured. PARTIALLY_REFUNDED An amount less than this captured payment's amount was partially refunded to the payer. PENDING Funds have not yet credited to the payee’s PayPal account. REFUNDED An amount greater than or equal to this captured payment’s amount was refunded to the payer.
paypalCaptureStatusReason	String	PayPal field = capture_status_details Populated if the paypalCaptureStatus is PENDING or DENIED BUYER_COMPLAINT Payer has initiated a dispute for this captured payment with PayPal. CHARGEBACK Funds reversed due to a dispute. ECHECK Paid by eCheck which has not yet cleared. INTERNATIONAL_WITHDRAWAL Merchant needs to accept or deny the payment via their PayPal account. OTHER No additional specific reason can be provided. PENDING_REVIEW Payment is pending manual review. RECEIVING_PREFERENCE_ MANDATES_MANUAL_ACTION   REFUNDED Captured funds were refunded. TRANSACTION_APPROVED_ AWAITING_FUNDING Payer must send funds for this captured payment. UNILATERAL Payee does not have an account. VERIFICATION_REQUIRED PayPal account not verified.
paypalSellerProtectionStatus	String	PayPal field = seller_protection.status ELIGIBLE PayPal 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_ELIGIBLE This transaction is not eligible for seller protection.
paypalSellerProtection DisputeCategories	String	PayPal field = dispute_category ITEM_NOT_RECEIVED Payer paid for an item that they did not receive. UNAUTHORIZED _TRANSACTION The payer did not authorize the payment.

Example Payment Results

Successful Card Payment

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"
}

Unsuccessful Card Payment

Unsuccessful Card Payment

{
  "signature": "CjWR0PpiW6dHDdMFr2LYGnPc3kaLtc/cN09ub8+ZFP4=",
  "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": 3010,
  "success": false,
  "settled": false,
  "message": "Transaction Rejected",
  "authCode": "123ABC",
  "avsHouseNumberResult": "Partial Match",
  "avsPostcodeResult": "Partial Match",
  "cscResult": "Matched",
  "payerAuthenticationResult": "Y/R",
  "optomanyTerminalId": "31292612",
  "charitableDonation": 0,
  "cardExpiryDate": "09/20",
  "cardPanStarred": "************9909",
  "cardTokenId": "XZXIx6WNM+vyvTFBOlGObOZazHurxVN6Sgjxq+CYhVcfMQ==",
  "cardSchemeId": 8,
  "cardSchemeName": "MasterCard",
  "cardIssuingCountry": "Brazil",
  "threeDS": 
  {
    "version": "2",
    "dsTransactionId": "1cd6f44b-6da5-49d2-813f-151ae0b743d7",
    "acsTransactionId": "545732c5-206a-4f98-a56a-b7b9520b7edf",
    "mpiTransactionId": "712684ed-4d9f-43e3-b376-53f722ef1464",
    "threeDSSessionData": "98491a9f-1799-46b7-9f62-3fee6930dc69",
    "cardholderAuthenticationStatus": "R"
  },
  "paymentMethod": "card",
  "cardholderName": "John Smith"
}

Successful Paypal Payment

Successful Paypal Payment

{
  "signature": "2epkfl9QPkUD4gYVomp/Hw7JaQHh+w6YGs/SRVCilhc=",
  "id": "2d0f9d8d-e16e-4482-9629-6d1974c65bef",
  "paymentOrderId": "52D26809BG588383M",
  "rrn": "3YP57986VJ9197719",
  "amount": 65,
  "currency": "GBP",
  "invoiceId": "1609149596324",
  "accountId": "uuid000001",
  "authDateTimeUtc": "2020-12-28T10:02:21.50291548Z",
  "errorCode": 0,
  "success": true,
  "transactionState": "CHARGE",
  "settled": true,
  "message": "Order successfully paid",
  "paypalOrderStatus": "COMPLETED",
  "paypalPayerName": "John Doe",
  "paypalEmail": "sb-9ieds2294744@personal.example.com",
  "paypalPayerID": "VFHQKQAR78CTY",
  "paypalPayerCountryCode": "GB",
  "paypalCaptureStatus": "COMPLETED",
  "paypalSellerProtectionStatus": "ELIGIBLE",
  "paypalSellerProtectionDisputeCategories": "ITEM_NOT_RECEIVED,UNAUTHORIZED_TRANSACTION"
}

Cancelled Klarna Payment

Cancelled Klarna Payment

{
  "signature": "cTdefoUwpLsLJvure14j9XL9SEC1a6+dNj06krusa4qoM=",
  "id": "113a7b76-9473-47d7-8fc0-9c045e334ddb",
  "paymentMethod": "klarna",
  "amount": 15.49,
  "currency": "GBP",
  "invoiceId": "1632980941435",
  "accountId": "476730",
  "errorCode": 0,
  "success": false,
  "message": "Transaction cancelled",
  "status": "CANCEL"
}

Successful Klarna Card Payment

Successful Klarna Payment

{
  "signature": "GNeuijrzZEflkxNd5J6JTHg977xxvUMrldh7oPCug=",
  "id": "dc0564ae-593b-44ae-30bb-c139a9dcf27c",
  "paymentMethod": "klarna",
  "rrn": "16bfdc4d-d34f-8c3b-aa59-c127fc659440",
  "amount": 957.37,
  "currency": "GBP",
  "invoiceId": "1632980941435",
  "accountId": "587429",
  "authDateTimeUtc": "2021-09-30T05:50:42.630339139Z",
  "errorCode": 0,
  "success": true,
  "settled": false,
  "message": "Completed successfully",
  "status": "AUTH"
}

Unsuccessful Klarna Payment

Unsuccessful Klarna Payment

{
  "id": "c5bffed3-314b-4de3-49a8-9008ce0eb36c",
  "amount": 10.98,
  "status": "REJECT",
  "message": "Transaction declined",
  "success": false,
  "currency": "GBP",
  "accountId": "1746394",
  "errorCode": 0,
  "invoiceId": "1624339009780",
  "signature": "tlpXeTnurpDsEbHZL374W6g7Et4ilQvOpqtPHnHRwsU=",
  "paymentMethod": "klarna"
}

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 4	Verify 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

C#

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 Transaction	URL provided in the payment request field backLink
Unsuccessful Transaction	URL 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.