Bill Payment Events

Overview

The 'Bill Payment Events' subscription enables real-time notification updates if there is a change in the status or sub-status of a bill pay 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 displayed in the application UI.

Transaction Status

A transaction may have one of the following transaction statuses:

Transaction Status	Description
SENT	Transaction has been committed, funded and accepted to MoneyGram
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
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 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:

Cash Pickup
Account Deposit

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\":\"BILL_PAYMENT_STATUS_EVENT\",\"eventPayload\":{\"transactionId\":\"3009143868\",\"partnerTransactionId\":[],\"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": "726237581734122683219764906193",
    "eventDate": "2024-12-13T20:44:43.118328",
    "subscriptionId": "922503ca-c27f-4563-93f3-f9b6cc36b7ab",
    "subscriptionType": "BILL_PAYMENT_STATUS_EVENT",
    "eventPayload": {
        "transactionId": "3008940179",
        "agentPartnerId": "72623761",
        "mainOfficeId": "12345678",
	"referenceNumber": "123456789",
        "transactionSendDate": "2024-12-13T20:44:40.574",
        "transactionStatusDate": "2024-12-13T20:44:43.118328",
        "expectedPayoutDate": "2024-12-13",
        "transactionStatus": "DELIVERED",
        "transactionSubStatus": [],
        "sendAmount": "100.00",
        "sendFee": "1.00",
        "sendCurrency": "USD",
        "receiveAmount": "100.00",
        "receiveCurrency": "USD",
        "fxRate": "1.0000",
        "sender": {
            "firstName": "Sally",
            "middleName": "",
            "lastName":"Smith",
            "secondLastName": "",
            "phoneNumber": "+1 555-123-1234",
        },
        "payee": {
            "billerName": "aaa",
            "beneficiary":{
                "firstName": "Smith",
                "middleName": "",
                "lastName": "Smith",
	        "secondLastName": "",
        }
}

{
    "eventId": "726237581734122683219764906193",
    "eventDate": "2024-12-13T20:44:43.118328",
    "subscriptionId": "922503ca-c27f-4563-93f3-f9b6cc36b7ab",
    "subscriptionType": "BILL_PAYMENT_STATUS_EVENT",
    "eventPayload": {
        "transactionId": "3008940179",
        "agentPartnerId": "72623761",
        "mainOfficeId": "12345678",
	"referenceNumber": "123456789",
        "transactionSendDate": "2024-12-13T20:44:40.574",
        "transactionStatusDate": "2024-12-13T20:44:43.118328",
        "expectedPayoutDate": "2024-12-13",
        "transactionStatus": "DELIVERED TO BILLER",
        "transactionSubStatus": "Please call 1-800-123-4567 or visit www.paymybills.com for more information.",
        "sendAmount": "100.00",
        "sendFee": "1.00",
        "sendCurrency": "USD",
        "receiveAmount": "100.00",
        "receiveCurrency": "USD",
        "fxRate": "1.0000",
        "sender": {
            "firstName": "Sally",
            "middleName": "",
            "lastName":"Smith",
            "secondLastName": "",
            "phoneNumber": "+1 555-123-1234",
        },
        "payee": {
            "billerName": "PayMyBill",
            "beneficiary":{
                "firstName": "",
                "middleName": "",
                "lastName": "",
	        "secondLastName": "",
        }
}

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.partnerTransactionId`	String	Optional	Partner’s unique session identifier
`eventPayload.agentPartnerId`	String	Required	MoneyGram sending agent ID
`eventPayLoad.mainOfficeID`	String	Required	MoneyGram sending Main Office 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.phoneNumber`	String	Optional	Country dial code + Phone number
`payee.billerName`	String	Optional	Biller Name
`payee.beneficiary.firsName`	String	Optional	Beneficiary First Name (if applicable)
`payee.beneficiary.middleName`	String	Optional	Beneficiary Middle Name (if applicable)
`payee.beneficiary.lastName`	String	Optional	Beneficiary Last Name (if applicable)
`payee.beneficiary.secondLastName`	String	Optional	Beneficiary Second Last Name (if applicable)

Response

200 OK HTTP status from the Webhook request

See Response body rules