Skip to content

    Process invoices

    This guide is for developers, who want to implement invoices and process them programatically.

    Before you start

    Before you start accepting invoice payments, you need to sign an agreement with the relevant provider and activate that payment option in your Netaxept Admin Account.

    1. Overview

    The call-response sequence generally follows the card payment flow as described in the Payment Flow - Outline section. But there are a few additional parameters required for invoices.

    Another difference is that the customer can be directed to the invoice provider's site (instead of to the Netaxept hosted payment window) to enter the required payment details. If the provider supports Strong Customer Authentiation (SCA), it is triggered in this phase.

    Invoice payment methods don't support all financial operations. Therefore, you should define the paymentMethodActionList parameter of the Register call to separate invoice from other payment methods in the checkout phase.

    Since the customers payment method is submitted to a third party, you should identify what payment method has been used by sending the Query call after the Terminal phase.

    2. User Journey

    When your customers choose invoice as a payment method, they are directed either to the Netaxept payment window or to the website of the chosen invoice service provider.

    Here, the customer is guided through the payment process and will then be redirected to the redirectURL as specified in the Register call.

    The invoice service provider then sends an invoice to the customer and settles the payment to you within the agreed time.

    3. Required Register call parameters

    When using invoice as a payment method, in addition to the Register call parameters as described before, more parameters become required.

    numberOfGoods

    The Register Call's numberOfGoods parameter is mandatory for invoices. It's value determines, how many different items are invoiced.

    If you are implementing SOAP instead of RESTfulAPI, the organization of parameters is different: Here the Register call's Order object contains a Goods object, which is mandatory for all invoice payments.

    The Goods object contains an array of Items and its set of parameters. One Item object represents one product item.

    numberOfGoods in Register call - Line breaks for readability

    https://test.epayment.nets.eu/Netaxept/Register.aspx?
      merchantId=xxxxxxxx&
      token=xxxxxxxx&
      ordernumber=order852&

    In the example above, the Number of Goods is 2, indicating two items. The following parameters (amount_1, title_1, quantity_1, articleNumber_1, VAT_1, IsVatIncluded_1) refer to the first item.

    The parameters are then repeated for the second item: amount_2, title_2 and so on.

    This can be repeated, but the number of items (n) must be defined in the numberOfGoods parameter: numberOfGoods=n.

    Please note, that for each item amount, title, quantity and articleNumber are mandatory parameters.

    Learn more about aditional parameters in the API reference.

    Customer information

    For invoice, to send customer information becomes mandatory. You can either pass on this information with the Register call, or collect the data on the Netaxept hosted payment window, if it is part of your implementation for the invoice payment flow.

    In addition to

    • customer's country (customerCountry)
    • name (customerFirstName, customerLastName)
    • address (customerAddress1)
    • post code (customerPostcode)
    • town (customerTown)

    as shown in the example above, parameters such as

    • email address (customerEmail)
    • phone number (customerPhoneNumber) and
    • social security number (customerSocialSecurityNumber)

    are required as well for most providers.

    After the invoice has been created but not yet activated (by sending the PROCESS call) it is possible to change the invoice by replacing it's content through your Netaxept Admin account. The Replace function allows you to remove or add order rows, or to change article number, title, quantity, amount or VAT on a specific order row. After you have done the desired changes, you can update the pending invoice by clicking the “Replace” button. Now the new invoice with the updated order rows is ready to be activated. Replacing invoice rows is currently only supported for Walley!

    4. Strong customer authentication (SCA)

    Walley

    As of today, SCA is supported for Walley by sending the Register call's validateCustomer="true" parameter to Netaxept. When using this parameter, the transactionId needs to be at least 21 characters. The authentication method is defined based on the following combinations:

    • Finland when customerCountry=FI and currencyCode=EUR
    • Norway when customerCountry=NO and currencyCode=NOK
    • Sweden when customerCountry=SE and currencyCode=SEK
    • Denmark when customerCountry=DK and currencyCode=DKK

    AfterPay

    For Arvato's AfterPay, no separate parameter needs to be send with the the Register call. Arvato will route the transaction to SCA, based on the logic and rules on their side.

    5. Partial credits and capture

    Partial credit

    To initiate a partial credit of an invoice, you need to send the relevant part of the transaction with the Process(Credit) call to Netaxept.

    The numberOfGoods parameter needs to be adjusted to the number of goods that are subject to the credit operation. The values of the related parameters (amount_1, title_1, quantity_1 and so on) must refer to the items you want to refund.

    Apart from quantity_1, the parameter's values need to be consistent with the parameters for the same item in the original invoice: i.e. if an item in the initial invoice had VAT_1= 24%, then the same item and VAT percentage must be repeated in the Process(Credit) call.

    Partial capture - line breaks for readability

    https://test.epayment.nets.eu/Netaxept/Process.aspx?
    	merchantId=MERCHANTID&
    	token=TESTTOKEN& 
    	transactionId=TRANSACTIONID&

    The example above builds on the example given for invoices earlier:

    Let's assume you want to refund the payment for just 100 out of the 200 pencils that have been ordered and invoiced.

    Here the amount is the amount you want to return: 5000 EUR (100 pencils for 50 EUR each). The numberOfGoods parameter has been changed to 1, since only pencils and no additional items have been returned. The quantity_1 has also changed to 100 (the amount of pencils you want to refund). amount_1 (the price for each pencil) remains the same as in the initial invoice: 50 EUR.

    Partial capture

    Netaxept also supports partial captures for some invoice payment methods (AfterPay, Walley).

    When running partial capture, the Process(CAPTURE) call must contain the numberOfGoods parameter. The corresponding parameter for the item for which you want to capture the funds must be added, similiar to Process(CREDIT) call as shown before.

    As an immediate response to your Process(CAPTURE) (or Process(SALE)) call, you'll get the SubTransactionId. You can also fetch it later, using the Query call.

    The SubTransactionId is required when you want to credit the amount of the partial capture.

    6. Adjusting the invoice amount - Process(ADJUST)

    Adjusting the invoice amount is currently supported for Walley only.

    After an invoice has been activated, you can make adjustments to the invoice's amount with the Process(ADJUST) call.

    Adjustments are used for discounts, price adjustments, delivery and surcharge charges. You can't make adjustments per item individually, it always affects the total invoice amount.

    Before you can send the Process(ADJUST) call, the Process(CAPTURE) has to be sent.

    Required parameters are:
    • adjustmentType: either Positive (amount added to the invoice) or Negative (amount deducted)
    • Goods: an array of item entries, each of them representing one product
    • SubTransactionID: is mandatory, if the adjustment is made on a partially captured transaction.

    You can run the Query call to retrieve the adjusted details for a transaction. Adjusted information for a transaction is available in Netaxept Admin as well.

    Code Sample: Adjusting the invoice amount - linebreaks for readability

    https://test.epayment.nets.eu/Netaxept/Process.aspx?
      merchantId=xxxxxxxx&
      token=xxxxxxxx&
      transactionId=f48eecacdbbc45f7a82b8eec6544cdf8&

    7. Recurring billing

    Recurring billing is currently supported for AfterPay only.

    Recurring billing for AfterPay works similiar to the Easy Payment functionality.

    Initial transaction

    These Register call parameters become required, for the intitial transaction of a recurring billing:

    • recurringType=S
    • paymentMethodActionList: AfterPay must be included

    Apart from that, the flow is similiar to the standart payment flow: you send the Terminal call to direct the customer to the payment window.

    Get the panHash token

    After you have sent the Process(CAPTURE) call, you send the Query call to get the panHash token. Store this token on your database's customer profile.

    Subsequent transactions

    The Register call's parameter for subsequent transactions need to be as follows:

    • panHash: the stored panHash token from the initial transaction
    • recurringType=S
    • serviceType=S
    • paymentMethodActionList: AfterPay must be included

    The payment window is omitted in the customer's payment flow, but you must send the Terminal call after having sent the Register call nonetheless, so that Netaxept can run the authorization of the transaction.

    As usually, the flow ends with you sending the Process(Capture) call.

    8. List of available invoice providers

    9. Invoice - Functionality

    Payment methodPayment method name in APIAUTHCAPTURESALECREDITANNULVERIFY
    Walley invoiceCollectorDone automatically by Netaxept
    Walley B2C invoice with Walley hosted terminal - In pilot! Use for selected merchantsWalleyB2CDone automatically by Netaxept
    Walley invoice B2B invoice with Walley hosted terminal In pilot use for selected merchantsWalleyB2BDone automatically by Netaxept
    Walley instalmentCollectorInstallmentDone automatically by Netaxept
    AfterPay invoice Will be discontinuedGothiaInvoice
    AfterPay instalment - Will be discontinuedGothiaInstallment
    AfterPay New payment methodAfterPayDone automatically by Netaxept
    Enterpay B-to-B invoiceEnterpayDone automatically by Netaxept (either Auth or Sale done automatically)Done automatically by Netaxept