Webhooks

Webhooks allow you to gain insight into the trustshare system. When certain events happen within our system we will send you a POST to a provided URL containing a JSON body. Webhooks can be used to keep the state of your own system inline with trustshare's, or be notified of asynchronous processes.

Setting up Webhooks

You can set up your Webhook via the Configuration page on the trustshare dashboard.

The supplied Webhook URL should return a 200 status code for every POST, so we know the message was received and we do not need to retry delivery.

When creating a Webhook, a test request will be sent with the following body:

{ "type": "handshake" }

We also require that you provide a shared secret. This secret will be supplied to your Webhook URL in the x-trustshare-secret header. Validating this shared secret allows you to confirm the authenticity of the request to your Webhook URL.

Events

We currently provide events around transactions, payments and disputes. A transaction is essentially a container for payments, whether inbound (received) or outbound (released and returned). A dispute denotes a transaction that is currently contentious.

The token field in each of the following events relates to the token returned by our SDKs.

In all instances of events, the from property relates to the buyer in the transaction and the to property relates to the seller.

Transaction initiated

A dedicated IBAN has been opened between the two parties for the transaction.

This event specifically denotes that a transaction has been initiated, and a dedicated account has been provisioned. Both parties will be notified by automated email at this point, however it doesn't necessarily mean a payment has been received.

{
"type": "transaction_initiated",
"from": "buyer@example.com",
"to": "seller@example.com",
"verification": {
"from": "unverified",
"to": "unverified"
},
"token": "5CIXLExTtrIE8387",
"currency": "gbp",
"estimated_value": 150000
}

Transaction complete

The transaction between the two parties is completed and the dedicated account has been closed.

This event is fired after a dedicated transaction account is zeroed after receiving payments. This is considered a terminal state and the associated account will no longer be able to receive funds.

note

The verification.to state would always be "verified" in this event as a recipient of funds must be verified before any payment to them will be actioned.

{
"type": "transaction_complete",
"from": "buyer@example.com",
"to": "seller@example.com",
"verification": {
"from": "unverified",
"to": "verified"
},
"token": "5CIXLExTtrIE8387",
"currency": "gbp",
"total_value": 150000
}

Transaction abandoned

The transaction between the two parties has been automatically abandoned.

This event is fired after a transaction is considered abandoned. This happens as the result of the system not receiving any inbound payments to the transaction account for 28 days after initiation. This is considered a terminal state and the associated account will no longer be able to receive funds.

note

This will never happen if there are funds in the transaction account.

{
"type": "transaction_abandoned",
"from": "buyer@example.com",
"to": "seller@example.com",
"verification": {
"from": "unverified",
"to": "verified"
},
"token": "5CIXLExTtrIE8387",
"currency": "gbp"
}

Payment received

A payment has been received from the buyer into the associated escrow account.

This event is fired when funds are received into the dedicated account and the associated funds are considered as "in escrow". Both parties will be notified by automated email at this point.

{
"type": "payment_received",
"from": "buyer@example.com",
"to": "seller@example.com",
"verification": {
"from": "in_review",
"to": "verified"
},
"token": "5CIXLExTtrIE8387",
"paymentToken": "f79L9CBt3NuyEEap",
"currency": "gbp",
"amount": 150000
}

Payment released

The buyer successfully released a payment to the seller from the escrow account.

This event is fired when a payment to a seller successfully leaves the dedicated account. Both parties will be notified by automated email at this point.

note

The verification.to state would always be "verified" in this event as a recipient of funds must be verified before any payment to them will be actioned.

{
"type": "payment_released",
"from": "buyer@example.com",
"to": "seller@example.com",
"verification": {
"from": "unverified",
"to": "verified"
},
"token": "5CIXLExTtrIE8387",
"paymentToken": "f79L9CBt3NuyEEap",
"currency": "gbp",
"amount": 150000
}

Payment returned

The seller successfully returned a payment to the buyer from the escrow account.

This event is fired when a payment to a buyer successfully leaves the dedicated account. Both parties will be notified by automated email at this point.

note

The verification.from state would always be "verified" in this event as a recipient of funds must be verified before any payment to them will be actioned.

{
"type": "payment_returned",
"from": "buyer@example.com",
"to": "seller@example.com",
"verification": {
"from": "verified",
"to": "unverified"
},
"token": "5CIXLExTtrIE8387",
"paymentToken": "f79L9CBt3NuyEEap",
"currency": "gbp",
"amount": 150000
}

Payment paused

In some instances the system may pause a release or return payment pending some further criteria.

This event is fired when a payment is paused automatically by the system due to specific criteria not being met. Please use the table below to reference any reason provided by this webhook.

ReasonDescription
inbound_payments_pendingAn inbound payment is still pending, once the payment is received this payment will automatically unpause.
from_document_requiredA document is required on the buyer profile.
from_verification_requiredThe buyer requires verification.
to_document_requiredA document is required on the seller profile.
to_verification_requiredThe seller requires verification.
unknown_contact_supportThe payment was paused for an unknown reason. Please contact support@trustshare.co
note

You can direct your users to help unpause these payments. In the case of *_document_required reasons direct the relevant user to https://{subdomain}.trustshare.co/profile to upload the required documentation. Where a *_verification_required reason is exposed, direct the relevant user to https://{subdomain}.trustshare.co/verify.

{
"type": "payment_paused",
"paymentType": "release",
"from": "buyer@example.com",
"to": "seller@example.com",
"verification": {
"from": "verified",
"to": "unverified"
},
"token": "5CIXLExTtrIE8387",
"paymentToken": "f79L9CBt3NuyEEap",
"currency": "gbp",
"amount": 150000,
"reason": "inbound_payments_pending"
}

Dispute raised

A participant in the transaction has raised a dispute against the other party.

This event is fired when a dispute is raised for our Compliance team to review. Both parties will be notified by automated email at this point.

{
"type": "dispute_raised",
"from": "buyer@example.com",
"to": "seller@example.com",
"token": "5CIXLExTtrIE8387"
}

Dispute resolved

trustshare has reviewed the dispute and resolved it.

Both parties will be notified by automated email at this point.

{
"type": "dispute_resolved",
"from": "buyer@example.com",
"to": "seller@example.com",
"token": "5CIXLExTtrIE8387"
}