menu

Payment API

What's on this page

Online Payments / Payment Methods / Wero

Wero

Shopper Country Sale Refund Authorise / Capture Void Token Vault Mandates
Worldwide ✓ ✓

Introduction

Wero is a new payment method that is being developed to replace iDEAL in the Netherlands and as a new payment method in the rest of the world. The payment method is developed by EPI (European Payments Initiative) as a new European alternative payment method.

Note

Wero is still under development and is not yet available for production use.

Collecting

Wero is a collecting payment method, i.e. CCV receives the money from the consumer banks and pays out the merchants. See our payouts section for more information on how CCV handles payouts for Wero.

Typical Wero Transaction Flow

  1. The consumer selects Wero as a payment method on your checkout page.
  2. The consumer is redirected to the Wero payment page.
  3. The consumer completes the payment on the Wero payment page.
  4. After payment completion, the consumer is redirected towards your webshop or app.

Before you begin

  • If you haven’t done so already, make sure to set up your test account and get your API key to start testing. Contact ecommerce@ccv.eu for questions surrounding your test account and credentials. Contact psp-support@ccv.eu for technical support.

Note

Keep in mind that your API key must not be exposed to the customer for any reason whatsoever.

Wero Transaction Processing Through CCV

The below steps describe a typical integration through CCV for Wero transactions:

  1. The customer is done shopping and proceeds to checkout.
  2. You request their/her authentication or a new registration in order to gather personal information.
  3. Once the authentication is complete, you present the customer with the possible payment methods.
  4. The customer selects payment method Wero.
  5. At this point you want us to handle the payment. Your backend system initiates a payment transaction using the API. See also Create a new payment.
    • Specify a returnUrl to where the customer should be redirected after the payment is completed (successfully or otherwise). This can be a link to your webshop or a deep link to your mobile application.
    • You can register to our notification system to receive notifications regarding the transaction. Visit our Notifications section for more info.

Example request

curl --basic --user apikey: -H "User-Agent: Shop123456" -H "Idempotency-Reference: 1FAvu5eqNFwohXwPZLJajVecN5AIPaUl7qPFi4jFx4Hvt4SeUO" -H "Content-Type: application/json" --data '{  "amount" : 0.10,  "currency" : "eur",  "method" : "wero",  "returnUrl" : "https://shop/return?order=123456",  "merchantOrderReference" : "123456",  "description" : "Order 123456",  "language" : "eng" }' https://api.psp.ccv.eu/api/v1/payment

Request body details

{
 "amount" : 0.10,
 "currency" : "eur",
 "method" : "wero",
 "returnUrl" : "https://shop/return?order=123456",
 "merchantOrderReference" : "123456",
 "description" : "Order 123456",
 "language" : "eng"
}
  1. After we validated the input parameters, we’ll return a new payment transaction. See also Payment object.

Example response

{
  "amount": 0.10,
  "created": 1793105552766,
  "currency": "eur",
  "description": "Order 123456",
  "language": "eng",
  "lastUpdate": 1793105552766,
  "merchantOrderReference": "123456",
  "method": "wero",
  "paidout": "no",
  "payUrl": "https://shop-vpos-test.ccvlab.eu/wero/api/consents/b585e691-a506-469a-9451-874ee4dbe28f/landing",
  "reference": "WE261027125232764CB87E18D.B",
  "returnUrl": "https://shop/return?order=123456",
  "status": "pending",
  "type": "sale"
}

  1. Redirect your customer to the payment URL (payUrl) as generated for the payment.

  2. The customer lands on the issuer’s hosted authentication form to complete the payment authentication.

  3. The customer completes the authentication and approves the transaction. Once approved, the customer is redirected towards CCV and CCV will redirect the customer back to the return URL (returnUrl) you provided in the initial payment request, see step 6.

    Import note: You should not imply that the customer will return! See the returnUrl integration consideration below.

  4. At this point you don’t know whether the payment is successful or not.

  • You must request the status of the payment to complete your order correctly. See also Read a transaction.

Example request

curl --basic --user apikey: https://api.psp.ccv.eu/api/v1/transaction?reference=WE261026165521585CB87E195.W

Example response

{
  "amount": 0.10,
  "created": 1793105552766,
  "currency": "eur",
  "description": "Order 123456",
  "details": {
    "authorisationStatus": "AUTHORISATION_GRANTED",
    "captureId": "823b7627-5ab6-4cff-990a-50ac603629cd",
    "captureStatus": "CAPTURE_SETTLED",
    "consentId": "b585e691-a506-469a-9451-874ee4dbe28f",
    "consentStatus": "CONSENT_GRANTED",
    "consumerName": "Jane Consumer",
    "methodTransactionStatus": "CAPTURE_SETTLED",
    "paymentRequestId": "79d14156-d67e-4a5f-a5de-d2c4ec10731e"
  },
  "entryMode": "ecom",
  "language": "eng",
  "lastUpdate": 1793105630644,
  "merchantOrderReference": "123456",
  "method": "wero",
  "methodTransactionId": "b585e691-a506-469a-9451-874ee4dbe28f",
  "paidout": "no",
  "payUrl": "https://shop-vpos-test.ccvlab.eu/wero/api/consents/b585e691-a506-469a-9451-874ee4dbe28f/landing",
  "reference": "WE261027125232764CB87E18D.B",
  "returnUrl": "https://shop/return?order=123456",
  "status": "success",
  "statusFinalDate": 1793105629983,
  "type": "sale"
}

  1. Assuming the payment is successful, you can contact the customer by email with a confirmation, show an appropriate notification on the shop, …

  2. As a side effect of completing a payment (successfully or not), we will notify you using either a webhook or notifications. This allows you to perform additional operations in your system like sending an email to your customer.

    Import note: A webhook does not contain any data except our payment reference. You must request the status of the payment before taking actions like shipping the order!

Integration Considerations

CCV PayUrl Mobile Integration

When performing a redirect towards the payUrl from inside a mobile device, we recommend the use of SFSafariViewController for iOS or Chrome Custom Tabs for Android, instead of a WebView.

However, if you decide to use a WebView anyway please consider the following:

  • Security best practices for WebViews.
  • The issuer authentication form for Wero may rely on external banking applications to be accessed from within the WebView. Please make sure your mobile application is able to handle these external deeplinks inside a webview.

Return URL

The return of a customer to your app or webshop (provided by the returnUrl) is the best-case scenario. Many reasons exist for why the customer does not return and some are listed here. It is therefore highly recommended that your business logic does not rely on the customer returning to your app or webshop. The actual transaction status is independent of whether the customer returns or not. You should always verify the status of the actual transaction with CCV to know if the payment succeeded or not. This can be done by using webhooks, notifications on your backend system or by the means of polling the transaction status, see also Read a transaction.

ReturnUrl is opened by the wrong Browser on mobile device

Mobile device users that access your online webshop could experience a returnUrl redirect that is opened inside the wrong browser. This can happen for customers that use a different browser than the default configured browser of the customer’s mobile device. Consider the following scenario: the customer opens the payUrl inside the Opera Mobile browser and authenticates the payment using their/her issuer’s banking app on the same device. After authentication, the issuer’s banking app will redirect the customer to the default browser: eg. Chrome Browser of the customer’s mobile device. Every session data your business logic depends on will be unusable if the customer returns in a different browser. You should be able to handle this difference.

Test and go live

Using your test API key in combination with our API at https://api.psp.ccv.eu/api/v1, you can start testing your integration. Our Wero testing environment uses the payment amount field to trigger various test scenarios.

Test case Transaction Result
66.02 Failed (Consent Timeout)
66.03 Failed with failure code cancelled (Consent Revoked)
67.01 Failed with failure code rejected (Authorisation Rejected)
67.02 Failed with failure code processing_error (Authorisation Failed)
67.03 Failed with failure code cancelled (Authorisation Cancelled)
other Success

Refunds

Wero payments can be refunded. Only successful payments can be refunded. Visit our refund endpoint documentation for more info.

Transition from iDEAL to Wero

At CCV, we are working on a smooth transition from iDEAL to Wero. The payment method for iDEAL in the API is still ideal, but the payment method is now shown to consumers as iDEAL | Wero.

To support the transition, we are adding a new payment method wero in the API. This will allow merchants to start using Wero as a payment method, while still supporting iDEAL for existing merchants.