Wero

• Overview
• Countries & currencies
• Integration
• Process flows
• Testing
• Additional information
• Consumer experience
• Reporting
• FAQ

Integration

You have two options when it comes to processing Wero payments. You can either use our hosted checkout pages or directly initiate payments on our platform and use your own checkout page. Both options are available to you, so you can choose the one that best suits your needs.

Before you begin

To follow along with this guide, please ensure that you have the following ready:

• The correct API endpoint
• A way to construct the authorization header (API Explorer, SDKs, etc.)
• A way to send REST API calls (API Explorer, SDKs, etc.)

MyCheckout hosted payment pages

If you're looking for the quickest way to accept Wero payments, our MyCheckout hosted payment pages is the optimal solution. By using this service, you'll be able to smoothly process payments and provide your customers with a convenient, hassle-free payment experience.

To initiate the desired action, execute POST /v1/{merchantId}/hostedcheckouts API call. This request enables you to interact with the hosted checkouts functionality, allowing seamless integration and customization for an enhanced user experience.

{
   "order": {
    "amountOfMoney": {
      "currencyCode": "EUR",
      "amount": 1000
    },
    "customer": {
      "merchantCustomerId": "123456547",
      "billingAddress": {
        "countryCode": "NL"
      }
    }
  }
}

{
   "RETURNMAC" : "10def562-6f86-4669-9a67-5177410a6a65",
   "hostedCheckoutId" : "066b137f-4665-71ff-af47-5653483a922f",
   "partialRedirectUrl" : "pay.int.checkout.worldline-solutions.com/checkout/9991-ab040093f6014115be7f4aa1c2e0f532:066b137f-4665-71ff-af47-5653483a922f:b8f953b63d554d71bc71a193958b024b"
}

From the response, the important properties are:

• hostedCheckoutId – can be used in subsequent API calls to retrieve the transaction details (with Get hosted checkout status API call);
• partialRedirectUrl – is used to create the URL to which the customer needs to be redirected. By default, we configure every account with the subdomain payment, so you can always connect https://payment. with the partialRedirectUrl, for example:

https://payment.pay2.preprod.checkout.worldline-solutions.com/checkout/9991......

For more information on customizing the checkout page, please refer to our MyCheckout hosted payment pages guide.

Using your own checkout page

If you choose to not use the MyCheckout hosted payment pages option, perhaps that you require more styling customization options, or already have an existing payment page, you can build a direct integration using our SDKs (or integrate our API from scratch). Within this option, you have variations depending on how you wish to integrate.

Client encryption

Our Client API allows you to perform various actions. All you need is to be able to create a session via the POST/v1/{merchantId}/sessions API call, which will grant you access to the Client API.

It's highly recommended that you use our Client SDKs, provided for the following programming languages:

• JavaScript
• Java
• Swift
• Objective-C
• Flutter

We also have reference implementations showing how to use these SDKs on GitHub.

By using this integration type, you'll be able to smoothly process payments and provide your customers with a convenient payment experience. To initiate the desired action, execute POST /v1/{merchantId}/payments API call. 

See create payment request with the minimum required data set below. If you want to supplement it with other data, please read the API documentation.

{
    "order": {
        "amountOfMoney": {
            "amount": 1000,
            "currencyCode": "EUR"
        },
        "customer": {
            "billingAddress": {
                "countryCode": "NL"
            }
        }
    },
    "redirectPaymentMethodSpecificInput": {
        "paymentProductId": 900,
        "redirectionData": {
            "returnUrl": "https://www.example.com"
        }
    }
}

Consumer redirection

If you use POST /v1/{merchantId}/payments API call, you also need to take care of the consumer redirection (in the case of POST /v1/{merchantId}/hostedcheckouts, we handle it ourselves). We'll return a merchantAction object. While there are several different actionType values, for payment product name transactions, we consistently return the actionType value as REDIRECT. Along with this, a redirectData object is included, containing a redirectURL. You'll need to direct your consumer to this URL to complete their payment.

Be aware that the merchantAction is only returned in the response to POST /v1/{merchantId}/payments and looks like this:

{
   "creationOutput" : {
      "additionalReference" : "00000880050000091417",
      "externalReference" : "000008800500000914170000100001"
   },
   "merchantAction" : {
      "actionType" : "REDIRECT",
      "redirectData" : {
         "RETURNMAC" : "fd9200d3-ddf5-4f4a-b0f4-01ad01cf9df2",
         "redirectURL" : "https://example.com/api/open/v1/ac/checkout.htm?codeValue=281666040097Ph7t0bsVIzSv5H1k6dSv4Z4N&loadMode=2"
      },
      "showData" : [ ]
   },
   "payment" : {
      "id" : "000008800500000914170000100001",
      "paymentOutput" : {
         "amountOfMoney" : {
            "amount" : 1000,
            "currencyCode" : "EUR"
         },
         "references" : {
            "paymentReference" : "170109005160"
         },
         "paymentMethod" : "redirect",
         "redirectPaymentMethodSpecificOutput" : {
            "paymentProductId" : 900
         }
      },
      "status" : "REDIRECTED",
      "statusOutput" : {
         "isCancellable" : false,
         "isRetriable" : false,
         "statusCategory" : "PENDING_PAYMENT",
         "statusCode" : 50,
         "statusCodeChangeDateTime" : "20240805221259",
         "isAuthorized" : false,
         "isRefundable" : false
      }
   }
}

The merchantAction is omitted from the GET /v1/{merchantId}/payments/{paymentId} API call and will return a response like this:

{
   "id" : "000008800510000157710000100001",
   "paymentOutput" : {
      "amountOfMoney" : {
         "amount" : 1000,
         "currencyCode" : "EUR"
      },
      "references" : {
         "paymentReference" : "T8850006WTMA"
      },
      "paymentMethod" : "redirect",
      "redirectPaymentMethodSpecificOutput" : {
         "paymentProductId" : 900
      }
   },
   "status" : "REDIRECTED",
   "statusOutput" : {
      "isCancellable" : false,
      "isRetriable" : false,
      "statusCategory" : "PENDING_PAYMENT",
      "statusCode" : 50,
      "statusCodeChangeDateTime" : "20241216151358",
      "isAuthorized" : false,
      "isRefundable" : false
   }
}

Refund

To start a refund process, you should use the API call POST /v1/{merchantId}/payments/{paymentId}/refund. This action is only applicable if the payment status is PAID. If you wish to refund the full order amount, you can do so by sending a request using this API call, but with the only parameter refundReason:

{
  "refundReason": "RETURN"
}

refundReason is a mandatory parameter to refund a Wero transaction, and its value specifies the reason for the refund request. Possible values are:

• RETURN
• CORRECTION
• PRE_DISPUTE
• SUBSCRIPTION
• SERVICE_LATE_CANCELLATION
• OTHER

You have the option to refund a part of the funds as well. For this, it's necessary to include a payload with the amountOfMoney object, where you specify the amount and the currencyCode:

{
  "amountOfMoney": {
    "amount": 200,
    "currencyCode": "EUR"
  },
  "refundReason": "RETURN"
}

Additionally, if you want to view the details of your refund, you can use the API call GET /v1/{merchantId}/refunds/{refundId}.

Webhooks

To track transaction status updates, you can subscribe to the following webhooks notifications:

• payment.created
• payment.redirected
• payment.pending_payment
• payment.captured
• payment.paid