API docs by Redocly

Getmomo Public API (1.21.0)

Download OpenAPI specification:Download (JSON)

License: Proprietary

Public API for interfacing with the Getmomo service offering.

This API supports both request/response endpoints and webhook event delivery. See the Webhooks section for details on event types, payload schemas, and signature verification.

Deposit Accounts

Endpoints for managing deposit accounts

List all deposit accounts

Retrieves all deposit accounts with pagination support

Authorizations:
bearerAuth
query Parameters
offset
integer >= 0
Default: 0
Example: offset=15

Number of items to skip before returning results

limit
integer [ 1 .. 100 ]
Default: 15
Example: limit=15

Maximum number of items to return

Responses

Response Schema: application/json
offset
required
integer >= 0

Number of items skipped before these results

limit
required
integer [ 1 .. 100 ]

Maximum number of items returned in this response

totalItems
required
integer >= 0

Total number of items available

required
Array of objects (DepositAccount)

List of deposit accounts for the current page

Response samples

Content type
application/json
{
  • "offset": 0,
  • "limit": 15,
  • "totalItems": 2,
  • "items": [
    ]
}

Get a single deposit account

Retrieves a single deposit account by its unique identifier

Authorizations:
bearerAuth
path Parameters
depositAccountId
required
string
Example: q3a2bQPpNz2tu4nkTrjmI

The unique identifier of the deposit account

Responses

Response Schema: application/json
id
required
string

Unique identifier for the entity

createdAt
required
string <date-time>

Timestamp when the entity was created (ISO 8601 with timezone)

updatedAt
string <date-time>

Timestamp when the entity was last updated (ISO 8601 with timezone)

version
required
string^[0-9]+$

Opaque optimistic-concurrency token for the entity. Round-trip this value unchanged on mutating requests (PATCH, DELETE) to detect stale writes.

name
required
string

Name of the deposit account

title
string

Optional title for the deposit account

iban
required
string^[A-Z]{2}[0-9]{2}[A-Z0-9]+$

IBAN of the deposit account

bic
required
string

BIC/SWIFT code of the deposit account

isDefault
required
boolean

Indicates whether this is the default deposit account.

Response samples

Content type
application/json
{
  • "id": "q3a2bQPpNz2tu4nkTrjmI",
  • "createdAt": "2025-09-10T08:30:00+02:00",
  • "updatedAt": "2025-10-23T09:15:00+02:00",
  • "version": "7",
  • "name": "Property Management GmbH",
  • "title": "Primary Account",
  • "iban": "DE89370400440532013000",
  • "bic": "HSHNDEHHXXX",
  • "isDefault": true
}

Virtual Deposit Accounts

Endpoints for managing virtual deposit accounts for rental properties

List all virtual deposit accounts for a deposit account

Retrieves all virtual deposit accounts associated with a specific deposit account with pagination support

Authorizations:
bearerAuth
path Parameters
depositAccountId
required
string
Example: TgQBfyro4OHY6Iza0zPQa

The unique identifier of the deposit account

query Parameters
offset
integer >= 0
Default: 0
Example: offset=15

Number of items to skip before returning results

limit
integer [ 1 .. 100 ]
Default: 15
Example: limit=15

Maximum number of items to return

Responses

Response Schema: application/json
offset
required
integer >= 0

Number of items skipped before these results

limit
required
integer [ 1 .. 100 ]

Maximum number of items returned in this response

totalItems
required
integer >= 0

Total number of items available

required
Array of any (VirtualDepositAccount)

List of virtual deposit accounts for the current page

Response samples

Content type
application/json
{
  • "offset": 0,
  • "limit": 15,
  • "totalItems": 2,
  • "items": [
    ]
}

Create virtual deposit account

Creates a new virtual deposit account for individual tenant(s) or company tenant. Use the 'type' field to specify which type to create.

Authorizations:
bearerAuth
path Parameters
depositAccountId
required
string
Example: EQ4Npb2K_yTUch0oIKWZH

The unique identifier of the deposit account

Request Body schema: application/json
required
givenReference
string

Optional reference for the tenancy. We recommend a combination of the tenancy agreement number and property number (e.g. M03879.Obj0842)

sourceId
string

Optional identifier from your own system. Use this to link the virtual deposit account to records in your property management software or internal database

streetName
required
string

Street name of the rental property

streetNumber
required
string

Street number of the rental property

postalCode
required
string

Postal code of the rental property

region
required
string

Region/state of the rental property

countryCode
required
string
Value: "DE"

Country code. Only 'DE' (Deutschland) is accepted as we only support German addresses

depositAmountCents
required
integer > 0

Deposit amount in cents. Must be a positive integer

rentalContractStartDate
string <date>

Optional start date of the rental contract (ISO 8601 date format, e.g. 2025-01-01)

notes
string

Optional free-text internal notes on the tenancy

payoutNote
string

Optional note describing the payout / settlement of the deposit

moveOutDate
string <date>

Optional date the tenant moved out (ISO 8601 date format, e.g. 2025-08-31)

propertyOwnerId
string or null

Optional identifier of the property owner to assign to this virtual deposit account. A null or omitted value leaves no owner assigned

type
required
string

Type of virtual deposit account. Must be 'INDIVIDUAL'

required
Array of objects (IndividualTenantInput) [ 1 .. 2 ] items

Array of individual tenants (minimum 1, maximum 2)

Responses

Response Schema: application/json
id
required
string

Unique identifier for the entity

createdAt
required
string <date-time>

Timestamp when the entity was created (ISO 8601 with timezone)

updatedAt
string <date-time>

Timestamp when the entity was last updated (ISO 8601 with timezone)

version
required
string^[0-9]+$

Opaque optimistic-concurrency token for the entity. Round-trip this value unchanged on mutating requests (PATCH, DELETE) to detect stale writes.

iban
required
string^[A-Z]{2}[0-9]{2}[A-Z0-9]+$

The virtual IBAN allocated to this virtual deposit account

appLink
required
string <uri>

Deep link to this virtual deposit account in the Manager App

type
required
string

Type of tenant for this virtual deposit account

givenReference
string

Optional reference for the tenancy. We recommend a combination of the tenancy agreement number and property number (e.g. M03879.Obj0842)

sourceId
string

Optional identifier from your own system. Use this to link the virtual deposit account to records in your property management software or internal database

streetName
required
string

Street name of the rental property

streetNumber
required
string

Street number of the rental property

postalCode
required
string

Postal code of the rental property

region
required
string

Region/state of the rental property

countryCode
required
string
Value: "DE"

Country code. Only 'DE' (Deutschland) is accepted as we only support German addresses

depositAmountCents
required
integer > 0

Deposit amount in cents. Must be a positive integer

rentalContractStartDate
string <date>

Optional start date of the rental contract (ISO 8601 date format, e.g. 2025-01-01)

notes
required
string or null

Free-text internal notes on the tenancy. Null if no notes have been recorded

payoutNote
required
string or null

Note describing the payout / settlement of the deposit. Null if no payout note has been recorded

moveOutDate
required
string or null <date>

Date the tenant moved out (ISO 8601 date format, e.g. 2025-08-31). Null if not set

propertyOwnerId
required
string or null

Identifier of the property owner assigned to this virtual deposit account. Null if no owner is assigned

status
required
string
Enum: "INCOMPLETE" "COMPLETE" "PARTIALLY_PAID_OUT" "RESOLVED"

Lifecycle status of the virtual deposit account

rentalContractVersion
required
string^[0-9]+$

Opaque optimistic-concurrency token for the account's rental contract. It increments whenever a top-level (rental-contract-level) field changes. Round-trip this value unchanged when optimistically locking those fields.

rentalContractUpdatedAt
string <date-time>

Timestamp when the account's rental contract was last updated (ISO 8601 with timezone).

required
Array of objects (IndividualTenant) [ 1 .. 2 ] items

Array of tenants (minimum 1, maximum 2)

Request samples

Content type
application/json
Example
{
  • "type": "INDIVIDUAL",
  • "givenReference": "M03879.Obj0842",
  • "sourceId": "pm-2024-unit-789",
  • "tenants": [
    ],
  • "streetName": "Hauptstraße",
  • "streetNumber": "123",
  • "postalCode": "10115",
  • "region": "Berlin",
  • "countryCode": "DE",
  • "depositAmountCents": 200000
}

Response samples

Content type
application/json
Example
{
  • "id": "C9NS3gndTEXrX6CoHIyGy",
  • "createdAt": "2025-10-23T11:00:00+02:00",
  • "version": "1",
  • "iban": "DE89370400440532013000",
  • "appLink": "https://getmomo.app/kautionsverwaltung/barkaution/C9NS3gndTEXrX6CoHIyGy",
  • "type": "INDIVIDUAL",
  • "givenReference": "M03879.Obj0842",
  • "sourceId": "pm-2024-unit-789",
  • "tenants": [
    ],
  • "streetName": "Hauptstraße",
  • "streetNumber": "123",
  • "postalCode": "10115",
  • "region": "Berlin",
  • "countryCode": "DE",
  • "depositAmountCents": 150000,
  • "notes": null,
  • "payoutNote": null,
  • "moveOutDate": null,
  • "propertyOwnerId": null,
  • "status": "INCOMPLETE",
  • "rentalContractVersion": "2"
}

Get a single virtual deposit account

Retrieves a single virtual deposit account by its unique identifier

Authorizations:
bearerAuth
path Parameters
depositAccountId
required
string
Example: iDVh8yNUQ8y2hh1jkXTbi

The unique identifier of the deposit account

virtualDepositAccountId
required
string
Example: C9NS3gndTEXrX6CoHIyGy

The unique identifier of the virtual deposit account

Responses

Response Schema: application/json
id
required
string

Unique identifier for the entity

createdAt
required
string <date-time>

Timestamp when the entity was created (ISO 8601 with timezone)

updatedAt
string <date-time>

Timestamp when the entity was last updated (ISO 8601 with timezone)

version
required
string^[0-9]+$

Opaque optimistic-concurrency token for the entity. Round-trip this value unchanged on mutating requests (PATCH, DELETE) to detect stale writes.

iban
required
string^[A-Z]{2}[0-9]{2}[A-Z0-9]+$

The virtual IBAN allocated to this virtual deposit account

appLink
required
string <uri>

Deep link to this virtual deposit account in the Manager App

type
required
string

Type of tenant for this virtual deposit account

givenReference
string

Optional reference for the tenancy. We recommend a combination of the tenancy agreement number and property number (e.g. M03879.Obj0842)

sourceId
string

Optional identifier from your own system. Use this to link the virtual deposit account to records in your property management software or internal database

streetName
required
string

Street name of the rental property

streetNumber
required
string

Street number of the rental property

postalCode
required
string

Postal code of the rental property

region
required
string

Region/state of the rental property

countryCode
required
string
Value: "DE"

Country code. Only 'DE' (Deutschland) is accepted as we only support German addresses

depositAmountCents
required
integer > 0

Deposit amount in cents. Must be a positive integer

rentalContractStartDate
string <date>

Optional start date of the rental contract (ISO 8601 date format, e.g. 2025-01-01)

notes
required
string or null

Free-text internal notes on the tenancy. Null if no notes have been recorded

payoutNote
required
string or null

Note describing the payout / settlement of the deposit. Null if no payout note has been recorded

moveOutDate
required
string or null <date>

Date the tenant moved out (ISO 8601 date format, e.g. 2025-08-31). Null if not set

propertyOwnerId
required
string or null

Identifier of the property owner assigned to this virtual deposit account. Null if no owner is assigned

status
required
string
Enum: "INCOMPLETE" "COMPLETE" "PARTIALLY_PAID_OUT" "RESOLVED"

Lifecycle status of the virtual deposit account

rentalContractVersion
required
string^[0-9]+$

Opaque optimistic-concurrency token for the account's rental contract. It increments whenever a top-level (rental-contract-level) field changes. Round-trip this value unchanged when optimistically locking those fields.

rentalContractUpdatedAt
string <date-time>

Timestamp when the account's rental contract was last updated (ISO 8601 with timezone).

required
Array of objects (IndividualTenant) [ 1 .. 2 ] items

Array of tenants (minimum 1, maximum 2)

Response samples

Content type
application/json
{
  • "id": "C9NS3gndTEXrX6CoHIyGy",
  • "createdAt": "2025-09-25T10:30:00+02:00",
  • "updatedAt": "2025-10-15T14:20:00+02:00",
  • "version": "3",
  • "iban": "DE89370400440532013000",
  • "appLink": "https://getmomo.app/kautionsverwaltung/barkaution/C9NS3gndTEXrX6CoHIyGy",
  • "type": "INDIVIDUAL",
  • "givenReference": "M03879.Obj0842",
  • "sourceId": "pm-2024-unit-789",
  • "tenants": [
    ],
  • "streetName": "Hauptstraße",
  • "streetNumber": "123",
  • "postalCode": "10115",
  • "region": "Berlin",
  • "countryCode": "DE",
  • "depositAmountCents": 150000,
  • "notes": "Tenant requested deposit split over two months",
  • "payoutNote": "Deducted EUR 200 for cleaning",
  • "moveOutDate": "2025-08-31",
  • "propertyOwnerId": "vWRaPWn3iIDr8iBpdAHpW",
  • "status": "COMPLETE",
  • "rentalContractVersion": "2",
  • "rentalContractUpdatedAt": "2025-10-20T11:30:00+02:00"
}

Delete a virtual deposit account

Deletes a single virtual deposit account by its unique identifier. The deletion is rejected with a 409 response when the virtual deposit account holds any booked transactions. Deletion requires the current version of the virtual deposit account for optimistic concurrency; supply the version returned by the get virtual deposit account endpoint so that stale writes are detected.

Authorizations:
bearerAuth
path Parameters
depositAccountId
required
string
Example: iDVh8yNUQ8y2hh1jkXTbi

The unique identifier of the deposit account

virtualDepositAccountId
required
string
Example: C9NS3gndTEXrX6CoHIyGy

The unique identifier of the virtual deposit account

Request Body schema: application/json
required
version
required
string^[0-9]+$

Opaque optimistic-concurrency token of the virtual deposit account, as returned by the get virtual deposit account endpoint. Round-trip this value unchanged to detect stale writes; the deletion is rejected with a version conflict when it does not match the current version.

Responses

Request samples

Content type
application/json
{
  • "version": "3"
}

Response samples

Content type
application/json
Example
{
  • "code": "VALIDATION_ERROR",
  • "message": "The request contains invalid data",
  • "details": {
    }
}

Request a partial payout from a virtual deposit account

Authorizations:
bearerAuth
path Parameters
depositAccountId
required
string
Example: uYfXVMXfUrTkv2vT4xZel

The unique identifier of the deposit account

virtualDepositAccountId
required
string
Example: vKo8sCA4VWbTNk8msiqPA

The unique identifier of the virtual deposit account

Request Body schema: application/json
required
counterpartyName
required
string <= 70 characters

Name of the payout recipient.

counterpartyIban
required
string^[A-Z]{2}[0-9]{2}[A-Z0-9]+$

IBAN of the payout recipient (SEPA).

remittanceInformation
required
string <= 140 characters

Remittance information for the transfer.

amountCents
required
integer >= 1

Payout amount in cents. Must be positive and must not exceed the account's available balance.

idempotencyKey
required
string <= 255 characters

A client-chosen opaque string (up to 255 characters) that makes certain the underlying bank transfer is only ever sent once for this payout.

Responses

Request samples

Content type
application/json
{
  • "counterpartyName": "Max Mustermann",
  • "counterpartyIban": "DE89370400440532013000",
  • "remittanceInformation": "Kautionsrückzahlung Objekt 0842",
  • "amountCents": 50000,
  • "idempotencyKey": "payout-2025-10-23-vda-0842-01"
}

Response samples

Content type
application/json
{
  • "bankCreditTransferId": "3f8b2c1a-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
  • "idempotencyKey": "payout-2025-10-23-vda-0842-01",
  • "status": "CREATED"
}

Get virtual deposit account balance

Retrieves the current balance of a virtual deposit account

Authorizations:
bearerAuth
path Parameters
depositAccountId
required
string
Example: uYfXVMXfUrTkv2vT4xZel

The unique identifier of the deposit account

virtualDepositAccountId
required
string
Example: vKo8sCA4VWbTNk8msiqPA

The unique identifier of the virtual deposit account

Responses

Response Schema: application/json
amountCents
required
integer

Current balance in cents

currency
required
string
Value: "EUR"

Currency of the balance

updatedAt
string or null <date-time>

Timestamp when the balance was last updated (ISO 8601 with timezone). Null if no transactions have occurred.

Response samples

Content type
application/json
{
  • "amountCents": 150000,
  • "currency": "EUR",
  • "updatedAt": "2025-10-23T14:30:00+02:00"
}

Property Owners

Endpoints for managing property owners

List all property owners

Retrieves all property owners with pagination support

Authorizations:
bearerAuth
query Parameters
offset
integer >= 0
Default: 0
Example: offset=15

Number of items to skip before returning results

limit
integer [ 1 .. 100 ]
Default: 15
Example: limit=15

Maximum number of items to return

Responses

Response Schema: application/json
offset
required
integer >= 0

Number of items skipped before these results

limit
required
integer [ 1 .. 100 ]

Maximum number of items returned in this response

totalItems
required
integer >= 0

Total number of items available

required
Array of any (PropertyOwner)

List of property owners for the current page

Response samples

Content type
application/json
{
  • "offset": 0,
  • "limit": 15,
  • "totalItems": 2,
  • "items": [
    ]
}

Create a property owner

Creates a property owner scoped to the authenticated manager

Authorizations:
bearerAuth
Request Body schema: application/json
required

Responses

Response Schema: application/json
id
required
string

Unique identifier for the entity

createdAt
required
string <date-time>

Timestamp when the entity was created (ISO 8601 with timezone)

updatedAt
string <date-time>

Timestamp when the entity was last updated (ISO 8601 with timezone)

version
required
string^[0-9]+$

Opaque optimistic-concurrency token for the entity. Round-trip this value unchanged on mutating requests (PATCH, DELETE) to detect stale writes.

type
required
string

Type of property owner

firstName
required
string

Individual: the owner's first name. Company: the contact person's first name.

lastName
required
string

Individual: the owner's last name. Company: the contact person's last name.

streetName
required
string
streetNumber
required
string
postalCode
required
string
region
required
string
country
required
string
emailAddress
string or null <email>
phoneNumber
string or null
taxIdNumber
string or null

German tax identification number

dateOfBirth
string or null <date>
hasCoowner
required
boolean
coownerFirstName
string or null
coownerLastName
string or null
coownerDateOfBirth
string or null <date>
coownerTaxIdNumber
string or null

Request samples

Content type
application/json
Example
{
  • "type": "INDIVIDUAL",
  • "firstName": "Max",
  • "lastName": "Mustermann",
  • "streetName": "Hauptstraße",
  • "streetNumber": "123",
  • "postalCode": "10115",
  • "region": "Berlin",
  • "country": "DE",
  • "emailAddress": "max.mustermann@example.com",
  • "phoneNumber": "+49301234567",
  • "taxIdNumber": "12345678901",
  • "dateOfBirth": "1980-05-12",
  • "hasCoowner": true,
  • "coownerFirstName": "Erika",
  • "coownerLastName": "Mustermann",
  • "coownerDateOfBirth": "1982-07-01",
  • "coownerTaxIdNumber": "98765432109"
}

Response samples

Content type
application/json
Example
{
  • "id": "vWRaPWn3iIDr8iBpdAHpW",
  • "createdAt": "2025-10-23T10:00:00+02:00",
  • "updatedAt": "2025-10-23T14:30:00+02:00",
  • "version": "3",
  • "type": "INDIVIDUAL",
  • "firstName": "Anna",
  • "lastName": "Müller",
  • "streetName": "Hauptstraße",
  • "streetNumber": "123",
  • "postalCode": "10115",
  • "region": "Berlin",
  • "country": "DE",
  • "emailAddress": "user@example.com",
  • "phoneNumber": "string",
  • "taxIdNumber": "string",
  • "dateOfBirth": "2019-08-24",
  • "hasCoowner": true,
  • "coownerFirstName": "string",
  • "coownerLastName": "string",
  • "coownerDateOfBirth": "2019-08-24",
  • "coownerTaxIdNumber": "string"
}

Get a single property owner

Retrieves a single property owner by its unique identifier

Authorizations:
bearerAuth
path Parameters
propertyOwnerId
required
string
Example: vWRaPWn3iIDr8iBpdAHpW

The unique identifier of the property owner

Responses

Response Schema: application/json
id
required
string

Unique identifier for the entity

createdAt
required
string <date-time>

Timestamp when the entity was created (ISO 8601 with timezone)

updatedAt
string <date-time>

Timestamp when the entity was last updated (ISO 8601 with timezone)

version
required
string^[0-9]+$

Opaque optimistic-concurrency token for the entity. Round-trip this value unchanged on mutating requests (PATCH, DELETE) to detect stale writes.

type
required
string

Type of property owner

firstName
required
string

Individual: the owner's first name. Company: the contact person's first name.

lastName
required
string

Individual: the owner's last name. Company: the contact person's last name.

streetName
required
string
streetNumber
required
string
postalCode
required
string
region
required
string
country
required
string
emailAddress
string or null <email>
phoneNumber
string or null
taxIdNumber
string or null

German tax identification number

dateOfBirth
string or null <date>
hasCoowner
required
boolean
coownerFirstName
string or null
coownerLastName
string or null
coownerDateOfBirth
string or null <date>
coownerTaxIdNumber
string or null

Response samples

Content type
application/json
{
  • "id": "vWRaPWn3iIDr8iBpdAHpW",
  • "createdAt": "2025-09-15T09:00:00+02:00",
  • "updatedAt": "2025-10-20T11:30:00+02:00",
  • "version": "3",
  • "type": "INDIVIDUAL",
  • "firstName": "Anna",
  • "lastName": "Müller",
  • "streetName": "Hauptstraße",
  • "streetNumber": "123",
  • "postalCode": "10115",
  • "region": "Berlin",
  • "country": "DE",
  • "emailAddress": "anna.mueller@example.com",
  • "phoneNumber": "+49301234567",
  • "taxIdNumber": "12345678901",
  • "dateOfBirth": "1980-05-12",
  • "hasCoowner": false,
  • "coownerFirstName": null,
  • "coownerLastName": null,
  • "coownerDateOfBirth": null,
  • "coownerTaxIdNumber": null
}

Update a property owner

Updates a property owner scoped to the authenticated manager. Only the fields present in the request body are changed; omitted fields are left unchanged and an explicit null clears a nullable field. The supplied version must match the property owner's current version.

Authorizations:
bearerAuth
path Parameters
propertyOwnerId
required
string
Example: vWRaPWn3iIDr8iBpdAHpW

The unique identifier of the property owner

Request Body schema: application/json
required

Responses

Response Schema: application/json
id
required
string

Unique identifier for the entity

createdAt
required
string <date-time>

Timestamp when the entity was created (ISO 8601 with timezone)

updatedAt
string <date-time>

Timestamp when the entity was last updated (ISO 8601 with timezone)

version
required
string^[0-9]+$

Opaque optimistic-concurrency token for the entity. Round-trip this value unchanged on mutating requests (PATCH, DELETE) to detect stale writes.

type
required
string

Type of property owner

firstName
required
string

Individual: the owner's first name. Company: the contact person's first name.

lastName
required
string

Individual: the owner's last name. Company: the contact person's last name.

streetName
required
string
streetNumber
required
string
postalCode
required
string
region
required
string
country
required
string
emailAddress
string or null <email>
phoneNumber
string or null
taxIdNumber
string or null

German tax identification number

dateOfBirth
string or null <date>
hasCoowner
required
boolean
coownerFirstName
string or null
coownerLastName
string or null
coownerDateOfBirth
string or null <date>
coownerTaxIdNumber
string or null

Request samples

Content type
application/json
Example
{
  • "version": "3",
  • "type": "INDIVIDUAL",
  • "firstName": "Max",
  • "lastName": "Mustermann",
  • "streetName": "Hauptstraße",
  • "streetNumber": "123",
  • "postalCode": "10115",
  • "region": "Berlin",
  • "country": "DE",
  • "emailAddress": "max.mustermann@example.com",
  • "phoneNumber": "+49301234567",
  • "taxIdNumber": "12345678901",
  • "dateOfBirth": "1980-05-12",
  • "hasCoowner": true,
  • "coownerFirstName": "Erika",
  • "coownerLastName": "Mustermann",
  • "coownerDateOfBirth": "1982-07-01",
  • "coownerTaxIdNumber": "98765432109"
}

Response samples

Content type
application/json
Example
{
  • "id": "vWRaPWn3iIDr8iBpdAHpW",
  • "createdAt": "2025-10-23T10:00:00+02:00",
  • "updatedAt": "2025-10-23T14:30:00+02:00",
  • "version": "3",
  • "type": "INDIVIDUAL",
  • "firstName": "Anna",
  • "lastName": "Müller",
  • "streetName": "Hauptstraße",
  • "streetNumber": "123",
  • "postalCode": "10115",
  • "region": "Berlin",
  • "country": "DE",
  • "emailAddress": "user@example.com",
  • "phoneNumber": "string",
  • "taxIdNumber": "string",
  • "dateOfBirth": "2019-08-24",
  • "hasCoowner": true,
  • "coownerFirstName": "string",
  • "coownerLastName": "string",
  • "coownerDateOfBirth": "2019-08-24",
  • "coownerTaxIdNumber": "string"
}

Async Jobs

Endpoints for polling the state of asynchronous jobs such as tax certificate and bank statement generation

Initiate tax certificate generation

Initiates the asynchronous generation of a tax certificate for a virtual deposit account and the requested tax year. Returns the created async job, which can be polled via the get async job endpoint and whose artifact can be downloaded once completed.

Authorizations:
bearerAuth
path Parameters
depositAccountId
required
string
Example: uYfXVMXfUrTkv2vT4xZel

The unique identifier of the deposit account

virtualDepositAccountId
required
string
Example: vKo8sCA4VWbTNk8msiqPA

The unique identifier of the virtual deposit account

Request Body schema: application/json
required
year
required
integer

The tax year for which the certificate should be generated. Must be between the year the virtual deposit account was opened and the current year.

Responses

Request samples

Content type
application/json
{
  • "year": 2024
}

Response samples

Content type
application/json
{
  • "id": "j8sCA4VWbTNk8msiqPAvK",
  • "type": "TAX_CERTIFICATE",
  • "referenceType": "VIRTUAL_DEPOSIT_ACCOUNT",
  • "referenceId": "vKo8sCA4VWbTNk8msiqPA",
  • "status": "PENDING",
  • "createdAt": "2025-10-23T14:30:00+02:00",
  • "completedAt": null,
  • "errorCode": null,
  • "version": "1"
}

Initiate bank statement generation

Initiates the asynchronous generation of an all-time bank statement (Kontoauszug) for a virtual deposit account. Returns the created async job, which can be polled via the get async job endpoint and whose artifact can be downloaded once completed.

Authorizations:
bearerAuth
path Parameters
depositAccountId
required
string
Example: uYfXVMXfUrTkv2vT4xZel

The unique identifier of the deposit account

virtualDepositAccountId
required
string
Example: vKo8sCA4VWbTNk8msiqPA

The unique identifier of the virtual deposit account

Responses

Response samples

Content type
application/json
{
  • "id": "j8sCA4VWbTNk8msiqPAvK",
  • "type": "STATEMENT",
  • "referenceType": "VIRTUAL_DEPOSIT_ACCOUNT",
  • "referenceId": "vKo8sCA4VWbTNk8msiqPA",
  • "status": "PENDING",
  • "createdAt": "2025-10-23T14:30:00+02:00",
  • "completedAt": null,
  • "errorCode": null,
  • "version": "1"
}

Get an async job

Retrieves the current state of an asynchronous job (e.g. tax certificate or bank statement generation) initiated for the authenticated manager.

Authorizations:
bearerAuth
path Parameters
depositAccountId
required
string
Example: uYfXVMXfUrTkv2vT4xZel

The unique identifier of the deposit account

virtualDepositAccountId
required
string
Example: vKo8sCA4VWbTNk8msiqPA

The unique identifier of the virtual deposit account

jobId
required
string
Example: j8sCA4VWbTNk8msiqPAvK

The unique identifier of the async job

Responses

Response Schema: application/json
id
required
string
type
required
string
Enum: "TAX_CERTIFICATE" "STATEMENT"
referenceType
required
string
Value: "VIRTUAL_DEPOSIT_ACCOUNT"
referenceId
required
string
status
required
string
Enum: "PENDING" "PROCESSING" "COMPLETED" "FAILED"
createdAt
required
string <date-time>
completedAt
required
string or null <date-time>
errorCode
required
string or null
version
required
string^[0-9]+$

Response samples

Content type
application/json
{
  • "id": "j8sCA4VWbTNk8msiqPAvK",
  • "type": "TAX_CERTIFICATE",
  • "referenceType": "VIRTUAL_DEPOSIT_ACCOUNT",
  • "referenceId": "vKo8sCA4VWbTNk8msiqPA",
  • "status": "COMPLETED",
  • "createdAt": "2025-10-23T14:30:00+02:00",
  • "completedAt": "2025-10-23T14:31:00+02:00",
  • "errorCode": null,
  • "version": "3"
}

Download an async job artifact

Mints a fresh short-lived presigned HTTP-GET URL (TTL 7 days) for the completed job's artifact in partner-facing object storage; returns a new URL on every call.

Authorizations:
bearerAuth
path Parameters
depositAccountId
required
string
Example: uYfXVMXfUrTkv2vT4xZel

The unique identifier of the deposit account

virtualDepositAccountId
required
string
Example: vKo8sCA4VWbTNk8msiqPA

The unique identifier of the virtual deposit account

jobId
required
string
Example: j8sCA4VWbTNk8msiqPAvK

The unique identifier of the async job

Responses

Response Schema: application/json
jobId
required
string
fileUrl
required
string <uri>
expiresAt
required
string <date-time>

Response samples

Content type
application/json
{}

Webhooks

Webhook events delivered to your registered endpoint.

Setting Up a Webhook

  1. In the Manager App, navigate to Integrationen (Integrations).
Integrations page
  1. Open the Offene Schnittstelle (Public API) integration card, then select the Webhooks tab and click Neuen Webhook erstellen (Create new webhook) to register your endpoint URL and set a signing secret.
Webhooks tab

Signature Verification

Every webhook request includes an X-Getmomo-Signature header for verifying authenticity. The signature is an HMAC-SHA256 digest of the raw JSON request body, computed with your webhook secret.

Header format: v1,<base64-encoded-signature>

Verification examples:

Node.js / TypeScript

import crypto from 'node:crypto';

function verifySignature(secret: string, body: string, header: string): boolean {
  const signature = crypto.createHmac('sha256', secret).update(body).digest('base64');
  const expected = `v1,${signature}`;
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

Python

import hmac
import hashlib
import base64

def verify_signature(secret: str, body: bytes, header: str) -> bool:
    signature = base64.b64encode(
        hmac.new(secret.encode(), body, hashlib.sha256).digest()
    ).decode()
    expected = f"v1,{signature}"
    return hmac.compare_digest(expected, header)

Go

import (
  "crypto/hmac"
  "crypto/sha256"
  "encoding/base64"
  "fmt"
)

func VerifySignature(secret, body, header string) bool {
  mac := hmac.New(sha256.New, []byte(secret))
  mac.Write([]byte(body))
  expected := fmt.Sprintf("v1,%s", base64.StdEncoding.EncodeToString(mac.Sum(nil)))
  return hmac.Equal([]byte(expected), []byte(header))
}

C#

using System.Security.Cryptography;
using System.Text;

public static bool VerifySignature(string secret, string body, string header)
{
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(body));
    var expected = $"v1,{Convert.ToBase64String(hash)}";
    return CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(expected),
        Encoding.UTF8.GetBytes(header)
    );
}

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.MessageDigest;
import java.util.Base64;

public static boolean verifySignature(String secret, String body, String header) throws Exception {
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes("UTF-8"), "HmacSHA256"));
    String signature = Base64.getEncoder().encodeToString(mac.doFinal(body.getBytes("UTF-8")));
    String expected = "v1," + signature;
    return MessageDigest.isEqual(expected.getBytes("UTF-8"), header.getBytes("UTF-8"));
}

Ruby

require 'openssl'
require 'base64'

def verify_signature(secret, body, header)
  signature = Base64.strict_encode64(
    OpenSSL::HMAC.digest('sha256', secret, body)
  )
  expected = "v1,#{signature}"
  Rack::Utils.secure_compare(expected, header)
end

PHP

function verifySignature(string $secret, string $body, string $header): bool {
    $signature = base64_encode(hash_hmac('sha256', $body, $secret, true));
    $expected = "v1,{$signature}";
    return hash_equals($expected, $header);
}

Always use a constant-time comparison function to prevent timing attacks.

Delivery Behavior

  • Events are delivered as POST requests with Content-Type: application/json
  • Your endpoint must respond with a 2xx status code to acknowledge receipt
  • On repeated failure (non-2xx or network error), the webhook is disabled and an email notification is sent to all managers with webhook management permissions
  • Re-enable a disabled webhook from the Manager App after resolving the issue

Event Envelope

All events share a common envelope:

{
  "type": "<EVENT_TYPE>",
  "payload": { ... }
}

The type field identifies the event. The payload shape depends on the event type.

Test Event Webhook

Sent when a test event is triggered from the Manager App. Use this to verify your webhook endpoint is correctly configured and can validate signatures.

Authorizations:
bearerAuth
header Parameters
X-Getmomo-Signature
required
string
Example: v1,K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols=

HMAC-SHA256 signature of the request body. Format: v1,<base64-encoded-signature>

Request Body schema: application/json
required
type
required
string
Value: "TEST"

Event type identifier

required
object (WebhookTestPayload)

Responses

Request samples

Content type
application/json
{
  • "type": "TEST",
  • "payload": {
    }
}

Virtual Deposit Account Balance Updated Webhook

Sent whenever the balance of a virtual deposit account changes. Use this to keep your system in sync with deposit balances managed by Momo. Delivery is retried with exponential backoff on failure; after the final unsuccessful retry, the webhook is automatically disabled and the manager is notified by email.

Authorizations:
bearerAuth
header Parameters
X-Getmomo-Signature
required
string
Example: v1,K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols=

HMAC-SHA256 signature of the request body. Format: v1,<base64-encoded-signature>

Request Body schema: application/json
required
type
required
string
Value: "VIRTUAL_DEPOSIT_ACCOUNT_BALANCE_UPDATED"

Event type identifier

required
object (WebhookVirtualDepositAccountBalanceUpdatedPayload)

Responses

Request samples

Content type
application/json
{
  • "type": "VIRTUAL_DEPOSIT_ACCOUNT_BALANCE_UPDATED",
  • "payload": {
    }
}

Async Job Status Changed Webhook

Sent whenever an asynchronous job started via the Public API (tax certificate or statement generation) reaches a terminal status (COMPLETED or FAILED). Use this instead of polling the job status endpoint. Delivery is retried with exponential backoff on failure; after the final unsuccessful retry, the webhook is automatically disabled and the manager is notified by email.

Authorizations:
bearerAuth
header Parameters
X-Getmomo-Signature
required
string
Example: v1,K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols=

HMAC-SHA256 signature of the request body. Format: v1,<base64-encoded-signature>

Request Body schema: application/json
required
type
required
string
Value: "PUBLIC_API_ASYNC_JOB_STATUS_CHANGED"

Event type identifier

required
object (WebhookPublicApiAsyncJobStatusChangedPayload)

Responses

Request samples

Content type
application/json
{
  • "type": "PUBLIC_API_ASYNC_JOB_STATUS_CHANGED",
  • "payload": {
    }
}