Creates a managed user. Be careful, a user is identified uniquely be her email.
Therefore, when you call this method and provide an email already known you will get an error.
Unless the optional isUpdateAllowed parameter is set to true, in which case it will
update the existing user with the new details.

Parameters

Name

In

Type

Default

Description

isUpdateAllowed

query

boolean

false

Optional. This parameter allows to update an existing user than throw an error if she already exists. Only use it when your system cannot garanty the unicity of user accounts and their associated emails.

HTTP/1.1400Bad RequestContent-Type:application/json{"code":"InvalidURL","message":"String 'https://api.finstack.io/api/v1/users/toto' is not a valid URL or service is down","fields":{"url":"https://api.finstack.io/api/v1/users/toto"}}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"UserForbidden","message":"You cannot access user 341d533a-d90f-4fce-9fc0-12072f7bd555 because you do not manage it","fields":{"userId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1404Not FoundContent-Type:application/json{"code":"UserNotFound","message":"User 341d533a-d90f-4fce-9fc0-12072f7bd555 was not found","fields":{"userId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1400Bad RequestContent-Type:application/json{"code":"InvalidURL","message":"String 'https://api.finstack.io/api/v1/users/toto' is not a valid URL or service is down","fields":{"url":"https://api.finstack.io/api/v1/users/toto"}}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"UserForbidden","message":"You cannot access user 341d533a-d90f-4fce-9fc0-12072f7bd555 because you do not manage it","fields":{"userId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1404Not FoundContent-Type:application/json{"code":"UserNotFound","message":"User 341d533a-d90f-4fce-9fc0-12072f7bd555 was not found","fields":{"userId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1400Bad RequestContent-Type:application/json{"code":"InvalidURL","message":"String 'https://api.finstack.io/api/v1/users/toto' is not a valid URL or service is down","fields":{"url":"https://api.finstack.io/api/v1/users/toto"}}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"UserForbidden","message":"You cannot access user 341d533a-d90f-4fce-9fc0-12072f7bd555 because you do not manage it","fields":{"userId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1404Not FoundContent-Type:application/json{"code":"UserNotFound","message":"User 341d533a-d90f-4fce-9fc0-12072f7bd555 was not found","fields":{"userId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

Deletes all information (mandates, bank accounts, events and user account) relative to the user with the specified id. WARNING: This action is only available in a SANDBOX environment. Use this only for automated testing.

HTTP/1.1400Bad RequestContent-Type:application/json{"code":"InvalidURL","message":"String 'https://api.finstack.io/api/v1/users/toto/bank_accccount' is not a valid URL or service is down","fields":{"url":"https://api.finstack.io/api/v1/users/toto/bank_accccount"}}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"UserForbidden","message":"You cannot access user 341d533a-d90f-4fce-9fc0-12072f7bd555 because you do not manage it","fields":{"userId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1404Not FoundContent-Type:application/json{"code":"UserNotFound","message":"User 341d533a-d90f-4fce-9fc0-12072f7bd555 was not found","fields":{"userId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"UserForbidden","message":"You cannot access user 341d533a-d90f-4fce-9fc0-12072f7bd555 because you do not manage it","fields":{"userId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1404Not FoundContent-Type:application/json{"code":"UserNotFound","message":"User 341d533a-d90f-4fce-9fc0-12072f7bd555 was not found","fields":{"userId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"UserForbidden","message":"You cannot access user 341d533a-d90f-4fce-9fc0-12072f7bd555 because you do not manage it","fields":{"userId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1404Not FoundContent-Type:application/json{"code":"UserNotFound","message":"User 341d533a-d90f-4fce-9fc0-12072f7bd555 was not found","fields":{"userId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"UserForbidden","message":"You cannot access user 341d533a-d90f-4fce-9fc0-12072f7bd555 because you do not manage it","fields":{"userId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1404Not FoundContent-Type:application/json{"code":"UserNotFound","message":"User 341d533a-d90f-4fce-9fc0-12072f7bd555 was not found","fields":{"userId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"UserForbidden","message":"You cannot access user 341d533a-d90f-4fce-9fc0-12072f7bd555 because you do not manage it","fields":{"userId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1404Not FoundContent-Type:application/json{"code":"UserNotFound","message":"User 341d533a-d90f-4fce-9fc0-12072f7bd555 was not found","fields":{"userId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1400Bad RequestContent-Type:application/json{"code":"InvalidURL","message":"String 'https://api.finstack.io/api/v1/meeee' is not a valid URL or service is down","fields":{"url":"https://api.finstack.io/api/v1/meeee"}}

HTTP/1.1400Bad RequestContent-Type:application/json{"code":"InvalidURL","message":"String 'https://api.finstack.io/api/v1/bank' is not a valid URL or service is down","fields":{"url":"https://api.finstack.io/api/v1/bank"}}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"UserForbidden","message":"You cannot access user 341d533a-d90f-4fce-9fc0-12072f7bd555 because you do not manage it","fields":{"userId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1404Not FoundContent-Type:application/json{"code":"UserNotFound","message":"User 341d533a-d90f-4fce-9fc0-12072f7bd555 was not found","fields":{"userId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1400Bad RequestContent-Type:application/json{"code":"InvalidURL","message":"String 'https://api.finstack.io/api/v1/bank/toto' is not a valid URL or service is down","fields":{"url":"https://api.finstack.io/api/v1/bank/toto"}}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"BankAccountForbidden","message":"You cannot view bank account 02b331d1-f938-4ac4-ab40-ac287c8e8c61 because you do not manage its owner","fields":{"bankAccountId":"02b331d1-f938-4ac4-ab40-ac287c8e8c61"}}

HTTP/1.1400Bad RequestContent-Type:application/json{"code":"InvalidURL","message":"String 'https://api.finstack.io/api/v1/bank' is not a valid URL or service is down","fields":{"url":"https://api.finstack.io/api/v1/bank"}}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"BankAccountForbidden","message":"You cannot view bank account 02b331d1-f938-4ac4-ab40-ac287c8e8c61 because you do not manage its owner","fields":{"bankAccountId":"02b331d1-f938-4ac4-ab40-ac287c8e8c61"}}

HTTP/1.1400Bad RequestContent-Type:application/json{"code":"InvalidURL","message":"String 'https://api.finstack.io/api/v1/bank' is not a valid URL or service is down","fields":{"url":"https://api.finstack.io/api/v1/bank"}}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"BankAccountForbidden","message":"You cannot view bank account 02b331d1-f938-4ac4-ab40-ac287c8e8c61 because you do not manage its owner","fields":{"bankAccountId":"02b331d1-f938-4ac4-ab40-ac287c8e8c61"}}

HTTP/1.1400Bad RequestContent-Type:application/json{"code":"InvalidURL","message":"String 'https://api.finstack.io/api/v1/bank/me' is not a valid URL or service is down","fields":{"url":"https://api.finstack.io/api/v1/bank/me"}}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"InvalidKeyForOperation","message":"You are not allowed to execute a Write operation with a Read API key","fields":{"apiKeyId":"02b331d1-f938-4ac4-ab40-ac287c8e8c61""apiKeyRole":"Read""operationType":"Write"}}

HTTP/1.1400Bad RequestContent-Type:application/json{"code":"InvalidURL","message":"String 'https://api.finstack.io/api/v1/mandates/toto' is not a valid URL or service is down","fields":{"url":"https://api.finstack.io/api/v1/mandates/toto"}}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"MandateForbidden","message":"You cannot access mandate 341d533a-d90f-4fce-9fc0-12072f7bd555 because you do not manage one of its parties","fields":{"mandateId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1404Not FoundContent-Type:application/json{"code":"MandateNotFound","message":"Mandate 341d533a-d90f-4fce-9fc0-12072f7bd555 was not found","fields":{"mandateId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1400Bad RequestContent-Type:application/json{"code":"InvalidURL","message":"String 'https://api.finstack.io/api/v1/mandates/toto' is not a valid URL or service is down","fields":{"url":"https://api.finstack.io/api/v1/mandates/toto"}}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"MandateForbidden","message":"You cannot access mandate 341d533a-d90f-4fce-9fc0-12072f7bd555 because you do not manage one of its parties","fields":{"mandateId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1404Not FoundContent-Type:application/json{"code":"MandateNotFound","message":"Mandate 341d533a-d90f-4fce-9fc0-12072f7bd555 was not found","fields":{"mandateId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

Cancels the mandate if it isn't signed yet or revokes it if it is signed.

HTTP/1.1400Bad RequestContent-Type:application/json{"code":"InvalidURL","message":"String 'https://api.finstack.io/api/v1/mandates/toto/sign' is not a valid URL or service is down","fields":{"url":"https://api.finstack.io/api/v1/mandates/toto/sign"}}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"MandateForbidden","message":"You cannot access mandate 341d533a-d90f-4fce-9fc0-12072f7bd555 because you do not manage one of its parties","fields":{"mandateId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1404Not FoundContent-Type:application/json{"code":"MandateNotFound","message":"Mandate 341d533a-d90f-4fce-9fc0-12072f7bd555 was not found","fields":{"mandateId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

Returns the link to be sent to the payer for her to sign the mandate. Can only be called when the mandate is not signed yet. Use this call only if you lost the signature link sent in the mandate creation request’s response.

Get Signed Mandate Document

GET/api/v1/mandates/{id}/documentHTTP/1.1X-Auth-Token:myapikeyvalue

HTTP response example:

HTTP/1.1200OK

HTTP/1.1400Bad RequestContent-Type:application/json{"code":"InvalidURL","message":"String 'https://api.finstack.io/api/v1/mandates/toto/doc' is not a valid URL or service is down","fields":{"url":"https://api.finstack.io/api/v1/mandates/toto/doc"}}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"MandateForbidden","message":"You cannot access mandate 341d533a-d90f-4fce-9fc0-12072f7bd555 because you do not manage one of its parties","fields":{"mandateId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1404Not FoundContent-Type:application/json{"code":"MandateNotFound","message":"Mandate 341d533a-d90f-4fce-9fc0-12072f7bd555 was not found","fields":{"mandateId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

Returns signed mandate document (if any) with the specified id in PDF.

HTTP/1.1400Bad RequestContent-Type:application/json{"code":"InvalidURL","message":"String 'https://api.finstack.io/api/v1/mandates/toto/events' is not a valid URL or service is down","fields":{"url":"https://api.finstack.io/api/v1/mandates/toto/events"}}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"MandateForbidden","message":"You cannot access mandate 341d533a-d90f-4fce-9fc0-12072f7bd555 because you do not manage one of its parties","fields":{"mandateId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1404Not FoundContent-Type:application/json{"code":"MandateNotFound","message":"Mandate 341d533a-d90f-4fce-9fc0-12072f7bd555 was not found","fields":{"mandateId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"InvalidKeyForOperation","message":"You are not allowed to execute a Write operation with a Read API key","fields":{"apiKeyId":"02b331d1-f938-4ac4-ab40-ac287c8e8c61""apiKeyRole":"Read""operationType":"Write"}}

HTTP/1.1404Not FoundContent-Type:application/json{"code":"MandateNotFound","message":"Mandate 02b331d1-f938-4ac4-ab40-ac287c8e8c61 was not found","fields":{"mandateId":"02b331d1-f938-4ac4-ab40-ac287c8e8c61"}}

HTTP/1.1400Bad RequestContent-Type:application/json{"code":"InvalidURL","message":"String 'https://api.finstack.io/api/v1/payments/toto' is not a valid URL or service is down","fields":{"url":"https://api.finstack.io/api/v1/payments/toto"}}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"PaymentForbidden","message":"You cannot view payment 341d533a-d90f-4fce-9fc0-12072f7bd555 because you do not manage one of its parties","fields":{"paymentId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1400Bad RequestContent-Type:application/json{"code":"InvalidURL","message":"String 'https://api.finstack.io/api/v1/payments/toto/events' is not a valid URL or service is down","fields":{"url":"https://api.finstack.io/api/v1/payments/toto/events"}}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"PaymentForbidden","message":"You cannot view payment 341d533a-d90f-4fce-9fc0-12072f7bd555 because you do not manage one of its parties","fields":{"paymentId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1400Bad RequestContent-Type:application/json{"code":"InvalidURL","message":"String 'https://api.finstack.io/api/v1/payments/toto/cancel' is not a valid URL or service is down","fields":{"url":"https://api.finstack.io/api/v1/payments/toto/cancel"}}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"PaymentForbidden","message":"You cannot view payment 341d533a-d90f-4fce-9fc0-12072f7bd555 because you do not manage one of its parties","fields":{"paymentId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1400Bad RequestContent-Type:application/json{"code":"InvalidURL","message":"String 'https://api.finstack.io/api/v1/event/summary' is not a valid URL or service is down","fields":{"url":"https://api.finstack.io/api/v1/event/summary"}}

Returns a CSV summary of events that occurred during the provided time range.
The CSV has 3 columns: resource type, event type and number of events.
The first line is the header of the file and contains column names.

Parameters

Name

In

Type

Description

since *

query

string

Return all events after given timestamp in UTC, for example ‘2015-01-01T12:00:00.000Z’.

until

query

string

Optional. Return all events before given timestamp in UTC, for example ‘2015-01-01T12:00:00.000Z’.

Occurs when the bank account is submitted and analyzed by a Payment Service Provider (PSP).

PSP

SDDMandate

PayerRegistered

Occurs after payer registration in Finstack when the mandate is requested manually from the back office and the payer is not yet a Finstack user.

Finstack website

SDDMandate

SDDMandateCanceled

Occurs when the creditor cancels a mandate request either from the API or the back office.

Finstack back office or API

SDDMandate

SDDMandateRequested

Occurs when a mandate is created (also called requested because a signature request is issued to the payer.

Finstack back office or API

SDDMandate

SDDMandateRevoked

Occurs when any of the parties (payer, creditor or third party creditor) revokes the mandate.

Finstack back office or API

SDDMandate

SDDMandateSignedElectronically

Occurs when the mandate is electronically signed by the payer.

Finstack website

SDDMandate

SDDMandateSignedManually

Occurs when the mandate is manually signed by the payer.

Finstack back office

SDDMandate

SDDMandateUsedByPSP

Occurs when the mandate is used for the first time for a payment.

PSP

SDDMandate

SignedDocumentStored

Occurs immediately after signature when the signed PDF document is archived.

Finstack system

SDDPayment

DirectDebitSubmittedToPSP

Occurs when the payment is submitted to be executed.

Finstack system

SDDPayment

SDDPaymentCanceled

Occurs when the payment is canceled by the final creditor either from the back office or the API.

Finstack back office or API

SDDPayment

SDDPaymentExecuted

Occurs when the payment is executed.

PSP

SDDPayment

SDDPaymentFullySettled

Occurs 8 weeks after the payment is partially settled if there was a rolling reserve, this event indicates that rolling reserve associated with this payment was released.

Finstack system

SDDPayment

SDDPaymentInitiated

Occurs when a payment is created.

Finstack website, back office or API

SDDPayment

SDDPaymentPartiallySettled

After successful execution, occurs when the amount collected is sent to creditor’s bank account before rolling reserve.

Finstack system

SDDPayment

SDDPaymentPlanned

Occurs when the mandate associated with the payment is signed.

Finstack website or API

SDDPayment

SDDPaymentRejected

Occurs when the payment is charged back.

Payer’s bank account

User

UserCreated

Occurs when a user is created through the API or when she registers directly at Finstack’s website.

Finstack website or API

User

UserModified

Occurs when a user is modified.

Finstack website or API

Webhooks

Get Webhooks

GET/api/v1/webhooksHTTP/1.1X-Auth-Token:myapikeyvalue

HTTP response example:

HTTP/1.1200OKContent-Type:application/json[{"id":"341d533a-d90f-4fce-9fc0-12072f7bd555","createdAt":"2015-01-01T12:00:00.000Z","updatedAt":"2015-01-01T12:00:00.000Z","links":[{"rel":"Update Webhook","href":"https://app.finstack.io/api/v1/webhooks/341d533a-d90f-4fce-9fc0-12072f7bd555","verb":"PUT"},{"rel":"Delete Webhook","href":"https://app.finstack.io/api/v1/webhooks/341d533a-d90f-4fce-9fc0-12072f7bd555","verb":"DELETE"}],"callbackURL":"https://www.yourwebsite.com/webhooklistener","resourcesAndEvents":{"BankAccount":["BankAccountCreated","BankAccountUpdatedByPSP"],"User":[],"Wallet":["PendingFeeAdded"]},"description":"Listen to specific events on bank accounts and wallets and all events on users."}]

HTTP/1.1400Bad RequestContent-Type:application/json{"code":"InvalidURL","message":"String 'https://api.finstack.io/api/v1/webhook' is not a valid URL or service is down","fields":{"url":"https://api.finstack.io/api/v1/webhook"}}

Returns all webhooks.

Responses

Create Webhook

POST/api/v1/webhooksHTTP/1.1Content-Type:application/jsonX-Auth-Token:myapikeyvalue{"callbackURL":"https://www.yourwebsite.com/webhooklistener","resourcesAndEvents":{"BankAccount":["BankAccountCreated","BankAccountUpdatedByPSP"],"User":[],"Wallet":["PendingFeeAdded"]},"description":"Listen to specific events on bank accounts and wallets and all events on users."}

HTTP response example:

HTTP/1.1201CreatedContent-Type:application/json{"id":"341d533a-d90f-4fce-9fc0-12072f7bd555","createdAt":"2015-01-01T12:00:00.000Z","updatedAt":"2015-01-01T12:00:00.000Z","links":[{"rel":"Update Webhook","href":"https://app.finstack.io/api/v1/webhooks/341d533a-d90f-4fce-9fc0-12072f7bd555","verb":"PUT"},{"rel":"Delete Webhook","href":"https://app.finstack.io/api/v1/webhooks/341d533a-d90f-4fce-9fc0-12072f7bd555","verb":"DELETE"}],"callbackURL":"https://www.yourwebsite.com/webhooklistener","resourcesAndEvents":{"BankAccount":["BankAccountCreated","BankAccountUpdatedByPSP"],"User":[],"Wallet":["PendingFeeAdded"]},"description":"Listen to specific events on bank accounts and wallets and all events on users."}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"InvalidKeyForOperation","message":"You are not allowed to execute a Write operation with a Read API key","fields":{"apiKeyId":"02b331d1-f938-4ac4-ab40-ac287c8e8c61""apiKeyRole":"Read""operationType":"Write"}}

Creates a new web hook. All you need to provide is an HTTPS URL that will be used to send you events.
All other parameters are optional, by default all events are sent. Resources and events parameters act like filters.

HTTP/1.1400Bad RequestContent-Type:application/json{"code":"InvalidURL","message":"String 'https://api.finstack.io/api/v1/webhooks/failure' is not a valid URL or service is down","fields":{"url":"https://api.finstack.io/api/v1/webhooks/failure"}}

Returns the list of failures (if any) on all webhooks in the previous month.
Failures are grouped by webhook ID and ordered chronologically.

Responses

Get Webhook

GET/api/v1/webhooks/{id}HTTP/1.1X-Auth-Token:myapikeyvalue

HTTP response example:

HTTP/1.1200OKContent-Type:application/json{"id":"341d533a-d90f-4fce-9fc0-12072f7bd555","createdAt":"2015-01-01T12:00:00.000Z","updatedAt":"2015-01-01T12:00:00.000Z","links":[{"rel":"Update Webhook","href":"https://app.finstack.io/api/v1/webhooks/341d533a-d90f-4fce-9fc0-12072f7bd555","verb":"PUT"},{"rel":"Delete Webhook","href":"https://app.finstack.io/api/v1/webhooks/341d533a-d90f-4fce-9fc0-12072f7bd555","verb":"DELETE"}],"callbackURL":"https://www.yourwebsite.com/webhooklistener","resourcesAndEvents":{"BankAccount":["BankAccountCreated","BankAccountUpdatedByPSP"],"User":[],"Wallet":["PendingFeeAdded"]},"description":"Listen to specific events on bank accounts and wallets and all events on users."}

HTTP/1.1400Bad RequestContent-Type:application/json{"code":"InvalidURL","message":"String 'https://api.finstack.io/api/v1/webhooks/toto' is not a valid URL or service is down","fields":{"url":"https://api.finstack.io/api/v1/webhooks/toto"}}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"WebhookForbidden","message":"You cannot access webhook 341d533a-d90f-4fce-9fc0-12072f7bd555 because you do not manage its owner","fields":{"webhookId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1404Not FoundContent-Type:application/json{"code":"WebhookNotFound","message":"Webhook 341d533a-d90f-4fce-9fc0-12072f7bd555 was not found","fields":{"webhookId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

Update Webhook

PUT/api/v1/webhooks/{id}HTTP/1.1Content-Type:application/json{"callbackURL":"https://www.yourwebsite.com/webhooklistener","resourcesAndEvents":{"BankAccount":[],"User":[]},"description":"Listen to all events on users and bank accounts."}

HTTP/1.1200OKContent-Type:application/json{"id":"341d533a-d90f-4fce-9fc0-12072f7bd555","createdAt":"2015-01-01T12:00:00.000Z","updatedAt":"2015-01-01T18:00:00.000Z","links":[{"rel":"Update Webhook","href":"https://app.finstack.io/api/v1/webhooks/341d533a-d90f-4fce-9fc0-12072f7bd555","verb":"PUT"},{"rel":"Delete Webhook","href":"https://app.finstack.io/api/v1/webhooks/341d533a-d90f-4fce-9fc0-12072f7bd555","verb":"DELETE"}],"callbackURL":"https://www.yourwebsite.com/webhooklistener","resourcesAndEvents":{"BankAccount":[],"User":[]},"description":"Listen to all events on users and bank accounts."}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"WebhookForbidden","message":"You cannot access webhook 341d533a-d90f-4fce-9fc0-12072f7bd555 because you do not manage its owner","fields":{"webhookId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1404Not FoundContent-Type:application/json{"code":"WebhookNotFound","message":"Webhook 341d533a-d90f-4fce-9fc0-12072f7bd555 was not found","fields":{"webhookId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

Delete Webhook

DELETE/api/v1/webhooks/{id}HTTP/1.1X-Auth-Token:myapikeyvalue

HTTP response example:

HTTP/1.1200OKContent-Type:application/json{"id":"341d533a-d90f-4fce-9fc0-12072f7bd555","createdAt":"2015-01-01T12:00:00.000Z","updatedAt":"2015-01-01T12:00:00.000Z","links":[{"rel":"Update Webhook","href":"https://app.finstack.io/api/v1/webhooks/341d533a-d90f-4fce-9fc0-12072f7bd555","verb":"PUT"},{"rel":"Delete Webhook","href":"https://app.finstack.io/api/v1/webhooks/341d533a-d90f-4fce-9fc0-12072f7bd555","verb":"DELETE"}],"callbackURL":"https://www.yourwebsite.com/webhooklistener","resourcesAndEvents":{"BankAccount":["BankAccountCreated","BankAccountUpdatedByPSP"],"User":[],"Wallet":["PendingFeeAdded"]},"description":"Listen to specific events on bank accounts and wallets and all events on users."}

HTTP/1.1400Bad RequestContent-Type:application/json{"code":"InvalidURL","message":"String 'https://api.finstack.io/api/v1/webhooks/toto' is not a valid URL or service is down","fields":{"url":"https://api.finstack.io/api/v1/webhooks/toto"}}

HTTP/1.1403ForbiddenContent-Type:application/json{"code":"WebhookForbidden","message":"You cannot access webhook 341d533a-d90f-4fce-9fc0-12072f7bd555 because you do not manage its owner","fields":{"webhookId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

HTTP/1.1404Not FoundContent-Type:application/json{"code":"WebhookNotFound","message":"Webhook 341d533a-d90f-4fce-9fc0-12072f7bd555 was not found","fields":{"webhookId":"341d533a-d90f-4fce-9fc0-12072f7bd555"}}

Fields

Name

Type

Format

Description

id *

string

uuid

Should be a valid UUID string. You are required to generate the id of the bank account in order to make the call idempotent. That allows you to safely retry to create the bank account without fearing to create multiple accounts on our side in case there was a network problem.

userId *

string

uuid

The user’s id to whom the bank account belongs.

holder

string

Holder of the bank account. By default, it is equal to the full name of the user or it’s legal entity name.

Fields

Name

Type

Format

Description

id *

string

uuid

Should be a valid UUID string. You are required to generate the id of the mandate in order to make the call idempotent. That allows you to safely retry to create the mandate without fearing to create multiple mandates on our side in case there was a network problem.

payerBankAccountId *

string

The payer’s bank account id.

finalCreditorId

string

Use this field only if the final creditor of the mandate is not the API user.

sendSignatureRequestByEmail

boolean

Set this flag to ‘true’ if you want to send a mandate signature request by email through Finstack.

signElectronically

boolean

Set this flag to ‘true’ if you want the mandate to be signed electronically by the payer.

Fields

Name

Type

Format

Description

id *

string

uuid

Should be a valid UUID string. You are required to generate the id of the payment in order to make the call idempotent. That allows you to safely retry to create the payment without fearing to create multiple debits on our side in case there was a network problem.

mandateId *

string

uuid

ID of the associated mandate. The mandate will be used to know who is the creditor and who is the payer in this transaction.

amount *

number

Amount to be withdrawn from the payer’s bank account, for example ‘100.00’. Minimum is 1€ and maximum is 20000€, any amounts outside this range will be rejected.

label *

string

Short message that will appear on the payer’s bank account statement.

valueDate

string

date

Date when the payment is charged, for example ‘2015-01-01’. If not specified or date is in the past, the payment will be executed as soon as possible.

NewWebhook

{"callbackURL":"https://www.yourwebsite.com/webhooklistener","resourcesAndEvents":{"BankAccount":["BankAccountCreated","BankAccountUpdatedByPSP"],"User":[],"Wallet":["PendingFeeAdded"]},"description":"Listen to specific events on bank accounts and wallets and all events on users."}

Information required to create a new webhook.

Fields

Name

Type

Format

Description

callbackURL *

string

uri

Finstack will do a POST call to this URL to send events. The URL has to be HTTPS in production!

resourcesAndEvents

object

A map where keys are resource types - BankAccount, Document, Plan, SDDMandate, SDDPayment, Subscription, User and Wallet. Values are arrays of the names of the events that can occur to the resource. If the array is empty, the webhook will listen to all events related to the corresponding resource type. This parameter is optional, if it isn’t provided the webhook will listen to all events.

Fields

Webhook

{"id":"341d533a-d90f-4fce-9fc0-12072f7bd555","createdAt":"2015-01-01T12:00:00.000Z","updatedAt":"2015-01-01T12:00:00.000Z","links":[{"rel":"Update Webhook","href":"https://app.finstack.io/api/v1/webhooks/341d533a-d90f-4fce-9fc0-12072f7bd555","verb":"PUT"},{"rel":"Delete Webhook","href":"https://app.finstack.io/api/v1/webhooks/341d533a-d90f-4fce-9fc0-12072f7bd555","verb":"DELETE"}],"callbackURL":"https://www.yourwebsite.com/webhooklistener","resourcesAndEvents":{"BankAccount":["BankAccountCreated","BankAccountUpdatedByPSP"],"User":[],"Wallet":["PendingFeeAdded"]},"description":"Listen to specific events on bank accounts and wallets and all events on users."}

A webhook is a subscription to listen to potentially all events in Finstack.

Finstack will do a POST call to this URL to send events. The URL has to be HTTPS!

resourcesAndEvents

object

A map where keys are resource types - BankAccount, Document, Plan, SDDMandate, SDDPayment, Subscription, User and Wallet. Values are arrays of the names of the events that can occur to the resource. If the array is empty, the webhook will listen to all events related to the corresponding resource type. If the map is empty, the webhook will listen to all events.

Fields

Timestamp at which the failure occurred in UTC, for example ‘2015-01-01T12:00:00.000Z’.

error *

string

Error message of the failure

Errors

Error

{"code":"BankAccountForbidden","message":"You cannot view bank account 02b331d1-f938-4ac4-ab40-ac287c8e8c61 because you do not manage its owner","fields":{"bankAccountId":"02b331d1-f938-4ac4-ab40-ac287c8e8c61"}}