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 transactionStatusand 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 StatusDescription
UNFUNDEDTransaction is staged. The customer needs to go to MoneyGram store to fund and commit the transaction
SENTTransaction has been committed, funded and accepted to MoneyGram
AVAILABLETransaction is available for cash pick up
IN TRANSITTransaction funds are moving to Bank Account or Wallet
RECEIVEDTransaction has been paid out to receiver
DELIVEREDTransaction funds have been delivered to a bank account, wallet or biller
PROCESSINGThis transaction is being reviewed internally by MoneyGram
REJECTEDTransaction is rejected by MoneyGram and can only be refunded back to the sender
REFUNDEDTransaction has been refunded back to send customer
CLOSEDTransaction 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 StatusTransaction Sub-StatusSub-Status DescriptionTarget Customer
PROCESSINGHOLD - DATA COLLECTION NEEDEDTransaction has been placed on HOLD and further compliance data needs to be collected from the customerSender or Receiver
PROCESSINGHOLD - DOCUMENT COLLECTION NEEDEDTransaction has been placed on HOLD and further transactional documentation needs to be collected from the customerSender or Receiver
PROCESSINGHOLD - INTERVIEW NEEDEDTransaction has been placed on HOLD and MoneyGram needs to interview the customerSender or Receiver
PROCESSINGHOLD - INTERNAL REVIEWThis transaction is being reviewed internally by MoneyGram. No action to be taken from partner at this time.null
PROCESSINGPARTNER HOLDThe partner has placed the transaction on HOLD. MoneyGram is waiting for instruction from the Partner to release the transactionnull
REJECTEDSENDER REJECTTransaction is rejected by MoneyGram and can only be refunded back to the sendernull
REJECTEDRECEIVER REJECTTransaction is rejected by MoneyGram and can only be refunded back to the sendernull
CLOSEDOPTION-O REFUNDTransaction has closed internally by MoneyGram and a new Reference Number has been issued to send customernull



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 of subStatus 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


FieldTypeRequired/
Optional
Description
eventIdStringRequiredUnique ID per message (UUID)
eventDateDate-TimeRequiredUTC date-time format when the message is sent.
subscriptionIdStringRequiredUnique ID of partner subscription request. This will be the same for all requests to a specific partner
subscriptionTypeStringRequiredType of subscription
-TRANSACTION_STATUS_EVENT
eventPayload.transactionIdStringOptionalUnique ID of the transaction resource created by MoneyGram during the transfer of funds
eventPayload.agentPartnerIdStringRequiredMoneyGram sending agent ID
eventPayload.referenceNumberStringRequiredReference 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.transactionSendDateStringRequiredUTC date-time format of the original Send transaction
eventPayload.transactionStatusDateDate-TimeRequiredUTC 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.expectedPayoutDateDateRequiredExpected 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.transactionStatusStringRequiredHigh-level status of the transaction
The following transaction status change will be published to the partner: Status & Sub_Status: Mapping & Definition
eventPayload.transactionSubStatus.subStatusStringOptionalDetailed 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.messageStringOptionalDescription of what data or document is needed from the targetCustomer in order to release the transaction
eventPayload.transactionSubStatus.targetCustomerStringOptionalWhen 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.codeStringOptionalUnique code to identify the data or document to collect. See Data Collection Code column in the transactionSubSatus field
eventPayload.transactionSubStatus.dataToCollect.dataCollectionStringOptionalThe data or document to collect from the customer.
eventPayload.sendAmountStringOptionalTransaction amount excluding fees and exchange rate.
eventPayload.sendFeeStringOptionalFee Amount applied to the transaction sendAmount (ISO alpha-3 code)
eventPayload.sendCurrencyStringOptionalThe sendAmount currency code (ISO alpha-3 code)
eventPayload.receiveAmountStringOptionalTransaction's receive amount excluding fees and exchange rate.
eventPayload.receiveCurrencyStringOptionalThe receiveAmount currency code (ISO alpha-3 code)
eventPayload.fxRateStringOptionalFx Rate applied to transaction
eventPayload.sender.firstNameStringOptionalSender First Name
eventPayload.sender.middleNameStringOptionalSender Middle Name (if applicable)
eventPayload.sender.lastNameStringOptionalSender Last Name
eventPayload.sender.secondLastNameStringOptionalSender Second Last Name (if applicable)
eventPayload.sender.senderNationalityStringOptionalCountry of citizenship (ISO alpha-3 code)
eventPayload.sender.address.line1StringOptionalResidence address line 1
eventPayload.sender.address.line2StringOptionalResidence address line 2
eventPayload.sender.address.line3StringOptionalResidence address line 3
eventPayload.sender.address.cityStringOptionalCity of residence
eventPayload.sender.address.provinceStringOptionalState/province of residence
eventPayload.sender.address.countryCodeStringOptionalCountry of residence (ISO Alpha-3 Code)
eventPayload.sender.dateOfBirthStringOptionalDate of birth (YYYY-MM-DD)
eventPayload.sender.personalId1TypeStringOptionalType of identification document

NOTE: For a full list of accepted Identification documents by country. see Reference Data Enumerations endpoint
eventPayload.sender.personalId1NumberStringOptionalIdentification document number
eventPayload.receiver.firstNameStringOptionalReceiver First Name
eventPayload.receiver.middleNameStringOptionalReceiver Middle Name (if applicable))
eventPayload.receiver.lastNameStringOptionalReceiver Last Name
eventPayload.receiver.secondLastNameStringOptionalReceiver Second Last Name (if applicable)
eventPayload.receiver.phoneNumberStringOptionalCountry dial code + Phone number

Response

200 OK HTTP status from the Webhook request

See Response body rules