Managing notifications

Introduction

In this section we are going to deal with the management of the notifications and responses you receive from Addon Payments.

In Addon Payments, unless the merchant’s configuration is modified, the notifications are in XML format, although you can request that they be in JSON format. To do so, please contact the support team.

The composition of the response object can be seen in detail in the section on Structure of notifications and responses.

When your merchant receives a notification, you must respond with an ACK with HTTP code 200. If you fail to do so, the server will send up to 5 retries of the same notification in a row.

Receiving notifications

Your platform must have a statusURL ready to receive transaction status notifications and update the customer’s order status accordingly. This URL is provided by the merchant in the requests sent to Addon Payments.

Addon Payments notification IPs

If your platform has security measures that have to authorize incoming connections, we recommend adding the IPs our notifications are sent from to your authorized list.

Staging environment:

35.189.207.233
35.246.248.42

Production Environment:

35.195.204.5
35.234.68.27

Structure of notifications/responses

The responses follow this structure, with a different colour for each part:

response: Encompasses all the other elements. In “operation-size=n” it indicates the number of operations the transaction has undergone and, therefore, the number of “operation” elements that will be received afterwards.
message: Shows the transaction ID on AP and whether the workflow has been completed correctly or there were any errors.
- Important: Don’t confuse this with transaction status, which is shown in the “status” for the final operation.
operations: Contains or groups each of the operations carried out on the transaction. The number of “operation” elements it contains is equal to the number shown in “operation-size=n” in the “response”.
- operation: This element contains the result of a specific operation on the transaction.
  - “Sorted-order” indicates the order in which the operations were executed, starting with one (1).
  - The status of the final transaction is shown in “status” and “respcode” in the final operation.
  - Operations executed on transactions are established in the workflow with rules. These assess several parameters of the transaction, such as transaction type, operation type, payment solution, amount, etc.
  - There are operations that may have one or several actions on the transaction. For example, risk analysis, authentication, authorization, capture, refund, payment into customer account, etc.
optionalTransactionParams: If there are parameters in “merchantParams”, this element will be returned with the respective values.
status: Indicates the status of the request. This element shows whether the workflow has finished correctly.
- Important: Don’t confuse this with transaction status, which is shown in the “status” for the final operation.
workFlowResponse: Shows the name and version of the workflow that handled the request.

Notification/response parameters

The following tables show the parameters for notifications. On the first table you will find the main parameters (message, operations, etc.). The second table has the parameters in “operations” (service, status, etc.). The final table has the “status” parameters, which show the transaction status.

Parameter	Description
response	Root element, encompasses the following elements. “operation-size=n” shows the number of operations carried out on the transaction.
message	Shows the transaction ID on AP and whether the workflow has been completed correctly or there were any errors.
operations	Contains or groups each of the operations carried out on the transaction. The number of “operation” elements it contains is equal to the number shown in “operation-size=n” in the “response”.
optionalTransactionParams	Element that contains the parameters sent in “merchantParams” and their values. – The value “entry” indicates an entry for each additional parameter. – “key shows the name of the additional parameter and “value” its value.
status	Element that shows whether the request was completed properly. Important: Don’t confuse this with transaction status, which is shown in the “status” of the final operation, inside the “operation”.
workFlowResponse	Shows the workflow that handled the request: – id: Internal workflow ID on AP. – name: Name of the workflow. – version: Version of the workflow.

This table shows the parameters in “operations”:

Parameter	Description
operation	Can encompass the rest of the parameters on the table. Contains the result of a specific operation on the transaction. There are as many as the “operation-size=n” indicates.
amount	Transaction total.
currency	Transaction currency.
merchantTransactionId	Transaction ID on your ecommerce platform.
operationType	Type of operation. The possible values are: – DEBIT: Payment. Meaning, the funds go from the customer’s account to the merchant. – CREDIT: Payment into customer’s account. Meaning the funds go from the merchant to the customer’s account. It is not a refund. For example, prize money. – REFUND: Reimbursing the customer for the whole amount of the initial transaction. – REBATE: Reimbursing the customer for part of the amount of the initial transaction. – VOID: Releasing the amount of a transaction with Pending status. – CAPTURE: Captures the amount of a transaction with Pending status. – ACCOUNT_REGISTRATION: Registration of customer account on AP
payFrexTransactionId	Transaction ID on AP. It is best to save it for any secondary transactions (release, refund, etc.) and to be able to locate the transaction if you need to.
sorted-order	Order of the operation in the workflow. Starts with the number one (1).
status	Status of the transaction after being handled by the payment solution or service. If it is the final operation, it reflects the final status of the transaction. The possible values are on the table below.
message	Message returned for the operation. Alphanumeric, max 1024 characters.
details	Response not processed by the payment solution.
paymentCode	Original response code from the payment solution. The format and values depend on the specific payment solution.
paymentDetails	Details of the customer’s card or account. – account: Customer account or wallet. – extraDetails: Element with extra information from the payment solution or service that handled the transaction. The format and values depend on the specific payment solution or service that generates the message. – entry: One entry per extra key. Contains: “key”: name of extra key. “value”: Value of extra key.
paymentMessage	Original response message from the payment solution or service that handled the transaction.
paymentSolution	Name of the payment solution that handled the transaction. When you receive this parameter, you won’t receive the parameter “service”. * Here is a table with all the payment solutions.
paySolTransactionId	Transaction ID on the payment solution. The format depends on the specific payment solution.
redirectionResponse	URL your ecommerce platform redirects the customer to after payment is complete.
respCode	AP response code. Maps the various response codes from the different payment solutions and services to a series of unified codes. * – code: Numerical response code from AP. – message: AP response messages. – uuid: Internal AP UUID generated for the transaction. Here is a table with the response codes and their descriptions.
service	Name of the service that handled the transaction. When you receive this parameter, you won’t receive the parameter “paymentSolution”. *

The following table shows the transaction statuses, in “status” for the “operation”:

Value	Description	Transaction completed	Final status
INITIATED	Transaction initiated	No	No
REDIRECTED	The payment solution requires customer be redirected to complete payment. It may be for several reasons, including: – Authentication of cardholder in card payments – The customer has to sign in on the payment solution platform – Payment solution not compatible with direct operation	No	No
PENDING	The transaction is pending completion using a secondary transaction. – For “DEBIT” transactions, it requires a settlement (CAPTURE) or release (VOID). – For “CREDIT” transactions, it requires approval (APPROVE) or rejection (DECLINE).	No	No
AWAITING_PAYSOL	Waiting for a response from the payment solution. The transaction has this status until AP receives a response from the payment solution.	No	No
SUCCESS3DS	3DSv2 authentication of the cardholder was successful.	No	No
ERROR3DS	3DSv2 authentication of the cardholder failed.	No	No
TO_CAPTURE	Transaction authorized and added to the following capture file. – Only for some acquirers.	Sí	No
SUCCESS	The transaction has been authorized.		Sí
SUCCESS_WARNING	The transaction has been authorized with KYC warnings.
ERROR	The transaction has been declined.	No
FAIL	The request generated an error. This could be for one of many reasons, including : – Request not formed properly. – Error in merchant settings. – Error in payment solution settings. – Error operation workflow.	No

Notification/response parameters – Cards

Below are the response parameters (specific for card operations) and their functions.

The specific parameters in this operation are found in the “operation” field, as follows:

Parameter	Description
authCode	Authorization code from the issuer for card payments. Alphanumeric, six (6) characters.
mpi*	3DSv2 response with information on authentication of card payments.Contains value “eci”, with result of authentication. These values are explained on the table below.
paymentDetails	Details of the customer’s card or account. May include these fields: – cardHolderName: Cardholder. – cardType: Returns Brand/Type of card. The card can be DEBIT/CREDIT/MIX. – cardNumber: Masked card number Numerical, max 19 digits. It must be stored on your ecommerce platform if there will be additional transactions using the card, such as recurring payments. – cardNumberToken: Customer card token generated by AP. Alphanumeric, 16 to 20 characters. It must be stored on your ecommerce platform if there will be additional transactions using the card, such as recurring payments. – expDate: Card expiry date. Numerical, four (4) digits. It should be stored on your ecommerce platform so you don’t send tokens with expired cards. Format: MMYY. – issuerBank: Name of bank that issued the card. – issuerCountry: Country of bank that issued the card.
rad	Response Additional Data. Only available for some card issuers. There is a list of all possible values here.
radMessage	Message received with Response Additional Data. Only available for some card issuers. There is a list of all possible values here.
subscriptionPlan	ID for recurring payments. It must be stored on your ecommerce platform if there will be additional transactions using the card, such as recurring payments.

*On this table you have the values for the field “eci”, in “mpi”, which show the result of the authentication attempt:

Card	3DSv2 status	Description	ECI	CAVV	Responsibility	Recommended action
Visa, Amex, JCB	Y	Authenticated	05	Yes	Issuer	Request authorization
Visa, Amex, JCB	A	Authentication attempt	06	Yes	Issuer	Request authorization
Visa, Amex, JCB	N	Not authenticated	07	No	Merchant	Do not request authorization
Visa, Amex, JCB	U	Authentication not available
Visa, Amex, JCB	R	Authentication declined
MasterCard	Y	Authenticated	02	Sí	Issuer	Request authorization
MasterCard	A	Authentication attempt	01	Sí	Issuer	Request authorization
MasterCard	N	Not authenticated	00	No	Merchant	Do not request authorization
MasterCard	U	Authentication not available
MasterCard	R	Authentication declined

Sample notifications/responses

Below are several examples of responses with an analysis of their content.

Received in response to a request sent via Hosted:

				
					https://checkout.stg-eu-west3.epgint.com/EPGCheckout/rest/online/detokenize?token=1cfe2f52-a72c-4a48-bf40-7d045397ef7c&apiVersion=5

Analysis: You only receive a URL to redirect the customer’s browser.

Received in response to a request sent via Host2Host in which “3DSv2” service requires the customer to be redirected to the SCA URL given in “redirectionResponse” to authenticate the transaction as a requirement prior to authorization:

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="2">
   <message>WorkFlow has finished successfully, for transaction ID: 7535014</message>
   <operations>
      <operation sorted-order="1">
         <amount>10.00</amount>
         <currency>EUR</currency>
         <merchantTransactionId>59702465</merchantTransactionId>
         <message>Exemptions has been removed</message>
         <operationType>DEBIT</operationType>
         <service>TRA</service>
         <status>SUCCESS</status>
         <transactionId>7535014</transactionId>
         <respCode>
            <code>0000</code>
            <message>Successful</message>
            <uuid>adbaef98_5b3e_4979_872b_959c9f1eb25d</uuid>
         </respCode>
      </operation>
      <operation sorted-order="2">
         <amount>10.00</amount>
         <currency>EUR</currency>
         <merchantTransactionId>59702465</merchantTransactionId>
         <message>Starting 3DSecure 2.0 process.</message>
         <operationType>DEBIT</operationType>
         <optionalTransactionParams/>
         <originalTransactionId>7535014</originalTransactionId>
         <paymentDetails>
            <extraDetails>
               <entry>
                  <key>threeDSMethodData</key>
                  <value>eyJ0aHJlZU…………Y1NjYifQ==</value>
               </entry>
               <entry>
                  <key>threeDSv2Token</key>
                  <value>9a595aad-710c-4a77-906d-5657d45f6c2d</value>
               </entry>
            </extraDetails>
         </paymentDetails>
         <redirectionResponse>redirect:https://checkout.stg-eu-west3.epgint.com/EPGCheckout/rest/online/3dsv2/redirect?action=gatherdevice&params=eyJ0aHJlZU…………I6IjA1In0=</redirectionResponse>
         <service>3DSv2</service>
         <status>REDIRECTED</status>
         <transactionId>986566</transactionId>
         <respCode>
            <code>8100</code>
            <message>Frictionless requires</message>
            <uuid>83730158_047c_4d19_a06c_d5d03547af2d</uuid>
         </respCode>
         <mpi>
            <acsEndProtocolVersion>2.2.0</acsEndProtocolVersion>
            <dsEndProtocolVersion>2.2.0</dsEndProtocolVersion>
            <threeDSMethodURL>https://mock-ds.stg-eu-west3.epgint.com/public/method-data/</threeDSMethodURL>
         </mpi>
      </operation>
   </operations>
   <optionalTransactionParams/>
   <status>SUCCESS</status>
   <workFlowResponse>
      <id>31380</id>
      <name>debit creditcards (TRA)</name>
      <version>0</version>
   </workFlowResponse>
</response>

Analysis:

response operation-size=”2″: In “operations” there are two (2) “operation” elements.
message “WorkFlow has finished successfully”: Shows that the workflow has been completed correctly, which means the request has been processed without errors. Important: this doesn’t show whether the transaction has been authorized or declined.
operations: Contains the operation carried out on the transaction.
- operation sorted-order=”1″: First operation carried out on the transaction.
  - service “TRA”: The first operation was risk analysis.
  - status “SUCCESS”: The risk analysis was completed correctly.
  - respCode – code “0000”: Response code received from TRA service that means it was completed correctly.
- operation sorted-order=”2″: Second operation carried out on the transaction.
  - service “3DSv2”: The second operation was a request for 3DSv2 authentication of the transaction.
  - status “REDIRECTED”: The 3DSv2 server requests that the customer be redirected to the SCA URL for secure authentication (SCA).
  - respCode – code “8100”: Response code received from 3DSv2 service that shows the customer must be redirected to SCA to authenticate the transaction as a requirement prior to authorization.
  - redirectionResponse: URL the customer must be redirected to.
optionalTransactionParams: It is blank because no additional parameters were sent in the request.
status “SUCCESS”: The request finished the workflow correctly without errors. Important: this doesn’t show whether the transaction has been authorized or declined.
workFlowResponse: Information on the workflow that handled the request.
- name: debit creditcards (TRA)
- version: 0

Received as a notification on the URL sent in the request parameter “statusURL” with the result of the authorization after customer authentication (valid for redirect and H2H integrations):

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="3">
   <message>WorkFlow has finished successfully, for transaction ID: 7536913</message>
   <operations>
      <operation sorted-order="1">
         <amount>10.00</amount>
         <currency>EUR</currency>
         <merchantTransactionId>1299418</merchantTransactionId>
         <message>Exemptions has been removed</message>
         <operationType>DEBIT</operationType>
         <service>TRA</service>
         <status>SUCCESS</status>
         <transactionId>7536913</transactionId>
         <respCode>
            <code>0000</code>
            <message>Successful</message>
            <uuid>adbaef98_5b3e_4979_872b_959c9f1eb25d</uuid>
         </respCode>
      </operation>
      <operation sorted-order="2">
         <amount>10.00</amount>
         <currency>EUR</currency>
         <merchantTransactionId>1299418</merchantTransactionId>
         <message>3dsv2 - processed</message>
         <operationType>DEBIT</operationType>
         <paymentDetails>
            <cardNumberToken>9821750791782227</cardNumberToken>
            <extraDetails/>
         </paymentDetails>
         <service>3DSv2</service>
         <status>SUCCESS3DS</status>
         <transactionId>7536913</transactionId>
         <respCode>
            <code>8000</code>
            <message>Successful authentication</message>
            <uuid>cf56dee1_4c7f_408c_b61f_85a1e7476806</uuid>
         </respCode>
         <mpi>
            <acsTransID>1e0cf2fa-2023-470b-9dee-8ae374cab858</acsTransID>
            <authMethod>01</authMethod>
            <authTimestamp>202306151828</authTimestamp>
            <authenticationStatus>Y</authenticationStatus>
            <cavv>AJkBB4OBmVFmgYFYFIGZAAAAAAA=</cavv>
            <eci>05</eci>
            <messageVersion>2.2.0</messageVersion>
            <threeDSSessionData>YzhjNzExZm…………liYmQwMDA1</threeDSSessionData>
            <threeDSv2Token>c8c711fa-c96e-43dc-8712-10509bbd0005</threeDSv2Token>
         </mpi>
         <paymentCode>nsY1</paymentCode>
         <paymentMessage>Authenticated successfully</paymentMessage>
      </operation>
      <operation sorted-order="3">
         <amount>10.00</amount>
         <currency>EUR</currency>
         <details>{"resultCode":"00000","resultDescription":"OK","values":{"rfTransactionCurrency":"EUR","rfOperationType":"Settle"…………"threeDsProtocolVersion":"2.2.0"}</details>
         <merchantTransactionId>1299418</merchantTransactionId>
         <message>Success 'Settle' operation with status 'SUCCESS'</message>
         <operationType>DEBIT</operationType>
         <optionalTransactionParams/>
<paySolTransactionId>355534686 790190 686064 230615202848</paySolTransactionId>
         <paymentDetails>
            <cardHolderName>Nombre Apellido</cardHolderName>
            <cardNumber>490727****2227</cardNumber>
            <cardNumberToken>9821750791782227</cardNumberToken>
            <cardType>VISA/DEBIT OR CREDIT</cardType>
            <expDate>1234</expDate>
            <extraDetails>
               <entry>
                  <key>cardCategory</key>
                  <value>Not Available</value>
               </entry>
               <entry>
                  <key>rememberMe</key>
                  <value>true</value>
               </entry>
            </extraDetails>
            <issuerBank>SERVIRED MASTERCARD INTERNACIONAL</issuerBank>
            <issuerCountry>ES</issuerCountry>
         </paymentDetails>
         <paymentMethod>19900</paymentMethod>
         <paymentSolution>caixapucpuce</paymentSolution>
         <status>SUCCESS</status>
         <transactionId>7536913</transactionId>
         <respCode>
            <code>0000</code>
            <message>Successful</message>
            <uuid>adbaef98_5b3e_4979_872b_959c9f1eb25d</uuid>
         </respCode>
         <authCode>509661</authCode>
         <mpi>
            <eci>05</eci>
         </mpi>
         <paymentCode>000</paymentCode>
         <paymentMessage>Operation completed successfullyo</paymentMessage>
      </operation>
   </operations>
   <optionalTransactionParams/>
   <status>SUCCESS</status>
   <workFlowResponse>
      <id>31380</id>
      <name>debit creditcards (TRA)</name>
      <version>0</version>
   </workFlowResponse>
</response>

Analysis:

response operation-size=”3″: In “operations” there are three (3) “operation” elements.
message “WorkFlow has finished successfully”: Shows that the workflow has been completed correctly, which means the request has been processed without errors. Important: this doesn’t show whether the transaction has been authorized or declined.
operations: Contains the operation carried out on the transaction.
- operation sorted-order=”1″: First operation carried out on the transaction.
  - service “TRA”: The first operation was risk analysis.
  - status “SUCCESS”: The risk analysis was completed correctly.
  - respCode – code “0000”: Response code received from TRA service that means it was completed correctly.
- operation sorted-order=”2″: Second operation carried out on the transaction.
  - service “3DSv2”: The second operation was a request for 3DSv2 authentication of the transaction.
  - status “SUCCESS3DS”: Cardholder authentication was a success.
  - respCode – code “8000”: Response code received from 3DSv2 service that shows the cardholder has been correctly authenticated.
- operation sorted-order=”3″: Third operation carried out on the transaction.
  - message “Success ‘Settle’ operation with status ‘SUCCESS'”: The transaction has been settled properly.
  - cardNumber: Customer card number with asterisks. It must be stored on your ecommerce platform to show the customer when they want to make a transaction using that card token.
  - cardNumberToken: Customer’s card token. It must be stored on your ecommerce platform to show the customer when they want to make a transaction using that card token.
  - expDate: Customer’s card expiry date. It must be stored on your ecommerce platform to show the customer when they want to make a transaction using that card token.
  - paymentSolution “caixapucpuce”: The transaction was managed in the third operation by the payment solution “CaixaPUCPUCE”, which authorizes and captures card payments.
  - status “SUCCESS”: The transaction was authorized by the issuing bank.
  - respCode – code “0000”: Response code received from AP that shows the transaction was authorized.
  - Important: The “status” and “respCode” in the final operation that corresponds to a payment solution shows whether THE TRANSACTION HAS BEEN AUTHORIZED OR DECLINED.
optionalTransactionParams: It is blank because no additional parameters were sent in the request.
status “SUCCESS”: The request finished the workflow correctly without errors. Important: this doesn’t show whether the transaction has been authorized or declined.
workFlowResponse: Information on the workflow that handled the request.
- name: debit creditcards (TRA)
- version: 0

Managing notifications

Introduction

Receiving notifications

Addon Payments notification IPs

Structure of notifications/responses

Notification/response parameters

Notification/response parameters – Cards

Sample notifications/responses

Products

Sales

Technical Support

Partners

SmartWiki, Powered by AI

Managing notifications

Introduction

Receiving notifications

Addon Payments notification IPs

Structure of notifications/responses

Notification/response parameters

Notification/response parameters – Cards

Sample notifications/responses

Products

Sales

Technical Support

Partners

SmartWiki, Powered by AI

Consulta la documentación de las distintas secciones de integraciones:

Addon Payments

Cyberpac

POS integrated Payments

Addon Payments

Consult the documentation of the different integrations sections:​

Consult the documentation of the different integrations sections: