Webhooks Notification

Account status updated events

The Account Status Updated webhook is triggered whenever there is a change in the status of a user’s account within our system that impacts payments.

Event Name

ACCOUNT_STATUS_UPDATED

Payload Structure

The webhook will send a JSON payload in the following format:

{
  "id": 145553,
  "isPaymentReady": true,
  "isVerified": false
}

Fields

1. id: Our internal account id.
2. isPaymentReady: Boolean indicating that all information required is informed.
3. isVerified: Boolean indicating if the account is verified.

See Create new callback configuration to setup this webhook

Payment status updated events

When sending a payment request, developers can find out about the payment status by calling Get Payment Status. There will be times where "real time" updates are needed and webhooks can provide that. To leverage webhooks, you would need to register a callback URL that we will notify anytime an event happens to the payment.

For example, after a payment is "sent" by you, it would be in "PendingAuth" (or pending authorization) state. As it moves from "PendingAuth" to "Authorized", webhooks will post a notification that an event has occurred. You can then call Get Payment Status to find out the current state and other relevant details.

To understand the notification states, here's a mapping of the webhooks notifications and to what is shown in the customer UI. Note that there will be updates / changes to how the states are presented to a customer to simplify the messaging. The states received via webhooks will NOT change to ensure backwards compatibility.

The states that webhooks will post notifications for are highlighted in bold below:

Invoice status updated events

The Invoice Status Updated webhook is triggered whenever an invoice undergoes a status change.

Event Name

INBOUND_INVOICE_STATUS_UPDATED
INBOUND_INVOICE_STATUS_UPDATED

Status

Payload Structure

The webhook will send a JSON payload in the following format:

{
    "id": 124585,
    "status": "Sent",
    "amount": {
        "number": 500.00,
        "currency": "USD"
    },
    "payerAccountId": 36699,
    "payeeAccountId": 14521,
    "dueDate": "2025-01-01",
    "scheduledSentDateIso": "2025-01-01",
    "paymentId": 123
}

Create new callback configuration

For creating a webhook to be notified when a status payment change occurs you should use the following endpoint

POST https://sandbox-api.veem.com/veem/v1.2/webhooks

Headers

• X-request-id: For example 48855846-628d-4177-b071-80332a116f0a
• Authorization: Bearer bearerToken

bearerToken is the Authorization token that belongs to the account created

i.e. Bearer d49e7fd4-2600-4dd4-a572-118668febbe7

see this section to generate your bearerToken

You can configure two types of events:

1. OUTBOUND_PAYMENT_STATUS_UPDATED Will notify you of status changes on payments sent by you
2. INBOUND_PAYMENT_STATUS_UPDATED Will notify you of status changes on payments sent to you

{
    "callbackURL":"https://typedwebhook.tools/webhook/b8d85c63-b0fe-4c31-8c27-ccfeff52da59",
    "event":"OUTBOUND_PAYMENT_STATUS_UPDATED"
}	

{
    "id": 31,
    "event": "OUTBOUND_PAYMENT_STATUS_UPDATED",
    "callbackUrl": "https://typedwebhook.tools/webhook/b8d85c63-b0fe-4c31-8c27-ccfeff52da59",
    "status": "Active"
}

Update a callback configuration

For updating a webhook configuration you can use the following endpoint

PATCH https://sandbox-api.veem.com/veem/v1.2/webhooks/{webhookId}

Headers

• X-request-id: For example 48855846-628d-4177-b071-80332a116f0a
• Authorization: Bearer bearerToken

bearerToken is the Authorization token that belongs to the account created

i.e. Bearer d49e7fd4-2600-4dd4-a572-118668febbe7

see this section to generate your bearerToken

{
  "callbackURL":"https://typedwebhook.tools/webhook/b8d85c63-b0fe-4c31-8c27-ccfeff52da59",
  "event":"OUTBOUND_PAYMENT_STATUS_UPDATED"
}

{
    "id": 31,
    "event": "OUTBOUND_PAYMENT_STATUS_UPDATED",
    "callbackUrl": "https://typedwebhook.tools/webhook/b8d85c63-b0fe-4c31-8c27-ccfeff52da59",
    "status": "Active"
}

Get existing callback configurations

For querying the existent webhooks you can call the next endpoint

GET https://sandbox-api.veem.com/veem/v1.2/webhooks

Headers

• X-request-id: For example 48855846-628d-4177-b071-80332a116f0a
• Authorization: Bearer bearerToken

bearerToken is the Authorization token that belongs to the account created

i.e. Bearer d49e7fd4-2600-4dd4-a572-118668febbe7

see this section to generate your bearerToken

{
    "id": 31,
    "event": "OUTBOUND_PAYMENT_STATUS_UPDATED",
    "callbackUrl": "https://typedwebhook.tools/webhook/b8d85c63-b0fe-4c31-8c27-ccfeff52da59",
    "status": "Active"
}

Delete a callback configuration

For deleting a webhook configuration use the following endpoint

DELETE https://sandbox-api.veem.com/veem/v1.2/webhooks/{webhookId}

Headers

• X-request-id: For example 48855846-628d-4177-b071-80332a116f0a
• Authorization: Bearer bearerToken

bearerToken is the Authorization token that belongs to the account created

i.e. Bearer d49e7fd4-2600-4dd4-a572-118668febbe7

see this section to generate your bearerToken

{
    "id": 31,
    "event": "OUTBOUND_PAYMENT_STATUS_UPDATED",
    "callbackUrl": "https://typedwebhook.tools/webhook/b8d85c63-b0fe-4c31-8c27-ccfeff52da59",
    "status": "Inactive"
}

Getting the notifications

Once you configure webhooks URL, Veem will send notification for payment status updates to that endpoint with the following payload.

The data is JSON content wrapped in string.

{
  "type": "OUTBOUND_PAYMENT_STATUS_UPDATED",
  "data": {
    "id": 1,
    "invoiceId": 1,
    "status": "Authorized",
    "debitTxn": {
      "id": 1,
      "status": "Pending",
      "errorCode": "01345",
      "errorMessage": "In case of reversal"
    },
    "creditTxn": {
      "id": 2,
      "status": "Pending",
      "errorCode": "01345",
      "errorMessage": "In case of reversal"
    }
  }
}

Retry Mechanism

The three webhooks mentioned above include a retry mechanism that attempts delivery up to three times, with a 5-second interval between each attempt.