Walley for API-only

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

The API response contains paymentMethod.type: walley for business-to-consumer and paymentMethod.type: walley_b2b for business-to-business.

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

1. To complete the payment, redirect the shopper to the action.url returned in the /payments response.

   When using the HTTP GET method:
   For security reasons, when displaying 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.

2. 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-decoded redirectResult returned when the shopper was redirected back to your site.

3. 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

1. 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've 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.

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:
  • For an account with the automatic capture turned on, include captureDelayHours in your /payments request to override the automatic capture value.
  • For an account without automatic capture turned on, ensure your capture request is done at least 10s after the /payments request.

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:

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 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 don't 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.

In case we receive the money after this point, you receive a CHARGEBACK_REVERSED webhook.

Test and go live

There is no test environment available for Walley. Verify payments with real payment details and small amounts.

Check the status of Walley verification payments in your Customer Area > Transactions > Payments.

See also