Webhooks Notification
Use webhooks to be notified about payment events for a payment transaction.
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:
Status | Status in our Customer App UI | Description |
---|---|---|
Drafted | Drafted | Payment is in drafted state and requires further updates. |
Sent | Sent | The payment has been sent to the receiver/payee. |
PendingAuth | Claimed | The payment is in pending authorization by Veem. |
Authorized | Claimed | The payment has been authorized and is ready for processing. The money will be withdrawn from sender's bank. |
InProgress | In Progress | The payment has been initiated and receiver will be receiving money shortly. |
Complete | Deposited | The payment is complete and the receiver should have received the money. |
Cancelled | Closed | The payment has been cancelled by the sender/payer. |
Closed | Closed | The payment has been closed by Veem by request from the sender, or receiver, or due to an error with the payment. |
Create new callback configuration
For creating a webhook to be notified when a status payment change occurs you should use the following endpoint
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"
}
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
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"
}
}
}
Updated 20 days ago