Messages
Create a notification message for a specific merchant.
POST /v1/notifications/admin/messages/merchant/{merchantReference}
Auth: API key (VantagePayAdminClient).
Parameters
| Name | In | Required | Description |
|---|---|---|---|
merchantReference | path | Yes | A globally unique internal merchant reference (UUID). |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
messageType | Information, Warning, Critical | Yes | The delivery channel for the message (e.g. push notification, in-app banner). |
messageTarget | None, Portal, Terminal, Email | Yes | The audience this message is intended for (e.g. consumers, merchants). |
messagePlacement | None, Dashboard, Reports, ValueAddedServices, Profile, QR, Transactions, Loans, HelpAndSupport, UserManagement, Devices | No | The placement within the application where the message will be displayed (e.g. top banner, feed). |
header | string | Yes | The message heading, limited to 512 characters. |
body | string | Yes | The main body text of the message. |
buttonText | string? | No | The label for the call-to-action button, limited to 128 characters. Omit for messages without a button. |
navigationKey | string? | No | A key identifying the in-app navigation destination when the message action is triggered (e.g. "screen"). |
navigationValue | string? | No | The value associated with ZGA.Core.Models.Notifications.Requests.CreateMessageRequest.NavigationKey that specifies the exact destination (e.g. a screen name or route path). |
visibleFromDate | string? | No | The earliest date from which the message should be shown. If null, the message is visible immediately upon creation. |
visibleUntilDate | string | Yes | The date after which the message will no longer be displayed. |
json
{
"messageType": "Information",
"messageTarget": "None",
"messagePlacement": "None",
"header": "string",
"body": "string",
"buttonText": "string",
"navigationKey": "string",
"navigationValue": "string",
"visibleFromDate": "string",
"visibleUntilDate": "string"
}1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
Responses
| Status | Description |
|---|---|
200 | The request was successful and the message was created. |
400 | The request failed validation, the error object will contain further information. |
401 | The authorization information provided is not valid, authentication is required to access this resource. |
403 | The authorization header does not contain the correct type or you do not have access to this resource. |
422 | The request payload is invalid, the error object will contain further information. |
429 | Too many requests are being sent concurrently or rate limiting has taken effect. |
500 | An unexpected error occurred, the error object will contain further information. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | No | Gets a value indicating whether the operation was successful. |
result | object | No | An in-app notification message displayed to a consumer or merchant. |
json
{
"success": true,
"result": {
"reference": "00000000-0000-0000-0000-000000000000",
"messageType": "Information",
"messageTarget": "None",
"messagePlacement": "None",
"header": "string",
"body": "string",
"navigationKey": "string",
"navigationValue": "string",
"buttonText": "string",
"isRead": true,
"readDate": "string",
"visibleFromDate": "string",
"visibleUntilDate": "string",
"createdDate": "string"
}
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
Code samples
WARNING
The JavaScript SDK does not cover admin APIs - use the .NET SDK.
csharp
using VantagePay.Models.Notifications;
using VantagePay.Models.Notifications.Requests;
var message = await adminClient.Notifications.CreateMerchantMessageAsync(
new CreateMessageRequest
{
MessageType = MessageType.Information,
MessageTarget = MessageTarget.Portal,
MessagePlacement = MessagePlacement.Dashboard,
Header = "Planned Maintenance",
Body = "Service window starts at 22:00 UTC.",
VisibleUntilDate = DateTimeOffset.UtcNow.AddDays(7),
},
Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"));1
2
3
4
5
6
7
8
9
10
11
12
13
14
2
3
4
5
6
7
8
9
10
11
12
13
14
Get all notification messages for the merchant.
GET /v1/notifications/admin/messages/merchant/{merchantReference}
Auth: API key (VantagePayAdminClient).
Parameters
| Name | In | Required | Description |
|---|---|---|---|
merchantReference | path | Yes | A globally unique internal merchant reference (UUID). |
Responses
| Status | Description |
|---|---|
200 | The request was successful and the messages were returned. |
400 | The request failed validation, the error object will contain further information. |
401 | The authorization information provided is not valid, authentication is required to access this resource. |
403 | The authorization header does not contain the correct type or you do not have access to this resource. |
422 | The request payload is invalid, the error object will contain further information. |
429 | Too many requests are being sent concurrently or rate limiting has taken effect. |
500 | An unexpected error occurred, the error object will contain further information. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | No | Gets a value indicating whether the operation was successful. |
result | array<object>? | No | Gets the response payload. |
json
{
"success": true,
"result": [
{}
]
}1
2
3
4
5
6
2
3
4
5
6
Code samples
WARNING
The JavaScript SDK does not cover admin APIs - use the .NET SDK.
csharp
var messages = await adminClient.Notifications.GetMerchantMessagesAsync(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"));1
Create a notification message for a specific consumer.
POST /v1/notifications/admin/messages/consumer/{consumerReference}
Auth: API key (VantagePayAdminClient).
Parameters
| Name | In | Required | Description |
|---|---|---|---|
consumerReference | path | Yes | A globally unique internal consumer reference (UUID). |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
messageType | Information, Warning, Critical | Yes | The delivery channel for the message (e.g. push notification, in-app banner). |
messageTarget | None, Portal, Terminal, Email | Yes | The audience this message is intended for (e.g. consumers, merchants). |
messagePlacement | None, Dashboard, Reports, ValueAddedServices, Profile, QR, Transactions, Loans, HelpAndSupport, UserManagement, Devices | No | The placement within the application where the message will be displayed (e.g. top banner, feed). |
header | string | Yes | The message heading, limited to 512 characters. |
body | string | Yes | The main body text of the message. |
buttonText | string? | No | The label for the call-to-action button, limited to 128 characters. Omit for messages without a button. |
navigationKey | string? | No | A key identifying the in-app navigation destination when the message action is triggered (e.g. "screen"). |
navigationValue | string? | No | The value associated with ZGA.Core.Models.Notifications.Requests.CreateMessageRequest.NavigationKey that specifies the exact destination (e.g. a screen name or route path). |
visibleFromDate | string? | No | The earliest date from which the message should be shown. If null, the message is visible immediately upon creation. |
visibleUntilDate | string | Yes | The date after which the message will no longer be displayed. |
json
{
"messageType": "Information",
"messageTarget": "None",
"messagePlacement": "None",
"header": "string",
"body": "string",
"buttonText": "string",
"navigationKey": "string",
"navigationValue": "string",
"visibleFromDate": "string",
"visibleUntilDate": "string"
}1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
Responses
| Status | Description |
|---|---|
200 | The request was successful and the message was created. |
400 | The request failed validation, the error object will contain further information. |
401 | The authorization information provided is not valid, authentication is required to access this resource. |
403 | The authorization header does not contain the correct type or you do not have access to this resource. |
422 | The request payload is invalid, the error object will contain further information. |
429 | Too many requests are being sent concurrently or rate limiting has taken effect. |
500 | An unexpected error occurred, the error object will contain further information. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | No | Gets a value indicating whether the operation was successful. |
result | object | No | An in-app notification message displayed to a consumer or merchant. |
json
{
"success": true,
"result": {
"reference": "00000000-0000-0000-0000-000000000000",
"messageType": "Information",
"messageTarget": "None",
"messagePlacement": "None",
"header": "string",
"body": "string",
"navigationKey": "string",
"navigationValue": "string",
"buttonText": "string",
"isRead": true,
"readDate": "string",
"visibleFromDate": "string",
"visibleUntilDate": "string",
"createdDate": "string"
}
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
Code samples
WARNING
The JavaScript SDK does not cover admin APIs - use the .NET SDK.
csharp
using VantagePay.Models.Notifications;
using VantagePay.Models.Notifications.Requests;
var message = await adminClient.Notifications.CreateConsumerMessageAsync(
new CreateMessageRequest
{
MessageType = MessageType.Information,
MessageTarget = MessageTarget.Portal,
MessagePlacement = MessagePlacement.Dashboard,
Header = "Planned Maintenance",
Body = "Service window starts at 22:00 UTC.",
VisibleUntilDate = DateTimeOffset.UtcNow.AddDays(7),
},
Guid.Parse("7c9e6679-7425-40de-944b-e07fc1f90ae7"));1
2
3
4
5
6
7
8
9
10
11
12
13
14
2
3
4
5
6
7
8
9
10
11
12
13
14
Get all notification messages for the consumer.
GET /v1/notifications/admin/messages/consumer/{consumerReference}
Auth: API key (VantagePayAdminClient).
Parameters
| Name | In | Required | Description |
|---|---|---|---|
consumerReference | path | Yes | A globally unique internal consumer reference (UUID). |
Responses
| Status | Description |
|---|---|
200 | The request was successful and the messages were returned. |
400 | The request failed validation, the error object will contain further information. |
401 | The authorization information provided is not valid, authentication is required to access this resource. |
403 | The authorization header does not contain the correct type or you do not have access to this resource. |
422 | The request payload is invalid, the error object will contain further information. |
429 | Too many requests are being sent concurrently or rate limiting has taken effect. |
500 | An unexpected error occurred, the error object will contain further information. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | No | Gets a value indicating whether the operation was successful. |
result | array<object>? | No | Gets the response payload. |
json
{
"success": true,
"result": [
{}
]
}1
2
3
4
5
6
2
3
4
5
6
Code samples
WARNING
The JavaScript SDK does not cover admin APIs - use the .NET SDK.
csharp
var messages = await adminClient.Notifications.GetConsumerMessagesAsync(Guid.Parse("7c9e6679-7425-40de-944b-e07fc1f90ae7"));1
Get a single notification message by reference.
GET /v1/notifications/admin/messages/{messageReference}
Auth: API key (VantagePayAdminClient).
Parameters
| Name | In | Required | Description |
|---|---|---|---|
messageReference | path | Yes | The unique reference of the message. |
Responses
| Status | Description |
|---|---|
200 | The request was successful and the message was returned. |
400 | The request failed validation, the error object will contain further information. |
401 | The authorization information provided is not valid, authentication is required to access this resource. |
403 | The authorization header does not contain the correct type or you do not have access to this resource. |
404 | The request was successful but does not return any results. |
422 | The request payload is invalid, the error object will contain further information. |
429 | Too many requests are being sent concurrently or rate limiting has taken effect. |
500 | An unexpected error occurred, the error object will contain further information. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | No | Gets a value indicating whether the operation was successful. |
result | object | No | An in-app notification message displayed to a consumer or merchant. |
json
{
"success": true,
"result": {
"reference": "00000000-0000-0000-0000-000000000000",
"messageType": "Information",
"messageTarget": "None",
"messagePlacement": "None",
"header": "string",
"body": "string",
"navigationKey": "string",
"navigationValue": "string",
"buttonText": "string",
"isRead": true,
"readDate": "string",
"visibleFromDate": "string",
"visibleUntilDate": "string",
"createdDate": "string"
}
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
Code samples
WARNING
The JavaScript SDK does not cover admin APIs - use the .NET SDK.
csharp
var message = await adminClient.Notifications.GetMessageAsync(Guid.Parse("2a2b2c2d-3e3f-4a4b-5c5d-6e6f7a7b8c9d"));1
Delete a notification message.
DELETE /v1/notifications/admin/messages/{messageReference}
Auth: API key (VantagePayAdminClient).
Parameters
| Name | In | Required | Description |
|---|---|---|---|
messageReference | path | Yes | The unique reference of the message. |
Responses
| Status | Description |
|---|---|
200 | The request was successful and the message was deleted. |
400 | The request failed validation, the error object will contain further information. |
401 | The authorization information provided is not valid, authentication is required to access this resource. |
403 | The authorization header does not contain the correct type or you do not have access to this resource. |
404 | The request was successful but does not return any results. |
422 | The request payload is invalid, the error object will contain further information. |
429 | Too many requests are being sent concurrently or rate limiting has taken effect. |
500 | An unexpected error occurred, the error object will contain further information. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | No | Gets a value indicating whether the operation was successful. |
json
{
"success": true
}1
2
3
2
3
Code samples
WARNING
The JavaScript SDK does not cover admin APIs - use the .NET SDK.
csharp
await adminClient.Notifications.DeleteMessageAsync(Guid.Parse("2a2b2c2d-3e3f-4a4b-5c5d-6e6f7a7b8c9d"));1
Mark a notification message as read.
PATCH /v1/notifications/admin/messages/{messageReference}/read
Auth: API key (VantagePayAdminClient).
Parameters
| Name | In | Required | Description |
|---|---|---|---|
messageReference | path | Yes | The unique reference of the message. |
Responses
| Status | Description |
|---|---|
200 | The request was successful and the message was marked as read. |
400 | The request failed validation, the error object will contain further information. |
401 | The authorization information provided is not valid, authentication is required to access this resource. |
403 | The authorization header does not contain the correct type or you do not have access to this resource. |
404 | The request was successful but does not return any results. |
422 | The request payload is invalid, the error object will contain further information. |
429 | Too many requests are being sent concurrently or rate limiting has taken effect. |
500 | An unexpected error occurred, the error object will contain further information. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | No | Gets a value indicating whether the operation was successful. |
json
{
"success": true
}1
2
3
2
3
Code samples
WARNING
The JavaScript SDK does not cover admin APIs - use the .NET SDK.
csharp
await adminClient.Notifications.MarkMessageAsReadAsync(Guid.Parse("2a2b2c2d-3e3f-4a4b-5c5d-6e6f7a7b8c9d"));1