Partners can use the MultiSafepay API to configure automatic payouts for their affiliated merchant accounts.

An automatic payout transfers funds from an affiliate's MultiSafepay account balance to an active business bank account according to a configured payout schedule.

To set up automatic payouts for an affiliate:

1. Add a business bank account to the affiliate account.
2. Validate the bank account.
3. Retrieve the bank account details and identifier.
4. Configure the automatic payout for the required currency.
5. Retrieve the automatic payout configuration to verify the setup.

Prerequisites

Before you start testing:

• You need a MultiSafepay partner test account and the credentials required to manage your affiliated accounts. You can create a partner test account here: Test partner account
• The affiliate must have a MultiSafepay account. Sign up a test account by making a Create affiliate request.

How to test automatic payouts

Use the TEST environment to test the API flow for configuring automatic payouts for an affiliate:

https://testapi.multisafepay.com/v1/json/

Most request parameters can contain dummy test values. However, parameters that reference an existing resource or require a predefined value must use a valid value from the TEST environment. For example, use the bank account ID returned when creating or retrieving a bank account.

Authentication

Authentication for this endpoint requires an account API key. To obtain your partner account API key, contact your partner manager.

1. Add a business bank account

Add a business bank account to the affiliate account using the Add bank account endpoint.

Provide the required bank account information:

Example request

curl --request POST \
     --url 'https://testapi.multisafepay.com/v1/json/accounts/{{affiliate_account_id}}/bank-accounts?api_key={{partner_api_key}}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "currency": "EUR",
  "holder_name": "John Doe SL",
  "iban": "NL91ABNA0417164300"
}
'

Example response

{
  "data": {
      "currency": "EUR",
      "holder_name": "John Doe SL",
      "iban": "NL91ABNA0417164300",
      "id": "pq5gyt7kznabc"
  },
  "success": true
}

Keep the bank account identifier returned by the API. You need it when configuring the automatic payout. You can also make a List bank accounts request to retrieve all bank accounts created for a specific affiliate. Here, you can retrieve the id for each bank account.

2. Validate the business bank account

Before using the bank account for the automatic payout configuration, validate it using the Validate bank account endpoint.

In the request include:

• The bank account ID you created in the previous request as a path parameter.
• The gateway or payment method used to process the payment as a body parameter. This can either be done with IDEAL (iDEAL | Wero) or BANKTRANS (Bank transfer). If no value is provided, the gateway will be set to BANKTRANS by default.

Example request

curl --request POST \
     --url 'https://testapi.multisafepay.com/v1/json/bank-accounts/{{bankaccount_id}}/payment-links?api_key={{partner_api_key}}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "gateway": "BANKTRANS"
}

Example response

{
    "data": {
        "bankaccount_id": "pq5gyt7kznabc",
        "payment_link": "https://testpayv2.multisafepay.com/connect/823RQO5OslnVodJOh5g4PDyuZJaPdlosR3A3/?lang=nl_NL"
    },
    "success": true
}

Access the payment link to complete the first step of the bank account verification.

Complete the validation payment based on the gateway selected in the request:

Once your affiliate's bank account has been validated, you can proceed to creating an auto payout.

3. Retrieve the business bank account

Track the status of the validated bank account by making a List bank accounts request. If the bank account has been validated, the status will be active .

Example request

curl --request GET \
     --url 'https://testapi.multisafepay.com/v1/json/accounts/{{account_id}}/bank-accounts?api_key={{partner_api_key}}' \
     --header 'accept: application/json' \

Example response

{
  "data": [
    {
      "currency": "EUR",
      "holder_name": "John Doe SL",
      "iban": "NL91ABNA0417164300",
      "id": "pq5gyt7kznabc",
      "status": "active"
    },
    {
      "currency": "EUR",
      "holder_name": "Example Holder Two",
      "iban": "NL91ABNA0412345678",
      "id": "eadw12cscga",
      "status": "pending"
    }
  ],
  "page": {
    "total": 2
  },
  "success": true
}

From the response, identify the bank account you created and validated and retrieve its bank account id for the automatic payout configuration.

4. Configure an automatic payout

Configure the automatic payout using the Create or update auto payout affiliate endpoint.

Automatic payouts are configured for a specific affiliate account and currency.

Configure the following settings:

The minimum amount corresponds to Pay out when balance exceeds in the MultiSafepay dashboard.

The reserve amount corresponds to Set reserve balance in the MultiSafepay dashboard.

When a payout is triggered, the amount is determined by the available account balance and the configured reserve amount (min_balance_amount).

Check the following example of new auto payout:

Example request

curl --request POST \
     --url 'https://testapi.multisafepay.com/v1/json/accounts/{{affiliate_account_id}}/autopayouts/EUR?api_key={{partner_api_key}}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "schedule": [
    "end_of_month"
  ],
  "bankaccount_id": "pq5gyt7kznabc",
  "min_amount": 1000,
  "min_balance_amount": 1000
}
'

Example response

{
    "success": true,
    "data": {
        "currency": "EUR",
        "schedule": [
            "end_of_month"
        ],
        "bankaccount_id": "pq5gyt7kznabc",
        "min_amount": 1000,
        "min_balance_amount": 1000
    }
}

In this example, the automatic payout is scheduled for the end of each month, with the following conditions:

• min_amount is 1000 (EUR 10.00), meaning the account balance must exceed EUR 10.00 before a payout is triggered.
• min_balance_amount is 1000 (EUR 10.00), meaning EUR 10.00 remains in the account after the payout.

In this case, if the available account balance is EUR 100.00, EUR 10.00 remains in the account and EUR 90.00 is paid out at the end of the month.

5. Verify the automatic payout configuration

After configuring the automatic payout, retrieve it to verify that the TEST environment contains the expected settings.

To retrieve the automatic payout configuration for a specific currency, use Get auto payout affiliate.

To retrieve the affiliate's automatic payout configurations, use List auto payouts affiliate.

Verify that the response contains the expected:

• Currency
• Payout schedule
• Business bank account
• Minimum amount
• Reserve amount

Update the automatic payout configuration

To test updating an existing configuration, change one or more payout settings and send another request to the Create or update auto payout affiliate endpoint for the same affiliate account and currency.

Retrieve the configuration again and verify that the updated values are returned.