API guide — Reconcile with vIBAN

Before you start

This guide walks you through an example of usage of the Memo Bank API – leverage vIBAN to easily reconcile.

📑 For an in-depth understanding of the Memo Bank API resources and how you can interact with them, take a tour of our Memo Bank API Reference.

API authentication and signature

Each request to the Memo Bank API must be authenticated. See on API Reference | Getting started how to create and manage your API credentials, create and sign your authentication token.

Setup your webhooks

Memo Bank uses webhooks to inform your system on transaction statuses. Understanding how our webhooks function is essential for tracking the status of incoming/outgoing operations and managing any necessary follow-up after execution.

📑 Follow the API Reference | Webhooks to configure them for your API application and find all the details on the webhooks events structure.

What is a virtual IBAN (vIBAN)?

A Memo Bank account can have two types of IBANs.

• The main IBAN is the traditional IBAN which serves as the primary identifier for a bank account.
• The virtual IBAN acts as an alias for the main IBAN. You can create, activate, and deactivate virtual IBANs as needed using our API. These IBANs are fully bidirectional, meaning you can use them to both send and receive transactions. They are particularly useful for isolating different use cases and making transaction reconciliation easier.

Create a virtual IBAN

When onboarding a new customer (or user), you can create a virtual IBAN using our API. Simply send a POST request to the /v2/ibans endpoint, providing the name and account_id . Upon a valid request, the API will respond with a 200 OK status.

{
  "id": "fe98f29d-5165-45ff-83f9-d7aa83e970b5",
  "account_id": "de2284c3-0360-4e4a-b10d-771f75b772d4",
  "iban": "FR7617338000037890121285329",
  "name": "Customer 12345",
  "status": "active",
  "type": "virtual",
  "allow_collections": true,
  "is_deleted": false
}

The response will include the id and the generated iban of the virtual IBAN. Be sure to store this information and associate it with the relevant customer in your system.

Initiate a transfer or collection

Once you’ve generated a virtual IBAN, it can be used in the local_iban field of your outgoing transaction endpoints:

• Collections: Use it in the local_iban field of the POST /v2/collections endpoint, in order to collect subscription payments from a customer, for example.
• Transfers: Use the virtual IBAN in the local_iban field of the POST /v2/transfers endpoint, in order to reimburse customer, for instance.

Receiving funds

For instance, when you accept payments via transfer from customers, all incoming transactions will automatically trigger a webhook:

{
  "id": "3553d37b-0141-4a07-801f-edd205bd64bc",
  "date": "2024-11-13T14:16:26.910514Z",
  "event_type": "transaction_confirmed",
  "resource_type": "transaction",
  "resource_id": "3db15ced-32ff-4ae5-83ce-06d4744829bf"
}

Using the resource_id from the webhook, you can retrieve detailed transaction information by sending a GET request to the v2/transactions/{id} endpoint:

{
	"id": "3db15ced-32ff-4ae5-83ce-06d4744829bf",
	"reference": "11fd1082-cafa-4432-a7dd-b4d1af4a3184",
	"account_id": "de2284c3-0360-4e4a-b10d-771f75b772d4",
	"amount": 500,
	"local_iban": "FR7617338000037890121285329",
	"currency": "EUR",
	"direction": "credit",
	"request_date": "2024-11-12T11:14:02.621261Z",
	"execution_date": "2024-11-12T11:14:02.621261Z",
	"accounting_date": "2024-11-12T11:14:03.119906Z",
	"counterparty_name": "Customer 12345",
	"status": "confirmed",
	"attachment_count": 0,
	"source": {
		"transfer_type": "standard",
		"local_iban": "FR7617338000037890121285329",
		"counterparty_iban": "FR7617338000018068952440364",
		"counterparty_bank_bic": "MEMOFRP2XXX",
		"type": "transfer_incoming"
	}
}

You will now have to filter on the source/type for transfer_incoming and you will be able to check if the customer IBAN in your system correspond to the local_iban .

Going further

Now that you can easily track outgoing and incoming transactions associated to a virtual IBAN, you can easily maintain and store a transaction history of a customer thanks to their virtual IBAN. If you wish, you can also get it using the /v2/transactions endpoint with the local_iban filter.

Additionally, many API users track balances for each of their customers by leveraging transaction webhooks. When a new transaction occurs, you will be able to consolidate the balance based on the local_iban available after getting each transaction detail. This approach ensures accurate and up-to-date tracking of customer-specific balances.