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
- Test: https://test.epayment.nets.eu/Netaxept/Process.aspx
- Production: https://epayment.nets.eu/Netaxept/Process.aspx
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:
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:
| ||
| 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 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 response code. The response codes are divided into groups according to the source. Read more about response sources | ||
| Response text | REST: ResponseText | WebServices: ProcessResponse.ResponseText |
| Optional (present if Response Code different from "OK") | Validation: Custom | MaxLength: N/A |
| Explains the response code and gives a more detailed description of the response code. 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