Card payments — ValitorPay

With ValitorPay you take card payments through Rapyd's payment gateway, both online and in the Point of Sale. Online, customers pay by card in the webshop, on quotations and orders in the customer portal, and for subscriptions. In the Point of Sale, they pay on a Rapyd card terminal connected to the till.

The sections Before you start, Setup and Daily use cover online payments first and card terminals second.

Before you start

Card payments rely on your agreement with Rapyd. Exigo installs the add-ons in Odoo.

What online payments need

You arrange these with Rapyd:

• An acquiring agreement and the ValitorPay gateway. You need a card acquiring agreement with Rapyd and the ValitorPay gateway active on your merchant account. Without the gateway, Rapyd rejects the keys as "unauthorized".
• 3-D Secure for all card types, enabled on the agreement. Every new card payment starts with a 3-D Secure verification before the card is charged.
• Rapyd's review of your website. Rapyd reviews the website, including a terms page, before the gateway is activated.
• Every currency the webshop sells in. Odoo sends the order's currency and amount to ValitorPay unchanged, so the agreement must cover each currency.
• An API key for the ValitorPay gateway. A production key for the Enabled state, which Rapyd sends as a secure or encrypted message, and a test (UAT) key for Test Mode.

In Odoo you need the Accounting or Invoicing app for the payment journal, Website with eCommerce if you sell online, and the Subscriptions app (Enterprise) if customers pay subscriptions with a saved card.

What card terminals need

• Rapyd/Valitor card terminals, which connect to the till through Rapyd's CloudLink service. Exigo has tested the connection with a PAX A920 terminal.
• The serial number of each terminal, grouped by store. You provide these.
• A CloudLink API key, entered on each terminal payment method in Odoo.
• Rapyd's approval of the Odoo web address. Rapyd/ValitorPay must allow the web address that receives replies from the terminals. Terminal replies do not arrive at any other address.
• The Point of Sale app in Odoo. Exigo installs the add-on and pairs the terminals.

What Odoo does not do with ValitorPay

• Refunding an online card payment from Odoo. A credit note in Odoo does not refund the card.
• Apple Pay and Google Pay, or other express checkout.
• Manual capture (charging the card later).
• Saved cards for ordinary purchases. Customers cannot save their card when paying, and saved ValitorPay cards are not offered at checkout. Cards are saved for subscriptions only.
• Other acquirers. The add-on supports only Rapyd's ValitorPay gateway.

Setup

Exigo handles the steps that name Exigo.

Setting up online payments

1. Exigo installs the add-on Exigo Payment Provider: ValitorPay. It creates the payment provider ValitorPay with the payment methods Card, Visa, Mastercard, Maestro and Amex.
2. Exigo or your administrator opens the provider: go to Accounting ‣ Configuration ‣ Online Payments ‣ Payment Providers and choose ValitorPay. It is also under Website ‣ Configuration ‣ eCommerce ‣ Payment Providers.
3. Exigo enters the API key in the API Key field on the Credentials tab. It is a password field and must be filled in unless the state is Disabled.
4. Choose the State:
   • Test Mode sends every request to Rapyd's test environment and needs a test key. In this state, only users logged in to Odoo see the provider.
   • Enabled sends payments to Rapyd's live environment and needs the production key. Odoo then marks the provider Published and customers see it.
   • Disabled turns the provider off.
5. Exigo or your accountant sets the Payment Journal on the Configuration tab. Every successful card payment is posted as a payment in this journal. The field must be filled in unless the state is Disabled.
6. If needed, limit when the provider is offered in the Availability section of the same tab: by country, currency and maximum amount.
7. Exigo tests with you. First a purchase is made in Test Mode with the test key, by a user logged in to Odoo. Then the state is switched to Enabled with the production key and a real purchase is made.

Changing the API key

A new API key comes from Rapyd when Rapyd replaces the key, with a new agreement, and when you move your acquiring to Rapyd. Card payments in the webshop do not work until the new key is in Odoo. Exigo can enter the key for you, or your administrator does it like this:

1. Get the new key from Rapyd. Rapyd sends the production key as a secure or encrypted message.
2. Go to Accounting ‣ Configuration ‣ Online Payments ‣ Payment Providers and choose ValitorPay.
3. Enter the new key in the API Key field on the Credentials tab.
4. Leave State at Enabled and save.
5. Make a small real purchase in the webshop and complete the 3-D Secure verification. Exigo recommends such a purchase after every key change.
6. If the purchase fails, open the order and read the reason in the chatter. If the new key does not work either, contact Exigo.

[Screenshot: the ValitorPay payment provider, Credentials tab with the API Key field and State = Enabled]

Setting up card terminals

Exigo sets up the terminals with you. You provide the serial number of each terminal, by store.

1. Exigo installs the add-on Exigo POS: Valitor/Rapyd CloudLink API.
2. Go to Point of Sale ‣ Configuration ‣ Payment Methods and create or open the card payment method.
3. Set Integration to Terminal and Integrate with to ValitorPay.
4. Set Mode to Production. The default is Test, which sends requests to Rapyd's test environment. Real terminals work only in Production.
5. Fill in these three required fields:
   • Rapyd/Valitor API key: the CloudLink API key.
   • Rapyd/Valitor Terminal identifier: the terminal's serial number. Each serial number can appear only once in the database.
   • Rapyd/Valitor Timeout: how many seconds the terminal has to answer the first request. The default is 5.
6. Save, click Register Terminal and confirm the pairing on the terminal if it asks. The Rapyd/Valitor device is paired box is ticked once Rapyd has answered Odoo.
7. Add the payment method to the Point of Sale and choose a Journal for it, as for any card payment method.

[Screenshot: Point of Sale payment method with Integration = Terminal, Integrate with = ValitorPay, Mode = Production and the three Rapyd/Valitor fields]

Daily use

Paying in the webshop

1. The customer chooses card payment and fills in the card number, cardholder name, expiry date and security code (CVC).
2. The pay button becomes active once the card number, expiry date and CVC are valid. A 4-digit CVC (Amex) is accepted.
3. After the customer clicks the pay button, a 3-D Secure verification from their bank replaces the checkout page.
4. Once the bank approves, Odoo charges the card and sends the customer to the payment status page.

[Screenshot: the card form in the webshop with its four fields and the pay button]

When the payment succeeds, the transaction becomes Confirmed and Odoo:

• confirms the quotation if the amount paid reaches the order total;
• sends the confirmation;
• creates and sends the invoice if automatic invoicing is on;
• posts a payment in the payment journal.

When the payment fails, Odoo writes the error and its reason in the order's chatter. Reasons from ValitorPay are in English, for example "3D Secure card verification failed." or "ValitorPay standard card payment failed."

The customer then sees a message in English, for example "We are not able to process your payment." or "3DS card verification failed. Please try again or contact support."

The order confirmation page shows a red Retry Payment button whenever the order's payment is not confirmed. It puts the same order back in the cart, as long as the order is still an unsent quotation. If ValitorPay's answer never arrived, the customer goes back to the shop with an empty cart and no button appears.

[Screenshot: order confirmation page with the red Retry Payment button]

If the customer leaves the payment page before it finishes, a scheduled job completes the order, provided ValitorPay had answered. See Scheduled jobs.

Subscriptions and saved cards

• When a subscription order is paid online, Odoo saves the card. ValitorPay creates a virtual card for recurring charges, and Odoo stores it as the customer's saved card.
• The daily subscription job charges the saved card at renewal, without 3-D Secure.
• If the card issuer answers with a replacement card, Odoo updates the saved card automatically.
• A card that staff type in for a customer, for example over the phone, still needs the customer's 3-D Secure approval.

Paying on a card terminal

1. Choose the ValitorPay payment method on the payment screen. The payment is not sent to the terminal automatically: the line shows Payment request pending and a Send button.
2. Click Send. The line shows Request sent, then Waiting for card once the terminal has accepted the request, with the notice "ValitorPay POS, sale received in the terminal".

[Screenshot: the till payment screen with a ValitorPay line showing Payment request pending and the Send button]

• Approved: The till rings a bell, the line shows Payment Successful and a notice says "ValitorPay POS, transaction completed". The card number, authorization code and merchant ID are saved on the payment and printed on the receipt as "Card number:", "Authorization code:" and "Merchant ID:". If Automatically validate order is on, which is the default, the order is validated.
• Declined: A dialog says "ValitorPay POS, transaction declined" and the line shows Transaction cancelled with a Retry button.
• Cancelled: Cancelling while waiting for the terminal makes Odoo ask the terminal to abort, and the terminal answers "ValitorPay POS, transaction cancelled". Cancelling before Odoo has answered shows "The sale request is not completed yet."
• Terminal busy or in error: The dialogs "ValitorPay POS, terminal is busy", "ValitorPay POS, terminal error" and "Error processing payment callback" appear, and the payment can be retried. If the connection to the server is lost, "Could not connect to the Odoo server, please check your internet connection and try again." appears and the line gets a Retry button.

The terminal uses English and does not print on its own. Amounts go to the terminal in whole krónur, and terminal payments are in Icelandic krónur only.

The payments are under Point of Sale ‣ Orders ‣ Payments. Each payment shows ValitorPay Card number, ValitorPay Authorization Code, ValitorPay Merchant ID and ValitorPay JSON, which is the terminal's raw reply.

Refunds

• Online payments: A card payment cannot be refunded from Odoo. A credit note in Odoo does not refund the card.
• Card terminals: A refund order paid with the ValitorPay payment method sends a refund to the terminal. The line shows Refund in process, and a refund line cannot be cancelled.

Posting payments and Rapyd settlements

• Online payments: Every successful card payment becomes a posted payment in the provider's payment journal, and paid invoices are reconciled automatically. The payment memo is the Odoo transaction reference and the ValitorPay reference, separated by a hyphen. All card types, debit and credit, go to the same journal.
• Terminal payments are posted when the Point of Sale session is closed, to the payment method's journal.
• Rapyd settlements: Odoo does not import settlement files from Rapyd. Rapyd's payouts are matched against these payments with Odoo's standard bank reconciliation.

Scheduled jobs

Exigo's add-ons have no scheduled jobs of their own. These jobs from Odoo itself act on ValitorPay payments:

When something goes wrong

The problems are listed in the order they occur most often now. The reason an online payment failed is shown in the order's chatter.

Card payments in the webshop stopped working

The usual cause is that Rapyd has replaced the API key, or that a new key came with a new agreement or a new gateway.

• Get the current key from Rapyd and enter it as described in Changing the API key.
• Read the reason in the order's chatter. If no key is entered, the payment fails with the error "API Key is not set".
• Make a small real purchase to confirm that payments work.

Contact Exigo if the new key does not work either, or if you want Exigo to enter it.

The payment does not reach the terminal

• Mode on the payment method must be Production. The default is Test.
• "No device token found" means the terminal is not paired. Click Register Terminal on the payment method.
• "ValitorPay POS Payment Method not found." means the Point of Sale has no ValitorPay payment method.
• "Multiple POS ValitorPay Payment Methods are linked to the POS session" means the Point of Sale has more than one ValitorPay payment method. Only one is allowed.
• Rapyd must have allowed the Odoo web address that receives replies from the terminals.

Contact Exigo to install the add-on and pair the terminals.

Customers do not see card payment in the webshop

The usual cause has been a new acquiring agreement that was not yet active at Rapyd.

• Get confirmation from Rapyd that the agreement is active.
• Check that State is Enabled and the provider is Published. In Test Mode, only users logged in to Odoo see it.
• Check the Availability section on the Configuration tab. Limits on country, currency or maximum amount can hide the provider.

Contact Exigo if all of this is in order.

The card was charged but the order is still a quotation

The order can also show up as an abandoned cart, or the payment can land on the wrong order.

• Odoo confirms an order only when the amount paid reaches the order total.
• If ValitorPay answered but the customer's browser did not finish, a scheduled job completes the order within about 10 minutes. Wait 10–15 minutes.
• If ValitorPay's answer never reached Odoo, the transaction stays unfinished and the order remains a quotation, which can show up as an abandoned cart.
• Open the order and read the transaction's state and the error in the chatter.
• Check with Rapyd whether the charge exists before you ask the customer to pay again.

Contact Exigo with the order reference and the time of payment.

"Unauthorized" when the API key is entered

The merchant account at Rapyd does not have the ValitorPay gateway. Ask Rapyd to activate it, then enter the key again.

Contact Exigo if the key is still rejected after Rapyd confirms the service is active.

The till waits for an answer from the terminal

Odoo accepts every reply from the terminal, including a decline without an authorization code, and shows the cashier an error if processing a reply fails. A terminal reply is matched to the right payment even if the cashier has opened another order meanwhile.

• If the till does not show the payment as successful, check on the terminal whether the sale was approved before charging again.
• Force done marks the line paid without confirmation from the terminal, so first check on the terminal whether the sale was approved.
• Force cancel gives up on a cancellation that is waiting for the terminal.

Contact Exigo if the till waits with no message at all.

A customer was charged twice

Odoo blocks a new payment when the order is recorded as fully paid, or when another payment request for the same order is being handled at that moment. A charge that ValitorPay made but Odoo never recorded, however, does not count as a payment in Odoo.

• Check both charges with Rapyd.
• The card cannot be refunded from Odoo.

Contact Exigo if the order in Odoo does not show the payment correctly.

A payment in a foreign currency fails

Odoo sends the order's currency to ValitorPay unchanged, so your agreement with Rapyd must cover the currency. Ask Rapyd to add it to the agreement.

Contact Exigo if the payment still fails after Rapyd has added the currency.

A customer's payment was declined

Common reasons are an expired card, a card over its limit, and a 3-D Secure verification the customer did not finish. An expired card and an exceeded limit are declines by the card issuer, not errors in the webshop.

• Read the reason in the order's chatter, for example "3D Secure card verification failed."
• The customer can try again with the Retry Payment button on the order confirmation page.

Contact Exigo if payments are declined with a 3-D Secure error even though the customer completed the verification.

Odoo 17

Setup and use are the same in substance in Odoo 17. The differences are:

• Icelandic in the webshop. The card fields and error messages are in Icelandic, for example Kortanúmer, Nafn korthafa and Gildir til (MM/YY), and the key field is called API lykill.
• The retry button reads Retry Payment, in English.
• Force done and Force cancel on waiting terminal lines are an Exigo add-on in Odoo 17. In Odoo 19 they are part of Odoo itself.
• Payment taken for another order. If the cashier has moved to another order when the terminal answers, Odoo 17 completes the order that was actually paid and shows "The card payment was taken for another order. That order is paid and still open."
• Terminal setup is the same: the same fields, the same Register Terminal button, and Mode defaults to Test.

See also

• Online payment providers
• Online payments
• Checkout and payment
• Subscriptions and automatic payments
• Payment terminals
• Bank reconciliation
• Credit notes and refunds
• Contact Exigo