Status Webhook

The MoneyGram Partner Listener Service (PLS) enables Account Deposit partners to asynchronously notify MoneyGram of transaction status changes over a JSON REST interface. All status updates are initiated by authorised partners using the PUT Transaction Status operation. The interface is idempotent — partners may safely retry the same payload until MoneyGram acknowledges receipt.

Supported status updates

PEN

Pending

Transaction acknowledged; processing in progress.

REC

Received

Funds successfully credited to the beneficiary.

REJ

Rejected

Transaction could not be fulfilled; marked as failure.

RTY

Retry

Transaction can be resent by MoneyGram.

Update flow

1 Initiate status update Partner sends PUT request with Basic Auth credentials.

2 Validate credentials PLS authenticates the request against the MGI backend. Failure → 401; partner contacts MGI.

3 updateStatus operation Backend applies the status. System exception → re-initiate later. Business exception → contact MGI.

4 Success response 200 OK returned; no further polling required.

Endpoint hosts

Environment	Base URL
UAT	`https://extadpartner.moneygram.com/partnerconnect/v1`
Production	`https://adpartner.moneygram.com/partnerconnect/v1` (confirmed during onboarding)

PUT /transactions/{mgiTransactionId}/status

Security configuration

IP whitelisting — at the firewall level, MoneyGram whitelists partner IPs and allows SSL connections (TLS 1.2+) only from approved addresses.
HTTP Basic Authentication — MoneyGram IT Security assigns a unique username and password per partner and per environment (UAT vs Production). The partner presents these credentials in the Authorization header on every request; the Partner Listener Service authenticates them.
Credential management — credentials are issued during partner onboarding, must be stored securely, and must never be hardcoded.

HTTP headers

Header	Required	Value
`Content-Type`	Required	`application/json`
`Authorization`	Required	`Basic base64(username:password)`
`X-MG-ClientRequestId`	Recommended	UUID (max 64 chars). Must be unique within a single session for unique requests.
`Host`	Required	As per environment noted above.

Path parameters

Parameter	Required	Type	Description
`mgiTransactionId`	Required	String (8–20 digits)	MoneyGram transaction tracking ID passed in the transaction load API. Pattern: `^\d{8,20}$`.

Request fields

Field	Required	Type	Description
`partnerTransactionId`	Required	String (1–50)	Partner's unique transaction identifier. If the partner uses the MoneyGram transaction ID, pass the same value here. Pattern: `^[A-Za-z0-9_\-]{1,50}$`. Also serves as the idempotency key.
`reasonCode`	Required	String (5 digits)	Reason code for the transaction status. Must be a valid 5-digit code from the published catalog — see Partner reason codes. Invalid codes return `400` with `errorCode 9300`.
`partnerReasonMessage`	Optional	String (max 500)	Partner's free-text reason message or description, for audit and logging.

Example request

PUT /transactions/{mgiTransactionId}/status application/json

{
  "partnerTransactionId": "PTX-2026-001234",
  "reasonCode": "01504",
  "partnerReasonMessage": "Transaction completed successfully"
}

cURL shell

curl -X 'PUT' \
  'https://extadpartner.moneygram.com/partnerconnect/v1/transactions/12345678901234/status' \
  -H 'accept: application/json' \
  -H 'Authorization: Basic dGVzdDp0ZXN0' \
  -H 'Content-Type: application/json' \
  -H 'X-MG-ClientRequestId: 8f14e45f-ceea-467a-a3a6-4e6b4d3a9c2f' \
  -d '{
    "partnerTransactionId": "PTX-2026-001234",
    "reasonCode": "01504",
    "partnerReasonMessage": "Transaction completed successfully"
  }'

Partner reason codes

Reason codes are grouped by category: 012xx pending, 014xx rejected, 015xx received, 016xx retry. Treat the catalog as authoritative — additional codes may be added over time, and partners should handle unknown codes gracefully.

PEN — Pending

Code	Scenario
`01200`	Acknowledged — delivery in process
`01204`	Verify customer information
`01205`	Other pending
`01213`	Acknowledged — pending wallet setup
`01214`	Acknowledged — pending receiver confirmation
`01215`	Communication error with partner
`01216`	Pending KYC process

REC — Received

Code	Scenario
`01504`	Received — confirmed deposited / delivered
`01505`	Received — assumed deposited by partner

REJ — Rejected

Rejection codes mark the transaction as a failure.

Code	Scenario
`01401`	Account closed
`01402`	Account unavailable for deposit — unspecified reason
`01404`	Invalid account number
`01406`	Account no longer active
`01410`	Invalid transaction amount
`01424`	Invalid phone number
`01425`	Invalid email address
`01426`	Account ineligible — blocked account
`01427`	Account ineligible — business account
`01428`	Account ineligible — minor account
`01429`	Account ineligible — joint account
`01430`	Account ineligible — restricted account
`01431`	Mobile wallet not set up
`01432`	Invalid / insufficient ID
`01433`	Transaction declined by receiver
`01434`	Transaction expired
`01436`	Limit exceeded
`01437`	Regulatory reason
`01438`	Commercial account
`01439`	Account name mismatch
`01440`	Account exceeds monthly accumulated amount
`01441`	Account exceeds weekly accumulated amount
`01442`	Account exceeds daily accumulated amount
`01443`	Transaction amount over the limit
`01444`	Invalid receiver ID
`01445`	Transaction payment reversed
`01446`	Invalid account currency
`01447`	Technical reject by receiving payment processor
`01448`	Technical reject by receive country payment switch

RTY — Retry

Code	Scenario
`01601`	Submit retry
`01608`	Retry technical reject
`01609`	Retry prefund reject

Responses

Every response — success or error — includes a server-generated requestId correlation ID. Quote this value when contacting support. All timestamps are UTC (ISO 8601 with Z suffix).

200 OK StatusUpdateResponse

Transaction status updated successfully application/json

{
  "status": "SUCCESS",
  "message": "Transaction status updated successfully",
  "mgiTransactionId": "12345678901234",
  "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "timestamp": "2026-04-23T10:30:00Z"
}