Card / POS¶

Q: What do I do if the POS payment fails, is cancelled or times out?

Until CompletionPosInvoices the document stays pending and has not been transmitted. If the customer tries the card again, charge again with the same token while it is valid (24 hours, 2 hours for food service), and complete when it succeeds. If the customer finally pays another way, resend the same document, with the same number, with the new payment method. On a timeout, first check on the POS / NSP whether the charge went through. Call the completion only after a successful charge. See: Card / IRIS payments

Q: What happens if I resend the same document with a different payment method, when the first submission was by card with skipSignature=false?

With a card or IRIS payment and skipSignature=false, the document is not transmitted immediately: it stays pending and the response carries a provider signature, until you call CompletionPosInvoices. If in the meantime you resend the same number with a different payment method (e.g. on credit), the second call is issued normally and the first stays pending. This is also the right thing to do when the card charge did not go through and the customer pays another way: same number, new payment method, no completion for the unused signature. But if the card was charged, do not resend the document: complete with CompletionPosInvoices, where you also declare the final payment type (7 or 8). See: Card / IRIS payments

Q: Which posNspId do I use for a POS terminal, and in which format (HEX or BASE64) will I get the token?

posNspId tells which NSP the terminal belongs to and sets the format and field order of the signature, e.g. 2 Viva: BASE64. For an NSP that is not on the list, ask it which protocol (format and field order) it requires and pick the matching code, e.g. 98 Other (HEX) or 99 Other (BASE64). The token is already returned in the NSP's format, so you pass it as is, without conversion. See: Lines & payments

Q: What is the correct body format for the CompletionPosInvoices and AskSignatureForOldInvoice calls?

In CompletionPosInvoices the body is an array of objects with signatureToken, transactionId, paymentAmount and, optionally, tipAmount and paymentType. A bare object is rejected. In AskSignatureForOldInvoice the body is just the document's MARK as a JSON number, and terminalId and posNspId go in the query string. CompletionAskSignatureForOldInvoice takes the same body (the MARK). If an example differs from the API's behavior, the Swagger of each environment prevails. See: Other endpoints

Q: Which aadeProviderId value do I send to the NSP for Novus: 005 or 105?

AADE has two identifiers for Novus Conceptus: provider_id 005 and license_id 105. Each bank / NSP asks for one of the two in its own field (e.g. aadeProviderId). Check the NSP's documentation to see which one it expects, and test first in its sandbox. See: Card / IRIS payments

Provider signature, NSP, special cases.

How does the Provider API fit into card or IRIS payments via POS, and when is a provider signature returned?

For a POS that is "locked" under A.1155/2023, you send the document with SendInvoices?skipSignature=false and payment type 7 (card) or 8 (IRIS), with terminalId and posNspId. The response includes providerSignature (token, data). You pass the token unchanged to the POS/NSP and, after the charge, call CompletionPosInvoices with signatureToken, transactionId, paymentAmount and the final paymentType. The document is then transmitted and you get a MARK. With skipSignature=true (the default), the document is issued immediately without a signature. Each payment line with a signature costs an extra 0.25 credits.

See: Card / IRIS payments

Who connects my application to the bank's POS terminal for card payments?

Your application does, using the API and the sandbox that the bank or payment provider (NSP, e.g. Viva, Mellon, Cardlink, Worldline, Nexi, Euronet, EDPS) gives you. It is a separate integration from the one with the certified e-invoicing provider, which only supplies the provider signature. You send SendInvoices?skipSignature=false with terminalId and posNspId, pass the token to the POS, and after the charge you complete with CompletionPosInvoices. The flow is the same for every NSP.

See: Card / IRIS payments

Does Novus provide a test POS or a POS simulator for testing card payments?

No. For the charge, use the sandbox or test terminal of your NSP (e.g. Viva, Mellon, Cardlink, Worldline, Nexi, Euronet, EDPS). The provider sandbox returns a real signature, in the format the NSP expects (HEX or BASE64), and in the sandbox CompletionPosInvoices also accepts a test transactionId. So you can test the whole flow on the provider side without a terminal, with ready-made steps in Postman (folder 4).

See: Card / IRIS payments

What do I do if the POS payment fails, is cancelled or times out?

Until CompletionPosInvoices the document stays pending and has not been transmitted. If the customer tries the card again, charge again with the same token while it is valid (24 hours, 2 hours for food service), and complete when it succeeds. If the customer finally pays another way, resend the same document, with the same number, with the new payment method. On a timeout, first check on the POS / NSP whether the charge went through. Call the completion only after a successful charge.

See: Card / IRIS payments

Is a separate test or certification scenario needed for IRIS payments (paymentType 8)?

No. IRIS follows the same flow as a card: provider signature, charge on the terminal, CompletionPosInvoices. If the customer switches method on the terminal (e.g. from card to IRIS), declare 8 as the final paymentType in the completion. Card / IRIS payments are not certified: you declare them in the certification request.

See: Card / IRIS payments

What happens if I resend the same document with a different payment method, when the first submission was by card with skipSignature=false?

With a card or IRIS payment and skipSignature=false, the document is not transmitted immediately: it stays pending and the response carries a provider signature, until you call CompletionPosInvoices. If in the meantime you resend the same number with a different payment method (e.g. on credit), the second call is issued normally and the first stays pending. This is also the right thing to do when the card charge did not go through and the customer pays another way: same number, new payment method, no completion for the unused signature. But if the card was charged, do not resend the document: complete with CompletionPosInvoices, where you also declare the final payment type (7 or 8).

See: Card / IRIS payments

Which posNspId do I use for a POS terminal, and in which format (HEX or BASE64) will I get the token?

posNspId tells which NSP the terminal belongs to and sets the format and field order of the signature, e.g. 2 Viva: BASE64. For an NSP that is not on the list, ask it which protocol (format and field order) it requires and pick the matching code, e.g. 98 Other (HEX) or 99 Other (BASE64). The token is already returned in the NSP's format, so you pass it as is, without conversion.

See: Lines & payments

Why is the VAT field in the provider signature data for Viva always 2400, whatever the document?

This field is now legacy. Internal handling also covers documents with several VAT rates, so the NSP and AADE are informed with a fixed value of 24.00% (2400), regardless of the actual VAT. This value does not affect the charge or the completion of the payment. Pass token and data exactly as the Provider returns them.

See: Card / IRIS payments

What is the correct body format for the CompletionPosInvoices and AskSignatureForOldInvoice calls?

In CompletionPosInvoices the body is an array of objects with signatureToken, transactionId, paymentAmount and, optionally, tipAmount and paymentType. A bare object is rejected. In AskSignatureForOldInvoice the body is just the document's MARK as a JSON number, and terminalId and posNspId go in the query string. CompletionAskSignatureForOldInvoice takes the same body (the MARK). If an example differs from the API's behavior, the Swagger of each environment prevails.

See: Other endpoints

Which aadeProviderId value do I send to the NSP for Novus: 005 or 105?

AADE has two identifiers for Novus Conceptus: provider_id 005 and license_id 105. Each bank / NSP asks for one of the two in its own field (e.g. aadeProviderId). Check the NSP's documentation to see which one it expects, and test first in its sandbox.

See: Card / IRIS payments

For an online card payment in an e-shop (no physical POS), is a provider signature needed?

Usually not. Under AADE circular E.2044/2024, distance sales (e-commerce) and payments by payment link are outside the POS integration obligation. You send SendInvoices with skipSignature=true (the default) and payment method type 7, and the document is issued immediately. If the same business also has a physical POS that must be integrated, the signature flow applies there. For each client's specific case, confirm with their accountant.

See: Card / IRIS payments

Can I settle several unpaid documents of a customer with a single card charge on the POS?

Yes, with one aggregate 8.4 document (POS receipt) for the total amount. In the 8.4 you must put the MARKs of the unpaid documents being settled in invoiceHeader.multipleConnectedMarks, so that AADE knows which invoices the payment covers. You send it with skipSignature=false and payment type 7 or 8, get one provider signature, charge once on the POS and complete with CompletionPosInvoices. To settle a single old document, there is also the AskSignatureForOldInvoice flow.

See: Card / IRIS payments

How do I charge a deposit by card on a 'locked' POS, when the main document will be issued later (e.g. a booking invoiced at check-out)?

At the time of the deposit, the application issues an 8.4 (POS receipt) for the amount, with skipSignature=false. It gets the provider signature, the POS charges the card, and the flow closes with CompletionPosInvoices. In the 8.4 you do not declare related documents, since the main document has not been issued yet. When the final invoice or receipt is issued, put the MARK of the 8.4 in multipleConnectedMarks.

See: Card / IRIS payments

How do I refund a card through a 'locked' POS that requires a provider signature?

There is no separate endpoint for a "refund signature". You issue the proper credit document (e.g. 11.4 or a credit invoice) with a POS payment method (type 7 or 8) and skipSignature=false, as in the original sale. With the provider signature you get, the terminal refunds the card, and you close the flow with CompletionPosInvoices. For a refund made only on the POS that does not match an issued sales document (e.g. a deposit refund), you issue an 8.5 (POS refund receipt) and use its signature.

See: Card / IRIS payments

For POS transactions such as mail order, instalments, preloaded or pre-authorization completion, do I need a different provider signature?

No. You use the same signature that SendInvoices returns with skipSignature=false and pass it to the terminal as in a simple sale. The specifics of each transaction type (mail order, instalments, pre-authorization, etc.) only concern the communication between your application and the terminal through the NSP's protocol. They do not affect the provider signature.

See: Card / IRIS payments