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.

Requirements

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 in your request one of the following combinations of countryCode and amount.currency:

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. Maximum length: 50 characters.
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, 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.

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:

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:

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:
  • 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:

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:

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:

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.

See also