Transaction Events
Overview
The 'Transaction Events' subscription enables real-time notification updates if there is a change in the status or sub-status of a transaction. This lets your business and customer know what’s happening with the transaction and any action required.
The transactionStatus
field returns the overall top-level status of a transaction. The transactionSubStatus
is an array that will return further details about the transaction and any action needed from the customer. Both the transactionStatus
and subStatus
return values that are consumer facing and can be displalyed in the application UI.
Transaction Status
A transaction may have one of the following transaction statuses:
Transaction Status | Description |
---|---|
UNFUNDED | Transaction is staged. The customer needs to go to MoneyGram store to fund and commit the transaction |
SENT | Transaction has been committed, funded and accepted to MoneyGram |
AVAILABLE | Transaction is available for cash pick up |
IN TRANSIT | Transaction funds are moving to Bank Account or Wallet |
RECEIVED | Transaction has been paid out to receiver |
DELIVERED | Transaction funds have been delivered to a bank account, wallet or biller |
PROCESSING | This transaction is being reviewed internally by MoneyGram |
REJECTED | Transaction is rejected by MoneyGram and can only be refunded back to the sender |
REFUNDED | Transaction has been refunded back to send customer |
CLOSED | Transaction has been closed internally by MoneyGram and is in contact with agent/partner/customer |
Transaction Sub-Status
A transaction may have one or more of the following Sub-Statuses:
Transaction Status | Transaction Sub-Status | Sub-Status Description | Target Customer |
---|---|---|---|
PROCESSING | HOLD - DATA COLLECTION NEEDED | Transaction has been placed on HOLD and further compliance data needs to be collected from the customer | Sender or Receiver |
PROCESSING | HOLD - DOCUMENT COLLECTION NEEDED | Transaction has been placed on HOLD and further transactional documentation needs to be collected from the customer | Sender or Receiver |
PROCESSING | HOLD - INTERVIEW NEEDED | Transaction has been placed on HOLD and MoneyGram needs to interview the customer | Sender or Receiver |
PROCESSING | HOLD - INTERNAL REVIEW | This transaction is being reviewed internally by MoneyGram. No action to be taken from partner at this time. | null |
PROCESSING | PARTNER HOLD | The partner has placed the transaction on HOLD. MoneyGram is waiting for instruction from the Partner to release the transaction | null |
REJECTED | SENDER REJECT | Transaction is rejected by MoneyGram and can only be refunded back to the sender | null |
REJECTED | RECEIVER REJECT | Transaction is rejected by MoneyGram and can only be refunded back to the sender | null |
CLOSED | OPTION-O REFUND | Transaction has closed internally by MoneyGram and a new Reference Number has been issued to send customer | null |
Handling "PROCESSING" Status
In some cases MoneyGram will place a transaction in "PROCESSING" status due to a compliance hold. In these hold scenarios we may require further data, documentation or an interview from the customer. The sub-status
is useful to understand the type of hold in placed, the impacted customer and the action needed to release the transaction from the hold.
NOTE: In some edge cases there might be two types of holds placed on a transaction. In this scenario the
transactionSubStatus
returns a array ofsubStatus
and the action to release the each hold.
To help walk you through PROCESSING status, we have put together the below tutorial:
Transaction Status Flow
The below state machine represents the transitions of transactionStatus
and the events/actions applied:


Signature Verification Code Example
const crypto = require('crypto');
const buffer = require('buffer');
const publicKey = "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0Dm7LFleQyaXakYdNOvCv2Irm2ufOcncek0Q4J+MtzmEYvdlfhx5Sm206s2Z5l0/+6YyA3tFljRNCFar3lm96o/S6IFNo0xOsCy+Il7EzQNl4S7kojqnOGfgMgUBC/qxf0S7zkh7y0St8G3OpcjYg7Ff7PAFXmcgjk22F1lUeOqy+zyP2dRJ+NEKZrcHJhbFheB0dPH++e+1foHSfhz+I+Pt9DDaESJasJptZGo0Ww3U+KkPmrDriOLbvpdE4r7MKzeQfGa7SMx4VzhtWFa98/6V6MO29ZjkegejHBZsCekA/1NU0gAQhQnxuYsgdCn/9LogrWqUS8Tl44K2yPYCsQIDAQAB";
function verify(signatureHeader, unixTimeInSeconds, destinationHost, body){
// Using Hashing Algorithm
const algorithm = "RSA-SHA256";
// Converting string to buffer
const data = Buffer.from(unixTimeInSeconds+"."+destinationHost+"."+body);
const pub = "-----BEGIN PUBLIC KEY-----\n" + publicKey + "\n-----END PUBLIC KEY-----";
// Verifying signature using crypto.verify() function
const isVerified = crypto.verify(algorithm, data, pub, Buffer.from(signatureHeader, "base64"));
// Printing the result
console.log('Is signature verified: '+isVerified);
return isVerified;
}
// Test
const signatureHeader = "wGIPt8Wt16Vl9yMGEBO7ByZA8zkJzuUjaE/2G5NDez8SEGDnX5VdxoSqdTN8N6/LaX2jV/9o25fWppJoxBBK6g/SHKFAo/Ib8uOnNYWeyjdrhZ4RVBCmB+IcdKuSXZHWFwtCLZM0R6PitE4HkXJrooe5KY93VzR8migLd7bw4ANAFwhYLBn6JmfnKO78A1hqpsUsq1T28Aph+6mYPx2q4SrfpkKK/YAoZrCpZMR/nzZMYevJhupy4i7B2L5axv94gm6YKZkaTAjCJWtXp2Kkv+UQ4Dpo7I+DkxWObg8dCy1JfzLlh57XswSdyiombhizHI89MgW4j1IWHZ4EZWxc6Q==";
const unixTimeInSeconds = 1679925945;
const destinationHost = "sandbox.com";
const body = "{\"eventId\":\"740708201679925945014500444747\",\"eventDate\":\"2023-03-27T14:05:44.884026\",\"subscriptionId\":\"15efa8b3-bb09-4fe9-a295-55fc323cf3ee\",\"subscriptionType\":\"TRANSACTION_STATUS_EVENT\",\"eventPayload\":{\"transactionId\":\"3009143868\",\"agentPartnerId\":\"74097706\",\"referenceNumber\":\"40196296\",\"transactionSendDate\":\"2023-03-27T14:05:41.007\",\"transactionStatusDate\":\"2023-03-27T14:05:41.007\",\"transactionStatus\":\"SENT\",\"transactionSubStatus\":[]}}";
verify(signatureHeader, unixTimeInSeconds, destinationHost, body);
Request Notification & Response Examples
{
"eventId": "740708201679925945014500444747",
"eventDate": "2023-03-27T14:05:44.884026",
"subscriptionId": "001cc295-4a40-413d-8639-7469a31001c4",
"subscriptionType": "TRANSACTION_STATUS_EVENT",
"eventPayload": {
"transactionId": "3008940179",
"agentPartnerId": "30150519",
"referenceNumber": "123456789",
"transactionSendDate": "2023-03-27T14:05:41.007",
"transactionStatusDate": "2023-03-27T14:05:41.007",
"expectedPayoutDate": "2023-03-29",
"transactionStatus": "SENT",
"transactionSubStatus": []
}
}
{
"eventId": "440855281658266796280184232452",
"eventDate": "2022-07-19T21:39:56.280849",
"subscriptionId": "001cc295-4a40-413d-8639-7469a31001c4",
"subscriptionType": "TRANSACTION_STATUS_EVENT",
"eventPayload": {
"transactionId": "3008940179",
"agentPartnerId": "30150519",
"referenceNumber": "12345678",
"partnerTransactionId": "35698THD74556312THD",
"transactionSendDate": "2022-07-19T21:39:52.039",
"transactionStatusDate": "2022-07-19T21:39:52.039",
"expectedPayoutDate": "2023-03-29",
"transactionStatus": "SENT",
"transactionSubStatus": [
{
"subStatus": "HOLD – DATA COLLECTION NEEDED",
"message": "MoneyGram needs to collect further data from the Send Customer",
"targetCustomer": "Sender",
"dataToCollect": [
{
"code": "3002",
"dataCollection": "DOB"
},
{
"code": "3003 ",
"dataCollection": "Country of Birth"
}
]
}
]
}
}
{
"eventId": "726237581734122683219764906193",
"eventDate": "2024-12-13T20:44:43.118328",
"subscriptionId": "922503ca-c27f-4563-93f3-f9b6cc36b7ab",
"subscriptionType": "TRANSACTION_STATUS_EVENT",
"eventPayload": {
"transactionId": "3008940179",
"agentPartnerId": "72623761",
"referenceNumber": "123456789",
"transactionSendDate": "2024-12-13T20:44:40.574",
"transactionStatusDate": "2024-12-13T20:44:43.118328",
"expectedPayoutDate": "2024-12-13",
"transactionStatus": "AVAILABLE",
"transactionSubStatus": [],
"sendAmount": "100.00",
"sendFee": "1.00",
"sendCurrency": "USD",
"receiveAmount": "100.00",
"receiveCurrency": "USD",
"fxRate": "1.0000",
"sender": {
"firstName": "Sally",
"middleName": "",
"lastName": "Smith",
"secondLastName": "",
"senderNationality": "",
"address": {
"line1": "100 Main St",
"line2": "",
"line3": "",
"city": "Dallas",
"province": "TX",
"countryCode": "USA"
},
"dateOfBirth": "1980-01-01",
"personalId1Type": "DRV",
"personalId1Number": "123456789"
},
"receiver": {
"firstName": "Joe",
"middleName": "",
"lastName": "Smith",
"secondLastName": "",
"phoneNumber": "+1 555-123-1234"
}
}
}
{
"eventId": "726237581734122683219764906193",
"eventDate": "2024-12-13T20:44:43.118328",
"subscriptionId": "922503ca-c27f-4563-93f3-f9b6cc36b7ab",
"subscriptionType": "TRANSACTION_STATUS_EVENT",
"eventPayload": {
"transactionId": "3008940179",
"agentPartnerId": "72623761",
"referenceNumber": "123456789",
"transactionSendDate": "2024-12-13T20:44:40.574",
"transactionStatusDate": "2024-12-13T20:44:43.118328",
"expectedPayoutDate": "2024-12-13",
"transactionStatus": "AVAILABLE",
"transactionSubStatus": [],
"sendAmount": "100.00",
"sendFee": "1.00",
"sendCurrency": "USD",
"receiveAmount": "100.00",
"receiveCurrency": "USD",
"fxRate": "1.0000",
"sender": {
"firstName": "Sally",
"middleName": "",
"lastName": "Smith",
"secondLastName": "",
},
"receiver": {
"firstName": "Joe",
"middleName": "",
"lastName": "Smith",
"secondLastName": "",
"phoneNumber": "+1 555-123-1234"
}
}
}
200 OK
Response body rules
When the request is successfully received, the response must only include the 200 OK HTTP status code. Do not include any additional information in the response body. Including extra information in the response body will lead to the response being rejected, and MoneyGram will continue to resend the same request.
Learn more: Webhook Delivery
Request Fields
Field | Type | Required/ Optional | Description |
---|---|---|---|
eventId | String | Required | Unique ID per message (UUID) |
eventDate | Date-Time | Required | UTC date-time format when the message is sent. |
subscriptionId | String | Required | Unique ID of partner subscription request. This will be the same for all requests to a specific partner |
subscriptionType | String | Required | Type of subscription -TRANSACTION_STATUS_EVENT |
eventPayload.transactionId | String | Optional | Unique ID of the transaction resource created by MoneyGram during the transfer of funds |
eventPayload.agentPartnerId | String | Required | MoneyGram sending agent ID |
eventPayload.referenceNumber | String | Required | Reference number generated by MoneyGram for a committed transaction. This reference number will be reused several months after the transaction has been closed/received. This number is not unique over time. |
eventPayload.transactionSendDate | String | Required | UTC date-time format of the original Send transaction |
eventPayload.transactionStatusDate | Date-Time | Required | UTC date-time format of when the status change occurred In the event of downtime where notification may be delivered out of sequence, the transactionSubStatus should be used to sort the events in date order. |
eventPayload.expectedPayoutDate | Date | Required | Expected payout date. If transaction is placed on hold and released with a status of available this date will be re-calculated to the new expected payout date. |
eventPayload.transactionStatus | String | Required | High-level status of the transaction The following transaction status change will be published to the partner: Status & Sub_Status: Mapping & Definition |
eventPayload.transactionSubStatus.subStatus | String | Optional | Detailed sub-statutes explaining what’s happening with the transaction resource. A sub-status is only returned when further detail or customer action is need. The following transaction sub_status change will be published to the partner: Status & Sub_Status: Mapping & Definition |
eventPayload.transactionSubStatus.message | String | Optional | Description of what data or document is needed from the targetCustomer in order to release the transaction |
eventPayload.transactionSubStatus.targetCustomer | String | Optional | When transaction is in PROCESSING status and additional information is needed, this identifies if additional information is needed. Valid values are from the Sender or Receiver. |
eventPayload.transactionSubStatus.dataToCollect.code | String | Optional | Unique code to identify the data or document to collect. See Data Collection Code column in the transactionSubSatus field |
eventPayload.transactionSubStatus.dataToCollect.dataCollection | String | Optional | The data or document to collect from the customer. |
eventPayload.sendAmount | String | Optional | Transaction amount excluding fees and exchange rate. |
eventPayload.sendFee | String | Optional | Fee Amount applied to the transaction sendAmount (ISO alpha-3 code) |
eventPayload.sendCurrency | String | Optional | The sendAmount currency code (ISO alpha-3 code) |
eventPayload.receiveAmount | String | Optional | Transaction's receive amount excluding fees and exchange rate. |
eventPayload.receiveCurrency | String | Optional | The receiveAmount currency code (ISO alpha-3 code) |
eventPayload.fxRate | String | Optional | Fx Rate applied to transaction |
eventPayload.sender.firstName | String | Optional | Sender First Name |
eventPayload.sender.middleName | String | Optional | Sender Middle Name (if applicable) |
eventPayload.sender.lastName | String | Optional | Sender Last Name |
eventPayload.sender.secondLastName | String | Optional | Sender Second Last Name (if applicable) |
eventPayload.sender.senderNationality | String | Optional | Country of citizenship (ISO alpha-3 code) |
eventPayload.sender.address.line1 | String | Optional | Residence address line 1 |
eventPayload.sender.address.line2 | String | Optional | Residence address line 2 |
eventPayload.sender.address.line3 | String | Optional | Residence address line 3 |
eventPayload.sender.address.city | String | Optional | City of residence |
eventPayload.sender.address.province | String | Optional | State/province of residence |
eventPayload.sender.address.countryCode | String | Optional | Country of residence (ISO Alpha-3 Code) |
eventPayload.sender.dateOfBirth | String | Optional | Date of birth (YYYY-MM-DD) |
eventPayload.sender.personalId1Type | String | Optional | Type of identification document NOTE: For a full list of accepted Identification documents by country. see Reference Data Enumerations endpoint |
eventPayload.sender.personalId1Number | String | Optional | Identification document number |
eventPayload.receiver.firstName | String | Optional | Receiver First Name |
eventPayload.receiver.middleName | String | Optional | Receiver Middle Name (if applicable)) |
eventPayload.receiver.lastName | String | Optional | Receiver Last Name |
eventPayload.receiver.secondLastName | String | Optional | Receiver Second Last Name (if applicable) |
eventPayload.receiver.phoneNumber | String | Optional | Country dial code + Phone number |
Response
200 OK HTTP status from the Webhook request
Updated 2 months ago