Manage payment methods with API

During the onboarding process, you add payment methods to your users' stores. After we enable a payment method, your users can accept all of its payment method variants by default. For example, if you configure visa, they can also accept visadebit, visapremiumcredit, and visasignature.

This page explains how you can:

• Request additional payment methods.
• View all payment methods configured for your merchant account or store.
• View the details of a specific payment method.
• Update the countries or regions and currencies where your users can accept a payment method.
• Enable or disable a payment method for your user.

Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

Payment method types

The type field identifies the payment method type that you want to add to a store. This is a card scheme, such as visa or mc, or a wallet, such as applepay, googlepay, or vipps. For the values that you can send, see the supported payment methods for platforms.

Your users can then accept the payment method variants that belong to that payment method type. A variant is more specific than a type: it identifies a single card product, or a card and wallet combination. For example, when you add visa, your users can accept payment method variants such as visadebit or visaalphabankbonus. When you add applepay, Adyen adds a payment method variant such as visa_applepay for each card scheme that you added. The value that you send is always the type.

Transaction data can contain the payment method variant:

• For in-person payments, the Terminal API AdditionalResponse contains both values, for example paymentMethod as mc and paymentMethodVariant as mccredit.
• For online payments, standard webhooks can contain additionalData.paymentMethodVariant when you turn on the Include Subvariant additional setting.

How it works

Payment method configuration has the following flow:

1. Identify the payment method type that you want to add. Check the supported payment methods for platforms list to see whether that type needs additional parameters.

2. Send a request to add the payment method.

   • If the payment method needs no method-specific settings, send type and the applicable common parameters. For example, when you add Alipay, you set type to alipay and send shopperInteraction as a common parameter. Some payment method types accept an optional object for extra settings, such as the transaction description.
   • If the payment method needs method-specific settings, also send an object named after the payment method. For example, when you add Klarna, include the klarna object with region, supportEmail, and disputeEmail. The response contains the same object with the settings that Adyen saved.

3. In the API response, identify the id of the payment method. This is an Adyen-generated identifier for the payment method resource, not the payment method type. Adyen processes the request asynchronously and sends a paymentMethod.created webhook when the payment method is added to the store. The payment method becomes available when the account holder's receivePayments capability is enabled, allowed, and valid.

4. Manage payment methods after they are added. You can get payment method details, update their settings, or disable a payment method for a store.

Add payment methods

To add a payment method to your user's store:

1. Make a POST /merchants/{merchantId}/paymentMethodSettings request with your merchant account ID in the path.

   In the body, specify the following parameters:

   Parameter	Required	Description
   type		The payment method type. To determine whether you need to include an additional payment-method-specific object, see the supported payment methods for platforms list.
   storeIds		The id of your user's store. For the list of stores in your merchant account, make a GET /merchants/{merchantId}/stores request.
   businessLineId		The unique identifier of your user's business line. Must be associated with the store in storeIds. Adyen uses the business line's service, industryCode, and salesChannels to determine whether the payment method is eligible for that store. If your user has multiple business lines, specify the one that is associated with the store where you want to add the payment method. When the store has more than one business line, the business line that you specify determines eligibility. The request fails if the payment method is not available for that business line's service, industryCode, or salesChannels.
   countries		The list of countries to enable with the payment method. To enable all countries supported by the payment method, set to ANY or send empty.
   currencies		The list of currencies to enable with the payment method. To enable all currencies supported by the payment method, set to ANY or send empty.

   Here is an example of a request to accept Visa payments from cards issued in the Netherlands:

2. When you get the response:

   • Save the id of the requested payment method. You need this later when maintaining payment methods.
   • Check the verificationStatus. This indicates if the payment method has been added or is still pending. Pending means your user is not able to use the payment method.

3. If the payment method is pending:

   • Check the value of the allowed parameter.
     If this is set to false, this indicates the receivePayments capability of the account holder for whom you added the payment method is not allowed. If this issue is not resolved within 60 days, the payment method activation request is automatically removed.
   • Listen to the following webhooks:
     • balancePlatform.accountHolder.updated: Notifies you about the status of the receivePayments capability. When it is enabled, allowed, and valid, the requested payment method will be automatically available for the user. See Troubleshooting below.
     • paymentMethod.created: Notifies you that your request to add a payment method is completed.
     • paymentMethodRequest.scheduledForRemoval: Notifies you that your request to add a payment method will be removed in 30 days.
     • paymentMethodRequest.removed: Notifies you that your request to add a payment method has been removed.

Webhooks

Because adding a payment method to your user's store is an asynchronous process, we recommend that you subscribe to the Management webhooks in your Customer Area.

After the payment method has been added to your store, Adyen sends a paymentMethod.created webhook.

Here is an example of the webhook you receive after adding Visa to your payment methods:

Troubleshooting

By default, every payment method you request is enabled for your user. However, only verified account holders can use the configured payment methods. This means that the account holder must have the following parameters and values set for the receivePayments capability:

If you update you user's legal entity or account holder information after it has been verified, the payment methods may be disabled until the account holder is verified again.

To check the status of your account holder's receivePayments capability, you can either send a GET /accountHolders/{id} request, or listen to the balancePlatform.accountHolder.updated webhook.

Get a list of all payment methods

To get the details of all payment methods configured on your merchant account, make a GET /merchants/{merchantId}/paymentMethodSettings request with the ID of your merchant account in the path.

You can filter the response using the following query parameters:

• storeId: The unique identifier of the store for which to return the payment methods.
• businessLineId: The unique identifier of the business line for which to return the payment methods.

A /merchants/{merchantId}/paymentMethodSettings response contains the payment method types that you added, such as mc. For wallets, the response can contain two kinds of values:

• The wallet that you added, for example applepay. It appears where you added it: for the merchant account, or for a specific store.
• A payment method variant that Adyen adds for each card scheme that you added, for example mc_applepay.

The following table shows which values you get in each case:

In the following example, you added applepay for the merchant account and mc for a store. A request without the storeId query parameter returns the wallet applepay, and the payment method variant mc_applepay of the store.

A request with the storeId query parameter returns the payment methods of that store. The response contains the payment method variant mc_applepay, but not applepay, because you added it for the merchant account.

Get the details of a specific payment method

To get the details of a specific payment method, make a GET /merchants/{merchantId}/paymentMethodSettings/{paymentMethodId} request with the ID of your merchant account and the payment method in the path.

Update a payment method

To change the settings of a payment method, make a PATCH /merchants/{merchantId}/paymentMethodSettings/{paymentMethodId} request with the ID of your merchant account and the payment method in the path.

In the body, you can specify the following parameters:

Here's an example of a request to update the Visa payment method by adding support for cards issued in the United States:

The response contains the id of the payment method and the updated list of payment method settings.

See also