Quick start guide to integrate with named EUR business accounts

This guide lists the most common integration flow for Business Named EUR Accounts on the Merge Platform.

By the end of this guide you will be able to:

Receive funds into a EUR account
Create and verify beneficiaries
Send EUR payouts
Handle webhook notifications
Test transaction monitoring workflows
Retrieve transaction history
Create named EUR IBANS and manage account lifecycles

Before You Begin(Sandbox)

To complete the steps in this guide, ensure that:

You have valid Merge Sandbox API credentials
Authentication is configured for API requests in your sandbox environment
A publicly accessible webhook endpoint is available to receive event notifications

Step 1 – Configure Webhooks

Webhooks are the primary mechanism for receiving updates from Merge. Before testing any account or payment flows, configure a webhook endpoint.

Add webhook configuration Add Webhook
Check if webhook is added Get Webhook

📘
Get real time updates by listening to webhooks
Production integrations should be webhook-driven. Do not rely on polling for account, payment, compliance, or lifecycle updates.

Step 2 – Retrieve your main EUR account

Once onboarded, your organisation is provisioned with a Main Account. Retrieve the account details and capabilities before initiating any account activity.

Retrieve the EUR main account details and store the main_account ID List main_account.

Information returned:
Account ID
IBAN
Currency
Available Balance
Account Status
Enabled Features

Step 3 – Simulate incoming funds

Fund your account in Sandbox by simulating an incoming payment. This step validates your incoming payment processing and webhook handling.

To simulate an incoming credit, execute Deposit funds.

Expected Outcome

Account balance increases
Transaction created
Payin webhook received and processed on your platform
Transaction visible in transaction history

Step 4 – Reverse a Payin

Received payins can be reversed based on your business logic. This step validates your reconciliation testing.

To reverse a successful payin execute, Reversal.

Expected Outcome

Balance adjustment
New transaction created with payment_type as payout and type_description as payin_reversal
Payout webhook received and processed on your platform

Step 5 – Create a recipient

Before creating a payout, a beneficiary (recipient) must be created. This step validates you are creating the recipient correctly and storing the returned recipient_id for future payouts.

To create a recipient execute, Add recipient.

Expected Outcome

New recipient is created
Recipient ID is stored in your platform

Step 6 – Verification of Payee

Merge supports Verification of Payee(VOP) to validate beneficiary details before funds are released. This step validates the recipient before payout is initiated.

To perform a Verification of Payee check, execute Verify payee.

Expected Outcome

Assess the verification of payee outcome and decide if you wish to proceed with the payout.
The VOP check is executed with the account ID from which the payout will be issued.

Sandbox test data

Expected Result	Account Holder Name	IBAN
match	Isabelle Marie Dubois	FR9317569000707197247234A34
close_match	Isabelle Marie	FR9317569000707197247234A34
no_match	John Nowak	FR9317569000707197247234A34
check_not_possible	TinTin	NL19INGB2128949858

Step 7 – Create a EUR payout

Once a recipient has been verified, initiate a payout with the VOP ID and recipient ID. This step validates the payout is submitted to Merge successfully.

To create a payout execute, Create payout.

Expected Outcome

Idempotency of the payout request is handled to prevent duplicate payment submissions caused by retries or network failures.
The payout request includes VOP attributes. If these attributes are missing Merge will execute the VOP check and proceed only if the verification status is a match.
```
{
  "vop_id": "vop_xxxxx",
  "override_vop_check": true
}
```
The payout request was successfully submitted.
The payout webhook was received and processed successfully.
The payout webhook contains the payment reference and scheme end-to-end transaction ID, which should be stored for reconciliation purposes.

Step 8 – Listen to compliance webhooks

Merge performs transaction monitoring on all incoming an outgoing payments. Your platform must listen to these webhooks and update your systems accordingly. This step validates that your platform is listening to payment compliance statuses and ready for any Request for Information(RFI).

The below webhooks are sent for any payment that is not automatically approved.

For payments placed on compliance hold, released or rejected listen to webhook, event: PAYMENT_COMPLIANCE_STATUS.
For payins that are compliance rejected and reversed listen to webhook, event: PAYMENT_COMPLIANCE_RETURNED.

Expected Outcome

Listen to compliance webhooks when payment goes on hold, released, rejected.
Listen to compliance webhooks when payin is compliance rejected and reversed. The reversal lifecycle generates two events: one when the reversal request is created and another when the reversal is successfully completed.

Sandbox test data

Use the below golden test amounts on payouts to simulate the payout on-hold, rejected and reversed.

Golden test amount	Expected behavior
0.81	Payout is put on compliance-hold and then released.
0.82	Payout is put on compliance-hold and then rejected.
Any other value	Payout is compliance auto-approved.

Step 9 – Create and manage additional named EUR accounts

Manage additional accounts for your business needs. These accounts are real IBANs issued in the name of your registered business. This step validates you are creating new IBANs and managing the life cycle of these accounts.

Integrate with the following API end points for managing the account life cycle.

To create a new account execute, Add account
To block the account execute, Block account
To unblock the account execute, Unblock account
To close the account execute, Close account

Listen to webhooks for each account event.

To get IBAN details listen to event: ACCOUNT_CREATED
To check if account block request is successful listen to, event: ACCOUNT_BLOCKED
To check if account unblock request is successful listen to, event: ACCOUNT_UNBLOCKED
To check if account closure request is successful listen to, event: ACCOUNT_CLOSED
To be notified when Merge suspends an account due to a compliance listen to, event: ACCOUNT_SUSPENDED
To be notified when a suspended account is reinstated after the compliance alert has been resolved listen to, event: ACCOUNT_UNSUSPENDED

Expected Outcome

Create and manage account life cycle
Listen to webhooks to know if the account action initiated was successful
Listen to webhooks when your IBANs are suspended due to compliance
Build business logic to stop payouts from blocked and suspended accounts
Issue payins and payouts from the new IBAN