Process

 

Description

After the successful Register call and terminal phase, you can make financial operation to the transaction. Available financial operations are AUTH, VERIFY, SALE, CAPTURE, ADJUST, CREDIT and ANNUL, and they all are encapsulated by the Process call. The Process call needs to be made at most 365 days (1 year) after the initial Register call for the transaction. Besides, some operations have time restrictions that vary from this.

  • The authorization (AUTH), account verification (VERIFY) and authorization & capture (SALE) must for most payment methods be done within 24 hours of the customer being redirected back from the payment window. We recommend doing the further action as soon as possible.
  • The CAPTURE needs to be done while the authorization is still valid, if applicable. Many card Issuers are using a 21-day limit. Beyond this, the response depends on the card Issuer and the specific account.
  • The CREDIT is available for 365 days.

If you are using CAPTURE in conjunction with the fee, you need to run the Query call to get the total amount of the transaction before capturing, as the amount might have changed during the terminal phase. You can always CAPTURE up to the total amount whether using fees or not.

The input data is organized into a ProcessRequest, and the output data is formatted as a ProcessResponse. Examples of the REST Process calls and the corresponding responses can be found in the "Sample code" section.

API call

REST

Please note that Server Name Indication (SNI) is required when connecting to Netaxept test environment URL https://test.epayment.nets.eu

Web Services

Process (string merchantId, string token, ProcessRequest  request) -> ProcessResponse

Input parameters

Available input parameters in the Process are listed below. Please see proper validation rules at the “Validation” section.

Authentication

Merchant ID

REST: merchantId

WebServices: merchantId

Required

Validation: Numeric

MaxLength: 8

Unique ID generated by Nets for identifying each merchant in Netaxept. You need to send this ID to Netaxept along all API calls. Test accounts may have a maximum length of 8 digits, while production accounts has a maximum length of 6 digits.

 

Token

REST: token

WebServices: token

Required

Validation: Reference

MaxLength: 32

Shared secret between the merchant and Netaxept that is used to authenticate the merchant and is provided to you by Netaxept.

ProcessRequest

Operation

REST: operation

WebServices: ProcessRequest.Operation

Required

Validation: Alpha

MaxLength: N/A

Specifies which financial operation you want to run for the transaction. Valid values are:

  • AUTH
  • VERIFY
  • SALE
  • CAPTURE
  • CREDIT
  • ANNUL
  • ADJUST

Read more about the different operations at the "Flow outline" section.

 

Transaction ID

REST: transactionId

WebServices: TransactionId

Required

Validation: Reference

MaxLength: 32

Unique ID identifying each transaction within the Merchant ID in Netaxept at any point. Transaction ID used in this call needs to match the Transaction ID used with the Register call and in Terminal phase.

 

Sub transaction ID

REST: subTransactionId

WebServices: SubTransactionId

Optional

Validation: Reference

MaxLength: 32

Invoice ID generated for each invoice. Usually one invoice transaction has one invoice ID, however, if you run for example a partial capture for an invoice transaction, an invoice with its own invoice ID will be created.

 

Description

REST: description

WebServices: ProcessRequest.Description

Optional

Validation: Custom

MaxLength: 4000

Free-format textual description of this part of the transaction / operation determined by the merchant and displayed to the merchant in Netaxept Admin. In Netaxept Admin, the field displayes also an IP address and/or a username that has been used for the transaction.

Please note that this is different than OrderDescription that is displayed to the end-customer on a payment window.

 

Transaction amount

REST: transactionAmount

WebServices: ProcessRequest.TransactionAmount

Optional

Validation: Numeric

MaxLength: 10

Transaction amount described as the lowest monetary unit for the given currency without punctuation marks and excluding any fees. For example 100,00 NOK is noted as "10000" and 9.99 USD is noted as "999". Note that both CREDIT and CAPTURE support partial captures and credits.

The max amount possible for this value is to specify 2147483647, the maximum value of a signed 32 bit integer.

If no transaction amount is specified for CAPTURE or CREDIT, the full available amount will be captured or credited, respectively.

 

Adjustment type

REST: adjustmentType

WebServices: ProcessRequest.AdjustmentType

Optional (required for "Adjust" operation)

Validation: Alpha

MaxLength: 50

Indicates whether the adjusted amount is negative or positive. Adjusting the total invoice amount is currently supported for Collector. Valid values are:

  • positive = Amount will be added to invoice
  • negative = Amount will be deducted from invoice

 

Transaction reference number

REST: transactionReconRef

WebServices: ProcessRequest.TransactionReconRef

Optional

Validation: Reference

MaxLength: 25

Reference number allocated to the transaction by the merchant. The transaction reference number will be returned to the merchant with the settlement if the chosen acquirer supports the return of the transaction-specific reference number. The transaction reference number can also be seen in the merchant's bank statement when direct bank payments are in question. Read more about transaction reference numbers

Transaction reference number can be sent to Netaxept along the Register call. This reference number will then serve as a default reference if the new transaction reference number is omitted in the Process call. The transaction reference number can also be omitted altogether.

 

Goods

REST:

WebServices: ProcessRequest.Goods

Optional

Validation: Custom

MaxLength: N/A

The Goods list is an array of Item entries, one Item representing one product line / item. The Goods object is used for invoice and instalment payment methods implemented via Netaxept. Read more about invoices and instalments

For each Item in the Goods list, the following parameters are available. Also, it should be noted that when working with REST interface, the format of these parameters needs special formatting. As the number of items is variable, you need to send a parameter "numberOfGoods" indicating how many product lines / items should be expected in the Goods list. Then, indexed from 1 up to "numberOfGoods", pass the parameters as amount_N, articleNumber_N etc. where "N" is the serial number of the item. In Web services, numberOfGoods parameter is not needed.

  • Amount (required)
  • ArticleNumber (required if Title missing)
  • Discount
  • Handling
  • IsVatIncluded
  • Quantity (required)
  • Shipping
  • Title (required if ArticleNumber missing)
  • UnitCode
  • VAT

Amount

Indicates the price of the individual item including the possible VAT. It can have maximum of two decimal places. The amount needs to be described as the lowest monetary unit for the given currency without punctuation marks and excluding any fees. For example: 100,00 NOK is noted as "10000" and 9.99 USD is noted as "999". Please note that when accumulating the total sum of each item, it must match the sum specified for the transaction as a whole in the Amount / Order.Amount parameter.

ArticleNumber

ArticleNumber is a string that specifies the unique identifier for the item.

Discount

Discount for the item. Use the "." character as delimiter.

Handling

Specifies whether the handling is included in the item data, on the boolean format: true or false.

IsVatIncluded

Specifies whether the VAT is included in the item price, on the boolean format: true or false.

Quantity

Quantity of items bought in the specific Item object.

Shipping

Specifies whether the shipping is included in the item data, on the boolean format: true or false.

Title

Title is a string that is the descriptive name or description for the item.

UnitCode

Assigned to each item. The unit code should start from 0 and it will get incremented based on the number of items.

VAT

The value-added tax percentage (VAT%) for the item. Use the "." character as a delimiter. For example: VAT 24% should be set as 24.00 or 24

When refunding the payment, the VAT% for the item to be refunded should match the VAT% of the corresponding original item.

 

Customer loyalty ID

REST: customerLoyaltyId

WebServices: ProcessRequest.CustomerLoyaltyId

Optional

Validation: Custom

MaxLength: 32

Membership identifier for loyalty program. The ID is validated only by its length which can be 10 digits. The same ID can be used several times.

 

Transaction loyalty amount

REST: transactionLoyaltyAmount

WebServices: ProcessRequest.TransactionLoyaltyAmount

Optional

Validation: Numeric

MaxLength: 32

Eligible amount for loyalty, described as the lowest monetary unit for the given currency without punctuation marks. For example: 100,00 EUR is noted as "10000".

 

Payment method benefit amount

REST: paymentMethodBenefitAmount

WebServices: ProcessRequest.PaymentMethodBenefitAmount

Optional

Validation: Numeric

MaxLength: 32

Eligible amount for payment method benefit, described as the lowest monetary unit for the given currency without punctuation marks. For example: 100,00 EUR is noted as "10000".

 

Output parameters

Available output parameters in the ProcessResponse are listed below.

ProcessResponse

Operation

REST: Operation

WebServices: ProcessResponse.Operation

Required

Validation: Alpha

MaxLength: N/A

Echoed from the Process call.

 

Transaction ID

REST: transactionId

WebServices: TransactionId

Required

Validation: Reference

MaxLength: 32

Echoed from the Process call.

 

Sub transaction ID

REST: subTransactionId

WebServices: SubTransactionId

Optional

Validation: Reference

MaxLength: 32

Invoice ID generated for each invoice. Usually one invoice transaction has one invoice ID, however, if you run for example a partial capture for an invoice transaction, an invoice with its own invoice ID will be created.

 

Merchant ID

REST: MerchantId

WebServices: MerchantId

Required

Validation: Reference

MaxLength: 32

Echoed from the Process call.

 

Response code

REST: ResponseCode

WebServices: ProcessResponse.ResponseCode

Required

Validation: AlphaNumeric

MaxLength: N/A

The response code will be set to the string "OK" if the transaction was processed correctly. Any other response is an error, and should be logged with the Response Source and the Response Text. Read more about response codes

 

Response source

REST: ResponseSource

WebServices: ProcessResponse.ResponseSource

Optional (present if Response Code different from "OK")

Validation: AlphaNumeric

MaxLength: N/A

Textual description of which part of the system generated the error code. The error codes are divided into groups according to the source. Read more about error sources

 

Response text

REST: ResponseText

WebServices: ProcessResponse.ResponseText

Optional (present if Response Code different from "OK")

Validation: Custom

MaxLength: N/A

Explains the error code and gives a more detailed description of the error helping the merchant to find out why the transaction failed. Read more about response messages

 

Authorization ID

REST: AuthorizationId

WebServices: ProcessResponse.AuthorizationId

Required (for AUTH)

Validation: Custom

MaxLength: 64

The unique ID given to an authorized transaction by the Issuer.

 

Execution time

REST: ExecutionTime

WebServices: ProcessResponse.ExecutionTime

Required

Validation: Timestamp

MaxLength: N/A

A timestamp indicating when the operation in question was finished. This timestamp is generated on the Netaxept server.

 

Batch number

REST: BatchNumber

WebServices: ProcessResponse.BatchNumber

Required

Validation: Numeric

MaxLength: 3

Specifies which settlement batch this operation belongs to. 

 

Exceptions and response codes

If something goes wrong when communicating between your system and Netaxept or in the middle of the payment process, Netaxept declines the transaction and returns an exception. All exceptions are wrapped in the outer Exception tag, with an Error tag inside. The type (xsi:type) of the Error tag indicates which exception it is. In most cases, the exception includes the error code indicating the error, as well as an error message explaining the code. The Process call can throw the following exceptions. Read more about exceptions > and response codes

  • AuthenticationException
  • BBSException
  • MerchantTranslationException
  • GenericError
  • NotSupportedException
  • ValidationException

 

Next step

Capture the payment

If you have only authorized the transaction, use the Process (Capture) call to debit the money from the customer after the goods has been sent. If necessary, you may capture only a part of the authorised amount.

Credit the payment

If you have already authorized and captured the transaction and the customer returns the product or the purchase is cancelled for any other reason, use the Process (Credit) call to return the captured amount to the customer’s account. If necessary, you can credit only a part of the captured amount.

Cancel the authorization

If you have only authorized the transaction and the purchase is cancelled for some reason, use the Process (Annul) call to cancel the cash provision previously made for the customer's account.

Check the transaction status

If you are unsure about the status of the transaction, use the Query call to check that the transaction has the correct status and the payment has succeeded. Despite of the successfully captured transaction, it is recommended to make the Query call before sending the goods to the customer to verify that the money has actually been captured. This is due to the response times Netaxept from time to time see from third-party payment methods, such as direct bank payments. Read more about the Query call