During the onboarding process, you already added payment methods to your users' stores. After we enable a payment method, your users can start accepting all of the payment method's variants by default. For example, if you configure visa, they can accept all of its variants, including visadebit, visapremiumcredit, visasignature and so on.
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 country/region and currency of 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.
| Requirement | Description | |
|---|---|---|
| Integration type | You must have an online or in-person payments integration with Adyen. | |
| API credential roles | Your Management API credential must have the following role:
|
|
| Webhooks | Subscribe to the following webhooks:
|
|
| Limitations |
|
|
| Setup steps | Before requesting a payment method, make sure that you already configured both your user's store and business lines. |
Request payment methods
To request a payment method for your user's store, 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 variant. Some payment methods require additional configuration or parameters. For details, see the Supported payment methods. |
| 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 for which you want to request a payment method. |
| 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:
The response contains the id of the requested payment method.
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:
| Parameter | Description | Value |
|---|---|---|
| verificationStatus | The status of the verification checks for the capability. | valid |
| enabled | Indicates whether the capability is enabled. | true |
| allowed | Indicates whether the capability is allowed. Adyen sets this to true if the verification is successful and the account holder is permitted to use the capability. | true |
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:
- storeIds: 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.
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:
| Parameter | Required | Description |
|---|---|---|
| countries | The list of countries to enable with the payment method. If sent empty, then all countries are supported by the payment method. | |
| currencies | The list of currencies to enable with the payment method. If sent empty, then all currencies are supported by the payment method. | |
| enabled | Indicates whether the payment method is enabled (true) or disabled (false). |
Disabled payment methods are automatically deleted after 90 days. Payment methods linked to a closed store are automatically disabled and deleted after 90 days.
Here's an example of requesting to update 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.