Skip to main content

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 Webhooks 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.

The description field in all instances of events relates to the transaction description supplied at checkout either by the user through the form, or by the facilitator through the SDKs.

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

In all instances of events, the balance property shows the true balance of the dedicated escrow account. These are the funds that have been already received by us and we are currently holding in escrow. Not to be confused with estimated_value, which indicates the estimated full value of a transactions; or total_value which indicates the full amount of funds that have been involved in the lifetime of the transaction once completed.

Similarly the amount property on payment events relates to the funds concerned in the single payment. Only balance is a true representation of funds currently held in the dedicated escrow account.

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",  "description": "my transaction description",  "estimated_value": 150000,  "balance": 0}

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",  "description": "my transaction description",  "total_value": 150000,  "balance": 0}

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",  "description": "my transaction description",  "balance": 0}

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",  "description": "my transaction description",  "amount": 150000,  "balance": 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",  "description": "my transaction description",  "amount": 150000,  "balance": 0}

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",  "description": "my transaction description",  "amount": 150000,  "balance": 0}

Payment settling#

An inbound payment has been initiated, however funds may take some time to clear into the escrow account.

This event is fired when a card payment is made by the user. Card payments can take around T+2 days to settle. The balance field does not include any settling payments as they do not form part of the escrow account balance at this point.

note

You will also receive a payment_received webhook with the same paymentToken. The following payment_received webhook will denote when the funds have cleared into the escrow account.

{  "type": "payment_settling",  "from": "buyer@example.com",  "to": "seller@example.com",  "verification": {    "from": "verified",    "to": "unverified"  },  "token": "5CIXLExTtrIE8387",  "paymentToken": "oXkIwJcxE3S3Z8BX",  "currency": "gbp",  "description": "my transaction description",  "amount": 15000,  "balance": 0}

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",  "description": "my transaction description",  "amount": 150000,  "balance": 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",  "description": "my transaction description"}

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",  "description": "my transaction description"}