Accept Walley payments using our APIs, and build your own payment form to have full control over the look and feel of your checkout page.
Before you begin
Before continuing, complete the following:
- Build your API-only integration.
- Add Walley in your Customer Area by contacting our Support Team.
Walley requires at least Checkout API v66.
Build your payment form for Walley
Include Walley in the list of available payment methods.
To make a Walley payment, collect the following shopper details:
- telephoneNumber
- shopperEmail
- company.name - in the case of a business-to-business payment (required)
- company.registrationNumber - in the case of a business-to-business payment (optional)
If you are using the /paymentMethods endpoint to show available payment methods to the shopper, specify these parameters:
Parameter | Possible values | |
---|---|---|
countryCode | - DK - FI - NO - SE |
|
amount.currency | - DKK - EUR - NOK - SEK |
Payments in Denmark (DK) or with the DKK currency are available only for B2C payments.
The API response contains paymentMethod.type
: walley for business-to-consumer and paymentMethod.type
: walley_b2b for business-to-business.
Adyen provides a logo for Walley that you can use on your payment form. For more information, refer to Downloading logos.
Make a payment
You must include the following fields when making a /payments request:
Parameter name | Required | Description |
---|---|---|
telephoneNumber | The shopper's telephone number. You must collect a working mobile phone number (including country code) from the customer. Incorrect or missing numbers will fail Walley's validation. |
|
shopperEmail | The shopper's email address. | |
company.name | The name of the company making the payment. This will be prefilled and presented to the shopper on Walley's payment form. Only required for walley_b2b payments. | |
company.registrationNumber | Only relevant to business-to-business payments. The registration number of the company making the payment. | |
lineItems.id | The ID of the line item. | |
lineItems.description | A description of the line item. | |
lineItems.amountExcludingTax | The item amount excluding the tax, in minor units. | |
lineItems.taxAmount | The tax amount, in minor units. | |
lineItems.taxPercentage | The tax percentage, in minor units. | |
lineItems.quantity | The number of items. |
In the /payments response, note the action
object. This contains the information needed to redirect the shopper.
Handle the redirect
-
To complete the payment, redirect the shopper to the
action.url
returned in the /payments response, taking into account the following recommendations:-
When using the HTTP GET method:
For security reasons, when showing the redirect in the app, we recommend that you use SFSafariViewController for iOS or Chrome Custom Tabs for Android, instead of WebView objects. Also refer to the security best practices for WebView. -
Redirection for mobile integrations:
For mobile integrations, we strongly recommended that you redirect the shopper to the default browser of their device. Redirecting to the default browser ensures the best compatibility, handling of multi-factor authentication, app-to-app redirection, and error handling.
-
-
After the shopper is redirected back to your website, check the payment result by making a POST /payments/details request, specifying:
details
: object that contains the URL-decodedredirectResult
returned when the shopper was redirected back to your site.
-
In the response note the following:
resultCode
: use this to present the result to your shopper.pspReference
: our unique identifier for the transaction.
Show the payment result
- Use the
resultCode
that you received in the /payments/details response to present the payment result to your shopper.
You can receive the following resultCode
values for Walley:
resultCode | Description | Action to take |
---|---|---|
Authorised | The shopper completed their payment, and it has been sent to the bank for processing. In most cases, this means that you will receive the funds. If you are using manual capture, you also need to capture the payment. | Inform the shopper that the payment has been successful. |
Cancelled | The shopper cancelled the payment while on their bank's website. | Ask the shopper whether they want to continue with the order, or ask them to select a different payment method. |
Error | There was an error when the payment was being processed. | Inform the shopper that there was an error processing their payment. The response contains a refusalReason , indicating the cause of the error. |
Pending or Received |
The shopper has completed the payment but the final result is not yet known. | Inform the shopper that you have received their order, and are waiting for the payment to be completed. You will receive the final result of the payment in an AUTHORISATION webhook. |
Refused | The payment was refused by the shopper's bank. | Ask the shopper to try the payment again using a different payment method. |
You also receive the outcome of the payment asynchronously in a webhook. If the shopper failed to return to your website or app, wait for notification webhooks to know the outcome of the payment. You can receive the following notification webhooks for Walley:
eventCode | success field | Description | Action to take |
---|---|---|---|
AUTHORISATION | false | The transaction failed. | Cancel the order and inform the shopper that the payment failed. |
AUTHORISATION | true | The shopper successfully completed the payment. | Inform the shopper that the payment has been successful and proceed with the order. |
Capture the payment
After the goods have been sent, you also need to capture the payment.
If the capture is not performed within 90 days, the authorization will expire.
Automatic captures
You can set up automatic captures. By default, this happens immediately after authorization.
However, due to the asynchronous nature of a 202 status
(success) response from Walley, it may take a few seconds before the update can be shown in all relevant systems and responses to API requests.
Therefore, an automatic capture may result in a 403 status
(forbidden) response.
Solutions:
- In the account settings, set the automatic capture to at least 1 day, not to immediate.
- Do a manual capture:
Partial captures
To partially capture a Walley payment, specify in your /payments/{paymentPspReference}/captures request:
Parameter | Description |
---|---|
amount |
The amount that the shopper should pay. |
lineItems |
Price and product information for the items that the shopper should pay for. You only need to specify lineItems if you are sending a partial capture, not if you are sending a full capture. The sum of the lineItems must match the amount declared in the capture call, otherwise Adyen will add a dummy lineItems entry to account for the difference. |
Only specify the items that you are capturing.
In the case of business-to-business payments:
- The
lineItems
values must match the values that were provided for authorization. - Captures using only
amount
can be used with full captures, not with partial captures. When used, all authorized items will automatically be captured and included on the invoice.
The following example shows how to make a partial capture request if the shopper only kept item #1 of the order.
The following response is returned:
Manually cancel any amount that remains after partially capturing a payment.
Refunds and cancellations
If you have not captured a Walley payment, you can cancel it. If you have captured the payment and you want to return the funds to the shopper, you need to refund it.
As with captures, you don’t need to specify lineItems
in the refund request if you are doing a full refund. To partially refund a Walley payment, specify in your /payments/{paymentPspReference}/refunds request:
Parameter | Description |
---|---|
amount |
The amount that is refunded to the shopper. |
lineItems |
Price and product information for the items that the shopper should pay for. The sum of the lineItems needs to match the amount declared in the refund call. If they do not match, Adyen will add a dummy lineItem entry to account for the difference. |
Only specify the items that you are refunding the money for.
The following example shows how to make a partial refund for item #1 of the above order.
The following response is returned:
The pspReference
is specifically for the refund transaction, not for the original payment.
Chargebacks
In rare scenarios it is possible that you do not receive the funds even after receiving a successful AUTHORISATION webhook. The successful AUTHORISATION webhook means that the payment has passed the verifications that the issuer and Walley run on the shopper account, and that the bank transfer was initiated successfully. However, the payment can still fail for the following reasons:
- The shopper cancelled the transaction. Banks in some countries/regions allow shoppers to cancel bank transfers until midnight of the day of the transaction.
- Some banks process transactions with a delay and do not block the funds for an authorized Walley payment. For example, if the shopper completes a Walley payment on a Saturday, the bank might only process it on Monday. If the shopper has withdrawn sufficient funds in the meantime, the payment will fail.
In these cases, Adyen is not informed that the transaction failed. We also do not know whether the bank might still process it later.
On our side, the status of the payment is SentForSettle until we receive the funds. You can check the status of the payment in your Customer Area.
If we have not received the funds after 8 calendar days, the status of the payment becomes Settled, then Chargeback, and you receive a CHARGEBACK webhook.
You cannot defend Walley chargebacks.
In case we receive the money after this point, you receive a CHARGEBACK_REVERSED webhook.
Test and go live
You can perform the test scenarios described on Walley's technical documentation using Adyen's /payments endpoint. Consider the following:
- Include the
CivRegNo
as the socialSecurityNumber. - When testing a Walley B2B transaction, provide the company information as shown in the following example:
"company": { "name": "Adyen N.V.", "registrationNumber": "5562000116" }
Check the status of Walley verification payments in your Customer Area > Transactions > Payments.