Skip to main content
When a user registers their bank account on the enrollment page, TapiPay notifies you with this webhook. It carries the account’s externalPaymentMethodId, the same one GET /payment-methods returns and POST /v2/debts/orders accepts, so you do not need to query the API to start charging the user.
This webhook has the same contract as the order payment: it does not carry operationId or companyName, and its idempotency key is id. What Common fields explains does not apply here, except for hash.

​
When it arrives

It arrives every time the account registration succeeds:
  • New account: the first time the user registers that account.
  • Repeated registration: the user registers again an account that was already active.
  • Reactivation: the user registers again an account that had been deleted.
In the last two cases the notice carries the same id and the same registeredAt as the new account one. It is the same account, so treat it as a resend. For now the contract covers bank accounts (BANK_ACCOUNT). If you receive a notice with another payment method type, ignore it: the other types are not part of this contract yet. It does not arrive if the registration fails, nor for accounts TapiPay loads outside the registration, for example in a migration.

​
Configuration

It reaches the same URL as the payment order events: the one you set for orders during onboarding or, if you do not have one, your general URL. The security mechanisms are the same as for the rest of the webhooks: see Validating the request comes from TapiPay. POST with Content-Type: application/json. The notificationType header carries the same value as type, so you can route without reading the body.

​
The payload

​
paymentMethod

It is the same paymentMethod object that arrives in the order payment, with two more fields: isDefault and details.

​
The hash

If you provided an RSA public key during onboarding, hash is encrypted with it. Decrypt it with your private key: it contains your integration username or, in version v2 of the security, { "clientUsername", "operationId" }. In v2, check that operationId matches the id in the body.

​
Example

It belongs to an integration without a public key, which is why hash is null.

​
Recommendations

  • Process each id only once. Besides the retries when you do not respond, a repeated registration and a reactivation resend the same id. Store processed id values in persistent storage.
  • Store the externalPaymentMethodId with your user: it is what you need to charge that account.
  • Do not use isDefault as the source of truth. The default account can change later, for example if the user deletes an account. Before deciding which account to charge, query GET /payment-methods.
  • Ignore fields you do not know: new fields can be added, also inside details.
The requirements for your endpoint (respond 2xx in under 5 seconds and be reachable from TapiPay’s IPs) are the same as for the rest of the webhooks: see Requirements for your endpoint.