Webhook Conventions
This page defines the JSON payloads for all webhook notifications sent by Maast. For instructions on how to create and manage webhooks, refer to our Webhooks API and Webhooks in Maast Manager guides. See API Reference for non-event-specific field definitions as well as sample requests and responses for all Webhook API requests.
Webhook Events
The following table contains a list of webhook events and their corresponding event schemas:
Event | Event Schema | Event Description |
---|---|---|
validate_url | none | This event is only used to validate that Maast can post events to the URL. Unlike the other events, it is never logged, and the data field is empty. |
subscription_suspended | subscription | The subscription was suspended by the Recurring Billing engine. |
subscription_complete | subscription | The subscription cycle has completed. |
subscription_payment_success | subscription | The recurring charge to the cardholder was successful. |
subscription_payment_failure | subscription | The recurring charge to the cardholder was declined. |
subscription_created | subscription | A new subscription was created. |
subscription_updated | subscription | A subscription was updated. |
account_updater_request_created | account_updater_summary | The Account Updater request has been created. |
account_updater_request_complete | account_updater_summary | The Account Updater request to update card data has completed. |
checkout_payment_success | checkout | A successful transaction has been posted for checkout. |
checkout_payment_failure | checkout | A transaction attempt using checkout was declined. |
checkout_vault_card_added | checkout_vault | A card was added to a customer using Hosted Checkout. |
checkout_vault_card_updated | checkout_vault | A Customer Vault card was updated successfully using Hosted Checkout. |
invoice_paid | invoice | The invoice has been paid in full. This webhook is triggered only when a customer makes an invoice payment. |
invoice_payment_success | invoice_payment | A successful invoice transaction has been posted. |
invoice_payment_failure | invoice_payment | An invoice transaction was declined. |
invoice_email_undeliverable | invoice_email | The invoice emailed to the customer was undeliverable. |
qp_manager_auth_success | qp_payment | The authorization request initiated from Maast Manager was successful. |
qp_manager_sale_success | qp_payment | The sale request initiated from Maast Manager was successful. |
qp_manager_force_success | qp_payment | The force request initiated from Maast Manager was successful. |
qp_manager_credit_success | qp_payment | The credit request initiated from Maast Manager was successful. |
qp_manager_capture_success | qp_payment | The capture request initiated from Maast Manager was successful. |
qp_manager_void_success | qp_payment | The void request initiated from Maast Manager was successful. |
qp_manager_refund_success | qp_payment | The refund request initiated from Maast Manager was successful. |
qp_manager_auth_failure | qp_payment | The authorization request initiated from Maast Manager was unsuccessful. |
qp_manager_sale_failure | qp_payment | The sale request initiated from Maast Manager was unsuccessful. |
qp_manager_force_failure | qp_payment | The force request initiated from Maast Manager was unsuccessful. |
qp_manager_credit_failure | qp_payment | The credit request initiated from Maast Manager was unsuccessful. |
qp_manager_capture_failure | qp_payment | The capture request initiated from Maast Manager was unsuccessful. |
qp_manager_void_failure | qp_payment | The void request initiated from Maast Manager was unsuccessful. |
qp_manager_refund_failure | qp_payment | The refund request initiated from Maast Manager was unsuccessful. |
application_approved | application | The Maast application was approved. |
application_declined | application | The Maast application was declined. |
application_cancelled | application | The Maast application was canceled. |
transaction_status_updated | transactions | The status of recently updated transactions. This includes ACH payment status updates such as rejections or late returns. The response contains a list of transactions whose statuses were updated by nightly settlement and funding runs. |
ach | ach_case | Notifications of change (NOC) or late returns received for ACH transactions. |
Notifications Schema
This section provides the request schema for all webhooks. Every webhook request contains the fields listed in Schema for All Webhooks. The data
object contains event-specific fields, which you can find in the following sections under the relevant event schema.
Schema for All Webhooks
Every webhook returns the following fields. All requests will have application/JSON content type and will contain JSON in the payload:
Field Name | Format | Description |
---|---|---|
webhook_id | Variable length, up to 10 N | The Unique ID assigned by Maast to a webhook. |
db_timestamp | Variable length, string | Webhook creation time. |
event | Variable length, up to 64 AN | The webhook event. Refer to the Webhook Events section for available events. |
is_test | Boolean | Set to true if the request is from sandbox (test) environment. Set to false if the request is from the production environment. |
data | JSON object | Data specific to the event. Refer to the appropriate event schema below. |
subscription
subscription
The following table shows fields included in the data
object of a subscription
-type webhook payload:
Field Name | Format | Description |
---|---|---|
merchant_id | Variable length, up to 16 N | A unique ID assigned by Maast to a merchant. |
subscription_id | Variable length, up to 10 N | A Maast-generated ID that identifies a subscription. |
status | Fixed length, 1 A | The status of the subscription. Possible values: • A - Active• D - Complete • P - Paused • C - Canceled • S - Suspended |
subscription_on_plan | Boolean | This is set to true if the subscription is associated with a recurring plan. It is set tofalse for off-plan subscriptions. |
plan_id | Variable length, up to 10 N | A Maast-generated ID that identifies a recurring plan. Set to 0 if this is an off-plan subscription. |
plan_name | Variable length, up to 64 AN | A unique name assigned by the merchant to a plan. |
plan_code | Variable length, up to 16 AN | A unique code assigned by the merchant to a plan. |
plan_desc | Variable length, up to 64 AN | A short description of the plan. |
plan_frequency | Fixed length, 1 N | The frequency of billing. Possible values: • 0 - Weekly • 1 - Bi-Weekly • 3 - Monthly • 4 - Quarterly • 5 - Bi-Annually • 6 - Annually |
interval | Variable length, up to 2 N | The number of months in a subscription cycle. Valid only for monthly subscriptions. |
plan_duration | Variable length, up to 4 N | The number of billing cycles in the subscription. -1 means to bill until canceled. |
customer_id | Variable length, up to 32 AN | The customer ID assigned to this subscription. |
customer_first_name | Variable length, up to 64 AN | The first name of the plan subscriber. |
customer_last_name | Variable length, up to 64 AN | The last name of the plan subscriber. |
date_start | String date in YYYY-MM-DD format | The date the subscription will (or did) start. |
date_next | String date in YYYY-MM-DD format | The date of next billing. This field will be empty if it is a canceled or completed subscription. |
date_end | String date in YYYY-MM-DD format | The date the subscription will (or did) end. |
amt_setup | Variable length, up to 12,2 N | A one-time fee amount. This is the fee charged when a subscription is added. |
profile_id | Fixed length, 20 N | The Maast Payment Gateway profile ID used for billing the customer. |
tran_currency | Fixed length, 3 N | The ISO numeric currency code for the transaction. |
prorate_date_start | String date in YYYY-MM-DD format | The date the customer will be (or was) billed the prorated amount if the first payment is prorated. |
prorate_amt | Variable length, up to 12,2 N | The prorated amount if the first payment is prorated. |
trial_date_start | String date in YYYY-MM-DD format | The date the trial period will (or did) start if the subscription has a trial period. |
trial_date_end | String date in YYYY-MM-DD format | The date the trial period will (or did) end if the subscription has a trial period. |
trial_amt | Variable length, up to 12,2 N | The amount billed during the trial if the subscription has a trial period. |
recur_date_start | String date in YYYY-MM-DD format | The date the regular billing cycle will (or did) start. |
recur_date_end | String date in YYYY-MM-DD format | The date the regular billing cycle will (or did) end. |
recur_amt | Variable length, up to 12,2 N | The regular billing amount. |
pg_id | Fixed length, 32 AN | A unique identifier generated by the payment gateway for this transaction. Applicable only to subscription_payment_success and subscription_payment_failure events. |
rcode | Variable length, up to 3 AN | The response code from the Payment Gateway API. Refer to Payment Gateway API Response Codes for valid codes. An rcode value of 000 , 008 , 010 , or 011 indicates an approved request. Applicable only to subscription_payment_success and subscription_payment_failure events. |
rmsg | Variable length, AN | A short text description of the rcode from the Payment Gateway API. Applicable only to subscription_payment_success and subscription_payment_failure events. |
amt_tran | Variable length, up to 12,2 N | The transaction amount. Applicable only to subscription_payment_success and subscription_payment_failure events. |
auth_code | Fixed length, 6 AN | The authorization code returned when the transaction was sent to the card issuer for approval. Applicable only to subscription_payment_success and subscription_payment_failure events. |
See the code below for a sample subscription
-type webhook payload:
{
webhook_id: 999,
db_timestamp: "20170613093002",
event: "subscription_payment_success",
is_test: true,
data: {
subscription_id: 9999,
merchant_id: 999000010999,
date_start: "2022-03-21",
date_next: "2022-06-20",
date_end: "9999-12-31",
prorate_date_start: "",
prorate_amt: 0,
trial_date_start: "",
trial_date_end: "",
trial_amt: 0,
recur_date_start: "2022-03-21",
recur_date_end: "9999-12-31",
recur_amt: 1,
amt_setup: 0,
status: "A",
profile_id: "99900001099900010840",
customer_id: "JOHNDOE",
customer_first_name: "John",
customer_last_name: "Doe",
plan_id: 99999,
plan_name: "ONCEAWEEK",
plan_code: "ONCEAWEEK",
tran_currency: "840",
plan_frequency: 0,
plan_duration: -1,
plan_desc: "",
subscription_on_plan: true,
interval: 1,
pg_id:"3fd9b4ed85e411e8a8720a56f26adaaa",
rcode:"000",
rmsg:"Approved T23111",
amt_tran:"1.00",
auth_code:"T23111"
}
}
account_updater_summary
account_updater_summary
The following table shows fields included in the data
object of an account_updater_summary
-type webhook payload:
Field Name | Format | Description |
---|---|---|
merchant_id | Variable length, up to 16 N | A unique ID assigned by Maast to a merchant. |
request_id | Variable length, up to 10 N | A unique ID assigned by Maast to the Account Updater request. |
request_date | String date in YYYY-MM-DD format | The date when a harvest request was sent to the Account Updater service. |
status | String | The status of the request. COMPLETED indicates the Account Updater request is complete. |
cnt_request | Variable length, up to 10 N | The number of cards in this request. |
cnt_response | Variable length, up to 10 N | The number of cards in this request that were reviewed by Account Updater. This should match the cnt_request . |
cnt_update | Variable length, up to 10 N | The number of cards in this request that were updated by Account Updater. |
See the code below for a sample account_updater_summary
-type webhook payload:
{
"webhook_id": 998,
"db_timestamp": "20170615100017",
"event": "account_updater_request_complete",
"is_test": true,
"data": {
"request_id": 999,
"merchant_id": 999999999999,
"status": "COMPLETED",
"cnt_request": 7,
"cnt_response": 7,
"cnt_update": 2,
"request_date": "2022-06-15"
}
}
checkout
checkout
The following table shows fields included in the data
object of a checkout
-type webhook payload:
Field Name | Format | Description |
---|---|---|
checkout_id | Fixed length, 32 AN | A unique identifier generated when a Checkout resource is created. |
pg_id | Fixed length, 32 AN | A unique identifier generated by the payment gateway for each transaction. |
rcode | Variable length, up to 3 AN | The response code from the payment gateway application. Refer to Payment Gateway Response Codes to get a valid list of rcode . An rcode value of 000 , 008 , 010 , or 011 indicates an approved request. |
rmsg | Variable length, AN | A short text description of the rcode from the Maast payment gateway. |
tran_time | Fixed length, 19AN year, month, day, and time in ISO date-time format (ex: 2022-12-03T10:15:30 ) | The date timestamp of when the transaction was submitted. The time is in PST (U.S.). |
card_number | Variable length, up to 16 AN | The masked card number. |
card_id | Fixed length, 32 AN | The tokenized card number. Applicable only if customer_id is sent in the Checkout request. |
amt_tran | Variable length, up to 12,2 N | The transaction amount. |
tran_currency | Fixed length, 3 N | The ISO numeric currency code for the transaction. |
purchase_id | Variable length, up to 25 AN | The purchase identifier (also referred to as the invoice number) included in the request. |
profile_id | Variable length, up to 20 AN | The Payment Gateway profile ID used for billing the customer. |
auth_code | Fixed length, 6 AN | The authorization code returned when the transaction was sent to the card issuer for approval. |
auth_response_desc | Variable length, AN | A short description of the authorization result. |
cvv2_result | Fixed length, 1 AN | If the customer enters their cvv in the Checkout page, the result from the card issuer is returned in this field. |
avs_result | Fixed length, 1 AN | If billing_zip (and optionally the billing_street_addr1 ) are provided in the checkout request or in the Checkout page, then the result from the card issuer will be returned in this field. |
recurring | Boolean | Identifies whether this is a recurring transaction (true ) or a one-time payment (false ). |
merchant_id | Variable length, up to 12 N | A unique ID assigned by Maast to a merchant. |
client_ip | Variable length | The IP address of the device making the payment. |
dba_name | Variable length, up to 25 AN | The 'Doing Business As' name associated with the profile. |
customer_id | Variable length, up to 32 AN | A unique ID that identifies a customer in Customer Vault. |
customer | JSON data | The customer information submitted with the transaction. Possible fields: • customer_first_name • customer_last_name • customer_firm_name • customer_email • customer_phone_number • billing_addr1 • billing_addr2 • billing_state • billing_city • billing_zip • billing_country |
option_info | JSON data | Information submitted with transaction through Optional Information fields on the Checkout form. Possible fields: • label • desc • value |
duration | Variable length, N | The duration of the gateway request in ms. |
http_status | Fixed length, 3 N | The HTTP status of the payment gateway request. |
http_status_text | Variable length, AN | A short description of the HTTP status. |
See the code below for a sample checkout
-type webhook payload:
{
"webhook_id":209,
"db_timestamp":"20170908100614",
"event":"checkout_payment_success",
"is_test":true,
"data":{
"http_status":200,
"http_status_text":"OK",
"rcode":"000",
"status":"Approved",
"amt_tran":"91.54",
"purchase_id":"Acme3884",
"auth_code":"T59396",
"recurring": false,
"customer":{
"customer_first_name":"John",
"customer_last_name":"Doe",
"customer_email": "[email protected]",
"billing_addr1": "4 W 4th Ave",
"billing_addr2": "500",
"billing_city": "San Mateo",
"billing_state": "CA",
"billing_zip": "94402",
"billing_country": "840",
"customer_firm_name": "Acme",
"customer_phone": "+19250160147"
},
"option_info": {
"desc": "Please select items",
"label": "Option Information",
"value": [
"Notebooks"
]
},
"cvv2_result":"-",
"avs_result":"Z",
"rmsg":"Approved T59396",
"pg_id":"0512541494b811e7a1dc0a728c0d49c0",
"card_id":"1715d1bf89d311e795d20a728c0d49c0",
"tran_currency":"840",
"currencyAlpha":"USD",
"dba_name":"JOHN - USD",
"card_number":"424242xxxxxx4242",
"customer_id":"johndoe",
"client_ip":"24.6.81.199",
"duration":50,
"tran_time":"2022-09-08T10:06:13.845-0700",
"auth_response_desc":"Approved and completed successfully",
"merchant_id":999900010999,
"profile_id":"99990001099900010840",
"checkout_id":"fe0ed3af94b711e7b89e0a3416b2e023"
}
}
checkout_vault
checkout_vault
The following table shows fields included in the data
object of a checkout_vault
-type webhook payload:
Field Name | Format | Description |
---|---|---|
customer_id | Variable length, up to 32 AN | The customer ID found in the Maast Customer Vault. |
card_id | Variable length, upto 32 N | A unique ID that represents the customer's payment method that was added or updated. |
See the code below for a sample checkout_vault
-type webhook payload:
{
"webhook_id": 209,
"db_timestamp": "20180905115418",
"event": "checkout_vault_card_added",
"is_test": true,
"data": {
"http_status":200,
"http_status_text":"OK",
"customer_id":"johndoe",
"card_id":"1715d1bf89d311e795d20a728c0d49c0",
}
}
invoice
invoice
The following table shows fields included in the data
object of an invoice
-type webhook payload:
Field Name | Format | Description |
---|---|---|
invoice_id | Variable length, up to 10 N | A unique number generated by Maast to identify an invoice. |
merchant_id | Variable length, up to 12 N | A unique ID assigned by Maast to a merchant. |
invoice_number | Variable length, up to 25 AN | The invoice number (also referred to as the purchase identifier) generated by the merchant. |
customer_id | Variable length, up to 32 AN | A unique ID that identifies a customer in Customer Vault. |
from_contact | JSON data | An array of merchant business contact information. Possible fields: • first_name • last_name • firm_name • address1 • address2 • city • state • zip • zip4 • phone • email_address • country_code • country |
billing_contact | JSON data | An array of customer contact information. Possible fields: • first_name • last_name • firm_name • address1 • address2 • city • state • zip • zip4 • phone • email_address • country_code • country |
status | Variable length, up to 16 AN | Status of an invoice. Possible values: • OUTSTANDING - The invoice has been sent to the customer and is not yet completely paid. Once an invoice is sent, only the billing_contact and from_contact can be updated. • PAID - The invoice has been completely paid. Once paid, the invoice is locked and cannot be modified. |
amt_tran | Variable length, up to 10,2 N | The total invoice amount. Typically this will be a sum of the line item totals and the tax amount. |
amt_tax | Variable length, up to 10,2 N | The tax amount. This amount is automatically calculated if the tax rate is provided. |
amt_sub_total | Variable length, up to 12,2 N | The sum of all line item total amounts. |
amt_paid | Variable length, up to 12,2 N | The amount paid by the customer. |
amt_balance | Variable length, up to 12,2 N | The amount due from the customer. This amount is typically amt_tran minus amt_paid . |
profile_id | Variable length, up to 20 AN | The Payment Gateway profile ID used for billing the customer. |
tran_currency | Fixed length, 3 N | The ISO numeric currency code for the transaction. |
footer_note | Variable length, up to 750 AN | The invoice footer note. This data is displayed on the footer of the invoice. |
payment_terms_note | Variable length, up to 500 AN | The invoice payment terms description. |
checkout_settings | JSON data | An array of invoice settings specific to the Checkout page. This can contain: • allow_partial_payments (Boolean) - If set to true , the customer can edit the transaction amount on the invoice Checkout page. This flag may be set to true to allow the customer to make partial payments.• email_receipt (Boolean) - If set to true and the customer's email address is provided, Maast generates and sends a receipt to the customer once a payment is made. |
invoice_link | Variable length | The URL of the payment form associated with the invoice. This appears as a link in the invoice once the invoice has been completed and sent to a customer. Customers can use the link to view and pay the invoice. |
sales_tax | JSON data | An array of sales tax information. This can contain: • type - How the sales tax is calculated. Allowable values are RATE and AMOUNT . (See value , below).• value - The sales tax value. If type is set to RATE , this field contains the sales tax rate, and the system automatically calculates the sales tax amount (amt_tax ) based on the rate. If the type is AMOUNT , this field contains the sales tax amount. |
payment_terms | JSON data | An array of payment terms. This can contain: • type - The payment term type. Allowable values are DAYS and DATE . By default, this field is set to DAYS . (See value , below.) • value - The invoice_due_date will be automatically updated based on this value. If type is set to DATE , this field contains the invoice_due_date formatted as YYYY-MM-DD. If type is DAYS , this field contains the number of days after the invoice date that the payment is due. |
date_invoice | Fixed length, 10 AN, in YYYY-MM-DD format | The invoice date. |
line_items | JSON array | An array of invoice line item details. Possible fields: • quantity - The count of items. • description - A short description of the item.• unit_cost - The cost per unit of the item. |
date_payment | Fixed length, 10 AN, in YYYY-MM-DD format | The invoice payment date. If multiple payments are made for this invoice, this field has the latest payment date. |
date_due | Fixed length, 10 AN, in YYYY-MM-DD format | The invoice due date. This date is automatically calculated based on the payment_terms . |
date_last_view | Fixed length, 10 AN, in YYYY-MM-DD format | The date the invoice was last viewed by the customer. |
date_sent | Fixed length, 10 AN, in YYYY-MM-DD format | The date the invoice was first sent to the customer. This is the date the invoice status was set to OUTSTANDING . |
date_notice | Fixed length, 10 AN, in YYYY-MM-DD format | The date a reminder or overdue notice will be sent. A reminder notice is sent before the due date. Overdue notices are sent after the due date. The reminder and overdue intervals can be configured on the Invoice settings page in Maast Manager. |
db_timestamp | Fixed length, 28 AN, ISO date timestamp in YYYY-MM-ddTHH:mm:ss.SSS-ZZZZ format | The invoice creation time stamp. |
See the code below for a sample invoice
-type webhook payload:
{
"webhook_id": 228,
"db_timestamp": "20180319132053",
"event": "invoice_paid",
"is_test": true,
"data": {
"line_items": [
{
"quantity": 8,
"amt_total": 64,
"unit_cost": "8",
"description": "Trident"
}
],
"invoice_id": 388,
"invoice_number": "aptest6788",
"customer_id": "1234TEST",
"amt_tran": 64.64,
"amt_tax": 0.64,
"amt_sub_total": 64.0,
"date_due": "2022-03-20",
"status": "OUTSTANDING",
"footer_note": "Thank you for your business!",
"payment_terms_note": "",
"merchant_id": 971000010003,
"amt_paid": 0.0,
"amt_balance": 64.64,
"tran_currency": "840",
"db_timestamp": "2022-03-19 13:20:27",
"profile_id": "97100001000300010840",
"date_invoice": "2022-03-19",
"date_payment": "",
"checkout_id": "f774f3812bb211e891060a3416b2e023",
"date_last_view": "2022-03-19",
"date_sent": "2022-03-19",
"date_notice": "2022-03-23",
"invoice_link": "https://dev.maast.com/checkout/invoice/f774f3812bb211e891060a3416b2e023",
"billing_contact": {
"zip": "95110",
"city": "",
"zip4": "",
"phone": "3233456789",
"state": "",
"country": "",
"address1": "",
"address2": "",
"firm_name": "",
"last_name": "test",
"first_name": "Albina",
"country_code": "840",
"email_address": "[email protected]"
},
"checkout_settings": {
"email_receipt": true,
"allow_partial_payments": true
},
"from_contact": {
"zip": "90909",
"city": "San mateo",
"zip4": "",
"phone": "7898990002",
"state": "CA",
"country": "",
"address1": "456 Jump street",
"address2": "789",
"firm_name": "Albina Enterprises",
"last_name": "",
"first_name": "",
"country_code": "840",
"email_address": "[email protected]"
},
"payment_terms": {
"type": "DAYS",
"value": "1"
},
"sales_tax": {
"type": "RATE",
"value": "1"
}
}
}
invoice_payment
invoice_payment
The following table shows fields included in the data
object of an invoice_payment
-type payload:
Field Name | Format | Description |
---|---|---|
invoice_id | Variable length, up to 10 N | A unique identifier generated by Maast to identify an invoice. |
checkout_id | Fixed length, 32 AN | A unique identifier generated when a Checkout resource is created. |
invoice_number | Variable length, up to 25 AN | The invoice number generated by the merchant. |
pg_id | Fixed length, 32 AN | A unique identifier generated by the payment gateway for each transaction. |
rcode | Variable length, up to 6 AN | The response code from the Payment Gateway API. Refer to Payment Gateway API Response Codes for valid codes. An rcode value of 000 , 008 , 010 , or 011 indicates an approved request. |
rmsg | Variable length AN | A short text description of the rcode from the Payment Gateway API. |
tran_time | Fixed length, 19AN year, month, day, and time in ISO date-time format (ex: 2022-12-03T10:15:30 ) | The date timestamp when the transaction was submitted. The time is in PST (U.S.). |
card_number | Variable length, up to 16 AN | The masked card number. |
card_id | Fixed length, 32 AN | The tokenized card number. Applicable only if customer_id is sent in the Checkout request. |
amt_tran | Variable length, up to 12,2 N | The transaction amount. |
tran_currency | Fixed length, 3 N | The ISO numeric currency code for the transaction. |
purchase_id | Variable length, up to 25 AN | The purchase identifier (also referred to as the invoice number) included in the request. |
profile_id | Variable length, up to 20 AN | The Payment Gateway profile ID used for billing the customer. |
auth_code | Fixed length, 6 AN | The authorization code returned when the transaction was sent to the card issuer for approval. |
auth_response_desc | Variable length, AN | A short description of the authorization result. |
cvv2_result | Fixed length, 1 AN | If the customer enters their cvv in the Checkout page, the result from the card issuer is returned in this field. |
avs_result | Fixed length, 1 AN | If billing_zip (and optionally the billing_street_addr1 ) are provided in the Checkout request or in the Checkout page, then the result from the card issuer will be returned in this field. |
merchant_id | Variable length, up to 12 N | A unique ID assigned by Maast to a merchant. |
client_ip | Variable length | The IP address of the device making the payment. |
dba_name | Variable length, up to 25 AN | The 'Doing Business As' name associated with the profile. |
customer_id | Variable length, up to 32 AN | A unique ID that identifies a customer in Customer Vault. |
customer | JSON data | The customer information submitted with the transaction. Possible fields: • customer_first_name • customer_last_name • customer_firm_name • customer_email • customer_phone_number • billing_addr1 • billing_addr2 • billing_state • billing_city • billing_zip • billing_country |
duration | Variable length, N | The duration of the gateway request in ms. |
http_status | Fixed length, 3 N | The HTTP status of the payment gateway request. |
http_status_text | Variable length, AN | A short description of the HTTP status. |
See the code below for a sample invoice_payment
-type webhook payload:
{
"webhook_id":209,
"db_timestamp":"20170908100614",
"event":"invoice_payment_success",
"is_test":true,
"data":{
"http_status":200,
"http_status_text":"OK",
"rcode":"000",
"status":"Approved",
"amt_tran":"91.54",
"invoice_id":"223489",
"invoice_number":"Acme3884",
"purchase_id":"Acme3884",
"auth_code":"T59396",
"customer":{
"customer_first_name":"John",
"customer_last_name":"Doe",
"billing_zip":"99099"
},
"cvv2_result":"-",
"avs_result":"Z",
"rmsg":"Approved T59396",
"pg_id":"0512541494b811e7a1dc0a728c0d49c0",
"card_id":"1715d1bf89d311e795d20a728c0d49c0",
"tran_currency":"840",
"currencyAlpha":"USD",
"dba_name":"JOHN - USD",
"card_number":"424242xxxxxx4242",
"customer_id":"johndoe",
"client_ip":"24.6.81.199",
"duration":50,
"tran_time":"2022-09-08T10:06:13.845-0700",
"auth_response_desc":"Approved and completed successfully.",
"merchant_id":999900010999,
"profile_id":"99990001099900010840",
"checkout_id":"fe0ed3af94b711e7b89e0a3416b2e023"
}
}
invoice_email
invoice_email
The following table shows fields included in the data
object of an invoice_email
-type webhook payload:
Field Name | Format | Description |
---|---|---|
invoice_id | Variable length, up to 10 N | A unique number generated by Maast to identify an invoice. |
invoice_number | Variable length, up to 25 AN | The invoice number (also referred to as the purchase identifier) generated by the merchant. |
merchant_id | Variable length, up to 12 N | A unique ID assigned by Maast to a merchant. |
customer_id | Variable length, up to 32 AN | A unique ID that identifies a customer in Customer Vault. |
status | Variable length, up to 16 AN | Status of an invoice. Possible values: • OUTSTANDING - The invoice has been sent to the customer and is not yet completely paid. Once an invoice is sent, only the billing_contact and from_contact can be updated. • PAID - The invoice has been completely paid. Once paid, the invoice is locked and cannot be modified.• CANCELED - Invoice has been canceled. Once canceled, the invoice is locked and cannot be modified. |
category_name | Variable length, up to 16 AN | The type of invoice email. Possible values: • INVOICE - The invoice that the merchant sends to customers. • INVOICE_REMINDER - An invoice reminder or overdue notification that the system sends out automatically. |
send_code | Fixed length, 1 AN | The email client response code. Possible values: • O - Email not sent. The email address may be invalid. • A - Email not sent. The email address has been disabled. • B - Email undeliverable. |
db_timestamp | Fixed length, 28 AN, ISO date timestamp in YYYY-MM-ddTHH:mm:ss.SSS-ZZZZ format | The date timestamp when the invoice was sent. |
recipient | Array | An array of the invoice recipient's email addresses. |
See the code below for a sample invoice_email
-type webhook payload:
{
"webhook_id": 228,
"db_timestamp": "20180315055040",
"event": "invoice_email_undeliverable",
"is_test": true,
"data": {
"invoice_id": 298,
"invoice_number": "SS#0312",
"customer_id": "JBOURNE",
"status": "PAID",
"merchant_id": 971000010123,
"category_name": "INVOICE",
"send_code": "O",
"db_timestamp": "2022-03-15 05:40:17",
"recipient": "[[email protected]"]"
}
}
qp_payment
qp_payment
The following table shows fields included in the data
object of a qp_payment
-type webhook payload:
Field Name | Format | Description |
---|---|---|
pg_id | Fixed length, 32 AN | A unique identifier generated by the payment gateway for each transaction. |
pg_id_linked | Fixed length, 32 AN | The pg_id of the original transaction, applicable only for refund events (qp_manager_refund_success or qp_manager_refund_failure ). |
rcode | Variable length, up to 6 AN | The response code from the Payment Gateway API. Refer to Payment Gateway API Response Codes for valid codes. An rcode value of 000 , 008 , 010 , or 011 indicates an approved request. |
rmsg | Variable length, AN | A short text description of the rcode from the Payment Gateway API. |
tran_time | Variable length, in ISO date-time format (YYYY-MM-DD HH:MM:ss) | The date timestamp of when the transaction was submitted. The time is in PST (U.S.). |
card_number | Variable length, up to 16 AN | The masked card number. |
amt_tran | Variable length, up to 12, 2 N | The transaction amount. |
tran_currency | Fixed length, 3 N | The ISO numeric currency code for the transaction. |
purchase_id | Variable length, up to 25 AN | The purchase identifier (also referred to as the invoice number) included in the request. |
profile_id | Variable length, up to 20 AN | The Maast Payment Gateway profile ID used for billing the customer. |
auth_code | Fixed length, 6 AN | The authorization code returned when the transaction was sent to the card issuer for approval. |
cvv2_result | Fixed length, 1 AN | If the customer enters their cvv in the Checkout page, the result from the card issuer is returned in this field. |
avs_result | Fixed length, 1 AN | If billing_zip (and optionally the billing_street_addr1 ) are provided in the checkout request or in the Checkout page, then the result from the card issuer will be returned in this field. |
merchant_id | Variable length, up to 12 N | A unique ID assigned by Maast to a merchant. |
customer_id | Variable length, up to 32 AN | A unique ID that identifies a customer in Customer Vault. |
http_status | Fixed length, 3 N | The HTTP status of the payment gateway request. |
http_status_text | Variable length AN | A short description of the HTTP status. |
See the code below for a sample qp_payment
-type webhook payload:
{
"webhook_id": 158,
"db_timestamp": "20180523145349",
"event": "qp_manager_sale_success",
"is_test": true,
"data": {
"pg_id": "c631258c5ed311e8bfc30a56f26ad49a",
"rcode": "000",
"rmsg": "Approved T81195",
"tran_time": "2022-05-23T14:53:49.160-0700",
"card_number": "424242xxxxxx4242",
"purchase_id": "QP-1123",
"amt_tran": "1",
"tran_currency": "840",
"profile_id": "97100001012300090840",
"auth_code": "T81195",
"cvv2_result": "-",
"avs_result": "Z",
"merchant_id": "971000010123",
"customer_id": "jbourne",
"http_status": "200"
}
}
application
application
The following table shows fields included in the data
object of an application
-type webhook payload:
Field Name | Format | Description |
---|---|---|
merchant_id | Variable length, up to 16 N | A unique ID assigned by Maast to a merchant. Only APPROVED applications display a merchant_id . |
app_id | Variable length, up to 8 N | A unique identifier generated by Maast for this application. |
app_status | Variable length, up to 12 N | The current status of the application. Possible values: • APPROVED - The application is approved, and the merchant account is ready. • DECLINED - The application has been declined. • CANCELLED - The application has been canceled. |
See the code below for a sample application
-type webhook payload:
{
"webhook_id": 243,
"db_timestamp": "20180830100002",
"event": "application_approved",
"is_test": true,
"data": {
"app_id": 103410,
"app_status": "APPROVED",
"merchant_id": 999000021437
}
}
transactions
transactions
The following table shows fields included in the data
object of a transactions
-type webhook payload:
Field Name | Format | Description |
---|---|---|
transactions | Array | An array of transactions that are closed and whose status has been updated. Refer to the transactions array schema below. |
transactions
array
transactions
arrayThis table shows the fields in the transactions
array of a transactions
-type webhook payload:
Field Name | Format | Description |
---|---|---|
pg_id | Variable length, up to 32 AN | A unique identifier generated by the payment gateway for each transaction. |
merchant_id | Variable length, up to 12 N | A unique ID assigned by Maast to a merchant. |
tran_status | Fixed length, 1 AN | The transaction status. Possible values: • S - Transaction settled. • P - Deposit sent. • N - Transaction settled but will not be funded by Maast. • R - Transaction rejected. |
amt_tran | Variable length, up to 12, 2 N | Transaction amount. |
tran_currency | Fixed length, 3 N | The ISO numeric currency code for the transaction. |
See the code below for a sample transactions
-type webhook payload:
{
"webhook_id": 141,
"db_timestamp": "20180905115418",
"event": "transaction_status_updated",
"is_test": true,
"data": {
"transactions": [
{
"pg_id": "22f7de93f52a11e6a52f0a728c0d49c0",
"tran_status": "S",
"tran_currency": "840",
"amt_tran": "9.00",
"purchase_id": "20170217_MAROON9"
},
{
"pg_id": "095e28bbf56011e6a52f0a728c0d49c0",
"tran_status": "S",
"tran_currency": "124",
"amt_tran": "-2.00"
}
]
}
}
ach_case
ach_case
The following table shows fields included in the data
object of an ach_case
-type webhook payload:
Field Name | Format | Description |
---|---|---|
pg_id | Variable length, up to 32 AN | A unique identifier generated by the payment gateway for each transaction. |
rec_id | Variable length up to 18 N | The rec_id is the control number for an ACH case. One transaction could receive multiple ACH cases. |
data_type | Fixed length, 1 AN | Type of ACH return. Possible values: • L - Late return • N - Notification of change (NOC) |
new_tr_number | Fixed length, 9 N | New bank transit/routing number. This optional field is present only if data_type is NOC and there are changes to the bank transit/routing number. |
new_type_id | Fixed length, 1 A | New bank account type. This optional field is present only if data_type is NOC and there are changes to the bank account type. Possible values: • C - Personal checking account • S - Personal savings account • K - Business checking account• V - Business savings account |
new_cardholder_name | Variable length, up to 64 AN | The new account holder's name. This optional field is present only if data_type is N and there are changes to the account holder's name. |
new_card_number | Fixed length, 16 AN | The masked account number. This is present only if data_type is N and there is an account number change. |
merchant_id | Variable length, up to 12 N | A unique ID assigned by Maast to a merchant. |
See the code below for a sample ach_case
-type webhook payload:
{
"webhook_id":209,
"db_timestamp":"20170908100614",
"event":"ach_case",
"is_test":true,
"data":{
"pg_id":"0512541494b811e7a1dc0a728c0d49c0",
"merchant_id":999900010999,
"new_tr_number":"123456788",
"new_type_id":"C",
"new_cardholder_name":"John Doe",
"rec_id":"123456788",
"data_type":"N",
}
}
Webhook Statuses
The following table contains all possible webhook statuses:
Status | Description |
---|---|
Active | The webhook is active. |
Disabled | The user has disabled the webhook. |
Suspended | The system has suspended the webhook. The system suspends a webhook when it is unable to post a request for 48 hours. |
NOTE: While a webhook is disabled or suspended, no new requests will be posted or added for it. If there are existing requests for this webhook in the request queue, they will be held.
Updated 11 months ago