Reference

Transaction status & webhooks

Widget events, status polling, and MoneyGram status webhooks for cash-in and cash-out (custodial and non-custodial).

Status webhooksStatus pollingWidget events

Transaction status & webhooks

How partners learn when a Ramps transaction moves forward: widget events, status polling, and MoneyGram status webhooks. These mechanisms apply to all flows (cash-in and cash-out, custodial and non-custodial).

For custodial cash-in crediting (mapping customerIdentifier to omnibus delivery), see Custodial cash-in.

For the RAMPS_TRANSACTION_CREATED widget event payload, see RAMPS_TRANSACTION_CREATED.

Optional · after validate: Web onTransactionCreated / React Native RAMPS_TRANSACTION_CREATED fires once validate succeeds (before commit). Use it to persist the Ramps transaction id early for view mode and mgiTransactionId for webhook correlation. Full timing, payload, and examples: onTransactionCreated.


Summary

MechanismBest forApplies to
Widget events (RAMPS_TRANSACTION_*)Embedded Web / RN appsWidget integrations
Status polling (GET /status?sync=true)Server-side apps, backup, reconciliationAll flows
MoneyGram status webhooksServer-to-server pushAll flows (same partner URL)
AreaStatus
Widget RAMPS_TRANSACTION_CREATED (includes mgiTransactionId)Implemented
Status polling APIImplemented
Partner webhook URL configuration (partner portal)Implemented
Webhook payload, Stellar (XLM)Live
Webhook payload, other networks (SOL and the rest)Live. Documented below

TEXT
                    ┌─────────────────────────────────────┐                    │      Ramps transaction (any flow)    │                    └─────────────────────────────────────┘                                      │          ┌───────────────────────────┼───────────────────────────┐          ▼                           ▼                           ▼   Widget events              Status polling              Status webhooks   (embedded SDK)             (server-side / backup)      (MoneyGram → partner URL)          │                           │                           │   RAMPS_TRANSACTION_CREATED    GET /status?sync=true      server-to-server POST   RAMPS_TRANSACTION_COMPLETE

They are complementary, but they are not equally suited to every job. Use widget events for the user experience and webhooks as the server-side default: they arrive when something actually changes, rather than asking repeatedly whether it has. Use polling as the fallback where webhooks are not yet enabled, and as the reconciliation path for anything a webhook did not deliver.


1. Widget events

As the user moves through a flow inside the MoneyGram widget, the SDK posts events to the host page (Web) or WebView (React Native). Not every event is terminal. RAMPS_TRANSACTION_CREATED fires as soon as validate succeeds, before commit, so handle it when it arrives rather than waiting for the flow to finish.

EventCash-inCash-out
RAMPS_TRANSACTION_CREATEDAfter validate succeedsAfter validate succeeds
RAMPS_TRANSACTION_COMPLETEDone screen (confirmation code)Done screen (reference number)
RAMPS_TRANSACTION_FAILEDError pathError path
RAMPS_SIGN_TRANSACTIONNot usedNon-custodial only
RAMPS_DEPOSIT_ADDRESSNot usedCustodial only

See RAMPS_TRANSACTION_CREATED for when the creation event fires relative to validate and commit, and for the payload (id, mgiTransactionId, quote economics).

Important: RAMPS_TRANSACTION_COMPLETE fires when the widget reaches the done screen. It does not always mean the transaction is terminal (for cash-in, the user still pays at the store). Use webhooks, or polling where webhooks are not yet enabled, for completed, paid_out, and the other statuses below.


2. Status polling

HTTP
GET /v1/transactions/{id}/status?sync=trueAuthorization: Bearer {sessionToken}

sync=true refreshes from MoneyGram before returning. Use when the user is viewing a receipt or your backend needs authoritative state.

Session token access

A Bearer session token can read status when the transaction was created in that session, or when the session carries the same walletAddress (non-custodial) or customerIdentifier (custodial). A token for a different customer receives 404.

To read status by transaction id from your server without a bound session, call the same route with x-api-key: ramps_sk_*.

Widget view mode uses the session token internally. Create each view-mode session with the same wallet or customer you used when the transaction started. See Partner transaction history.

MoneyGram can leave a temporary exception on for an account that still opens an older transaction from a new session. That exception is status only. Refunds and other writes stay limited to the bound customer.

When to poll

If you embed the widget, start polling once you have the Ramps transaction id from RAMPS_TRANSACTION_CREATED. The widget drives the flow itself, so the steps named in the Start column happen inside it. If you drive the API directly, start at the step named.

FlowStartStop when
Cash-inAfter commitcompleted, failed, or quote_expired
Cash-out (non-custodial)After check-deposit succeedscompleted if you only need to know the cash is ready to collect, paid_out if you need to know it was collected. Always stop on failed, quote_expired, or a terminal refund status (refunded or refund_failed). Do not stop on funds_received.
Cash-out (custodial)After your hot-wallet transfer is confirmedSame as cash-out (non-custodial)

On a cash-out, funds_received means MoneyGram has received the USDC. It does not mean the customer can collect cash yet. The reference number goes live at completed, and paid_out follows once the customer collects the cash at the agent. If you stop at funds_received, you never learn that the pickup became available, and you do not see a later failure or refund.

Cash-in status phases

PhaseTypical status
After validatevalidated / pending_kyc
After commitcommitted
User paid at counterfunds_received
USDC deliveredcompleted
Window expiredquote_expired

Cash-out status phases

PhaseTypical statusNotes
Awaiting consumer commitpending_commitCommit still in flight
Awaiting USDCawaiting_fundsSign & Send window open, or deposit not yet confirmed at MoneyGram
Deposit submitted, confirmation pendingawaiting_fundsCustomer already signed and sent on-chain. The widget shows a confirmation pending state (up to 20 minutes) instead of prompting Sign & Send again. Poll GET /status for depositSubmitted, depositConfirmationRemainingMs, and related fields.
USDC receivedfunds_receivedOn-chain deposit confirmed
Ready for pickupcompleted (cash-out)Pickup code active
Picked uppaid_outCash collected at agent
Refund lifecyclerefund_requested, refund_mgi_pending, refund_mgi_success, refunded, refund_failedCash-out only. Poll until a terminal refund status.

Refunds are cash-out only. Cash-in has no wallet refund path after commit.


What Ramps provides today

Partners configure sandbox and production webhook URLs in the partner portal:

Where to configure: Partner portal → Settings → Integration

When you save a production URL, Ramps registers it with MoneyGram so status events can be delivered to your endpoint. Ramps stores your URL and coordinates registration. MoneyGram's notification service POSTs status events to your URL.

Availability

EnvironmentWhen the webhook URL field is available
SandboxAfter sandbox onboarding is complete
ProductionAfter KYB approval and go-live. Contact your MoneyGram integration contact if production webhooks are not yet enabled.

Production webhook URLs are locked in the partner portal until KYB is approved.

Correlation key: mgiTransactionId

Store mgiTransactionId when the transaction is created:

  • Widget: RAMPS_TRANSACTION_CREATED.mgiTransactionId (after validate succeeds)
  • Server-side: mgiTransactionId from the quote or validate API response when you drive the flow from your backend

When a webhook arrives, look up your pending record by mgiTransactionId, then confirm with GET /v1/transactions/{rampsTransactionId}/status?sync=true before acting.

TEXT
1. At transaction creation: persist { mgiTransactionId, rampsTransactionId, flow, amount, ... }.2. Register your webhook URL in Settings → Integration (sandbox first, then production after go-live).3. On webhook receipt:     a. Look up pending row by mgiTransactionId.     b. GET /v1/transactions/{rampsTransactionId}/status?sync=true.     c. Act on confirmed status (notify user, credit ledger, mark picked up, etc.).

For custodial cash-in crediting, add customerIdentifier from your session to the pending row. See Custodial cash-in · Crediting pattern.

Webhook payload

There are two payload shapes. Which one you receive depends on the network your transaction settles on.

NetworkPayloadstatus vocabulary
Stellar (XLM)Stellar payload. See Differences from the Stellar payload.SEP-24, such as pending_anchor and completed
Every other network (SOL for Solana)Multichain payload, described below.MoneyGram transaction status, such as AVAILABLE and DELIVERED. See Status values.

If you integrate on Solana, or on Stellar and another network, use the network field as the discriminator. Multichain notifications carry it, and Stellar notifications never do. Branch on it rather than on account formats, amounts, or status values.

Shape

The notification is {"transaction": { ... }}, the same as the Stellar payload. Fields with no value are omitted rather than sent as null, so treat most fields as optional.

The request body your endpoint receives is this object itself, with nothing around it. There is no message wrapper and no envelope. Every example below is a complete request body. The signature covers the raw body bytes, so read Verifying the signature before you parse it.

Required fields differ by network, so do not validate both shapes against one schema:

NetworkAlways present
Every network except Stellarid, network, kind, status
Stellar (XLM)id, kind, status. Stellar notifications never carry network.

A shared validator that requires network will reject every valid Stellar notification.

Cash-out (withdrawal) on Solana, when MoneyGram has received the USDC and the cash is ready for pickup:

JSON
{  "transaction": {    "id": "12d6a8c1-9d7b-4dd1-9b4a-7b4169885fad",    "network": "SOL",    "transaction_id": "5wHTKxhvjBfXMyfySQXTsCYqw9YXhMMXVqzjweEvAjxytgHLfLVF3Xs7BS5UT6VTaMWkzYbbwmkDPJn6tzaPqmCM",    "external_transaction_id": "11370841",    "kind": "withdrawal",    "status": "AVAILABLE",    "amount_in": "6.66",    "amount_in_asset": "USDC",    "amount_out": "6.66",    "amount_out_asset": "USD",    "amount_fee": "0.00",    "amount_fee_asset": "USD",    "from": "FiFhQFxvNB8Cxjyuym5ZGYAJHuApdptCEbA6ymhi61FB",    "to": "GAYF33NNNMI2Z6VNRFXQ64D4E4SF77PM46NW3ZUZEEU5X7FCHAZCMHKU",    "started_at": "1970-01-21T12:23:49Z",    "updated_at": "2026-11-09T13:11:37.580000Z"  }}

Cash-in (deposit) after the customer pays at the store. No on-chain transfer exists yet, so transaction_id is absent:

JSON
{  "transaction": {    "id": "5ab9826f-4944-4df6-a6df-03aad8cd471a",    "network": "SOL",    "external_transaction_id": "69908343",    "kind": "deposit",    "status": "IN TRANSIT",    "amount_in": "10.76",    "amount_in_asset": "USD",    "amount_out": "10.76",    "amount_out_asset": "USDC",    "amount_fee": "0.00",    "amount_fee_asset": "USDC",    "from": "AHRNNSgPtvPJqPEC2a5HqbWcYj7uyADw3kJrk8TnvpkA",    "to": "GAYF33NNNMI2Z6VNRFXQ64D4E4SF77PM46NW3ZUZEEU5X7FCHAZCMHKU",    "started_at": "1970-01-21T12:27:12Z",    "updated_at": "2026-11-11T21:34:17.325000Z"  }}

The same cash-out after MoneyGram refunds the sender. transaction_id is now the refund transfer, from and to are swapped, and completed_at is present:

JSON
{  "transaction": {    "id": "12d6a8c1-9d7b-4dd1-9b4a-7b4169885fad",    "network": "SOL",    "transaction_id": "4JYM8Q3yVAwTGU9Eu2JfKkD6G5u9YtuxpbDRFsMV79LdbDhoAEfYtLysKD63JHmvZqRt5Qp8We1tbHxU2VHzaadA",    "external_transaction_id": "11370841",    "kind": "withdrawal",    "status": "REFUNDED",    "amount_in": "6.66",    "amount_in_asset": "USDC",    "amount_out": "6.66",    "amount_out_asset": "USD",    "amount_fee": "0.00",    "amount_fee_asset": "USD",    "from": "GAYF33NNNMI2Z6VNRFXQ64D4E4SF77PM46NW3ZUZEEU5X7FCHAZCMHKU",    "to": "FiFhQFxvNB8Cxjyuym5ZGYAJHuApdptCEbA6ymhi61FB",    "started_at": "1970-01-21T12:23:49Z",    "updated_at": "2026-11-09T15:29:18.587000Z",    "completed_at": "2026-11-09T15:29:18.587000Z"  }}

A transaction that needs additional review carries sub_statuses next to status. Other fields are omitted here:

JSON
{  "transaction": {    "status": "PROCESSING",    "sub_statuses": ["HOLD - DATA COLLECTION NEEDED"]  }}

Fields

FieldNotes
idMoneyGram transaction id. This is the mgiTransactionId you stored at transaction creation, and it is your correlation key.
networkMoneyGram network code: SOL for Solana. Other networks use their own code (ETH, POLY, BASE, ARB, CELO, MONAD). Stellar notifications never carry it, so it is the reliable way to tell the two shapes apart.
transaction_idOn-chain transaction hash or signature. Absent until a settling transfer exists on chain, so expect it to be missing on early events. On a REFUNDED notification it is the refund transfer, not the customer's original transfer.
external_transaction_idMoneyGram reference number. Absent when the transaction has none.
kinddeposit for cash-in, withdrawal for cash-out.
statusMoneyGram transaction status. See Status values.
sub_statusesList of MoneyGram sub-statuses that qualify status, such as HOLD - DATA COLLECTION NEEDED. Omitted when MoneyGram reports none.
amount_in, amount_in_assetAmount and asset the customer sends.
amount_out, amount_out_assetAmount and asset the customer receives.
amount_fee, amount_fee_assetFee and its asset. The fee asset is the payout asset: the cash currency on a cash-out, and USDC on a cash-in.
fromCustomer wallet address, on cash-in and on cash-out. On a REFUNDED notification, from and to are swapped.
toMoneyGram receiving account as recorded on the transaction. It can be an address on a different network from the transaction. Do not use it to infer the network. Use network.
started_atDo not use. A known conversion defect renders it as a date in January 1970, on every network.
updated_at, completed_atUTC, in ISO 8601 with six fractional digits, for example 2026-11-11T21:31:01.856000Z. completed_at appears only once the transaction reaches a terminal state. Treat both as informational, and do not use them for ordering or for age checks.

All amounts are strings, not numbers. Parse them as decimals, and do not round-trip them through a float. Precision varies between fields and events, so expect values such as "3", "38.0", and "38.00".

Differences from the Stellar payload

If you are porting a working Stellar handler to another network, these are the only changes:

  • Adds network.
  • Renames stellar_transaction_id to transaction_id.
  • Omits withdraw_anchor_account, withdraw_memo, withdraw_memo_type, deposit_memo and deposit_memo_type. These are Stellar-specific and have no equivalent on other networks.
  • Carries the MoneyGram transaction status in status, in place of a SEP-24 value.
  • Adds sub_statuses when MoneyGram reports any.

Every other field keeps the same name and meaning it has on Stellar.

Status values

On every network except Stellar, status is the MoneyGram transaction status. Values are uppercase, and one of them contains a space (IN TRANSIT). Match them exactly.

statusMeaning
UNFUNDEDMoneyGram has staged the transaction, and the customer has not funded it yet.
SENTMoneyGram has accepted the funded, committed transaction.
AVAILABLEThe cash is ready for pickup, and the reference number is live.
IN TRANSITThe funds are on their way to the wallet.
RECEIVEDThe receiver collected the cash.
DELIVEREDThe funds reached the wallet.
PROCESSINGThe transaction needs additional review by MoneyGram. sub_statuses gives the reason.
REJECTEDMoneyGram rejected the transaction. MoneyGram can only refund it to the sender.
REFUNDEDMoneyGram refunded the sender.
CLOSEDMoneyGram closed the transaction and handles it with the partner or the customer.

MoneyGram reports sub-statuses for three of these values. A notification can carry more than one sub-status, in any order.

statussub_statuses values
PROCESSINGHOLD - DATA COLLECTION NEEDED, HOLD - DOCUMENT COLLECTION NEEDED, HOLD - INTERVIEW NEEDED, HOLD - INTERNAL REVIEW, PARTNER HOLD
REJECTEDSENDER REJECT, RECEIVER REJECT, REJECTED BY PARTNER
CLOSEDOPTION-O REFUND. MoneyGram refunded the sender under a new reference number.

MoneyGram defines these values in Handling transaction status and sub-status.

Sometimes MoneyGram cannot look up the transaction status when it sends the notification. In that case status carries the lowercase SEP-24 value instead, such as pending_user_transfer_complete. Treat any value you do not recognise as a prompt to poll GET /status?sync=true.

Webhook status and Ramps status

The webhook status and the Ramps API status are different vocabularies. This table shows the value each one carries at the same moment.

MomentWebhook status, other networksWebhook status, StellarRamps API status
Cash-out: MoneyGram received the USDC, and the cash is ready for pickupAVAILABLEpending_user_transfer_completecompleted
Cash-out: the transaction needs additional reviewPROCESSING, with sub_statusespending_anchorNo change
Cash-out: the receiver collected the cashRECEIVEDcompletedpaid_out
Cash-out: MoneyGram refunded the senderREFUNDEDrefundedrefunded
Cash-in: the customer paid at the store, and the USDC is on its wayIN TRANSITpending_anchorfunds_received
Cash-in: the USDC reached the walletDELIVEREDcompletedcompleted

On cash-out, completed means the cash is ready for pickup in the Ramps API. On a Stellar webhook, completed means the receiver collected the cash.

MoneyGram sends no event for some Ramps statuses, so no webhook announces them: quote_expired, the refund steps before refunded, refund_failed, and cash-out funds_received. Poll GET /status?sync=true to see them.

Do not drive funds movement off the webhook value. Reconcile with GET /status?sync=true first.

Verifying the signature

Every notification is signed with Ed25519, on every network. The signature is over this exact plaintext:

TEXT
{timestamp}.{your_webhook_host}.{raw_body}
  • {timestamp} is the Unix time in seconds from the t component of the Signature header.
  • {your_webhook_host} is the host of the webhook URL you registered, with no scheme, no path, and no port. Ramps registers the host name alone, so a URL such as https://api.example.com:4443/webhook is registered as api.example.com. Including the port would make the plaintext differ from what was signed, and every verification would fail.
  • {raw_body} is the request body exactly as your endpoint received it, as a UTF-8 string.

The signature itself is base64 encoded.

What arrives at your endpoint. The delivery is an HTTPS POST with two headers that matter. The body is the notification object, with no wrapper:

TEXT
Content-Type: application/jsonSignature: t=1787932754,s=<base64 Ed25519 signature>
JSON
{"transaction":{"id":"bb7f5271-...","network":"SOL", ... }}

Verify against the raw request body, before you parse it. Many web frameworks parse a JSON body automatically. Capture the raw bytes first, for example with express.raw() in Express. In Express, register the webhook route before app.use(express.json()), or exclude the webhook path from the JSON parser. Otherwise the body arrives already parsed, and verification fails on genuine notifications. Do not parse the body and serialize it again before you verify: key order and whitespace would change, and the check would fail on a genuine notification.

Split the Signature header on the first = of each component. Base64 padding in s contains = characters, and there is no space after the comma.

Public keys. MoneyGram signs with one key pair per environment. The public half is a base32 G... strkey, the same key format Stellar uses, not a PEM or an X.509 blob.

EnvironmentEd25519 public key
Playground (sandbox)GCSESAP5ILVM6CWIEGK2SDOCQU7PHVFYYT7JNKRDAQNVQWKD5YEE5ZJ4
ProductionGD5NUMEX7LYHXGXCAD4PGW7JDMOUY2DKRGY5XZHJS5IONVHDKCJYGVCL

The key is per environment rather than per partner, so if you run separate custodial and non-custodial partner records against the same environment, both verify against the same key.

To decode the strkey yourself: base32-decode it, then drop the leading version byte and the trailing two checksum bytes. The remaining 32 bytes are the raw Ed25519 public key.

Step by step. The same procedure in prose, for other languages:

  1. Confirm the request carries a Signature header. Reject it if the header is absent.
  2. Split the header on commas, then split each component on its first =. This yields t, the Unix time in seconds, and s, the base64 signature. Base64 padding in s contains = characters, so splitting on every = corrupts the value.
  3. Read the raw request body as a UTF-8 string. Do not parse it yet. Keep it exactly as received.
  4. Build the plaintext by joining, with no separators beyond the periods shown: t as a string, a ., the host of the webhook URL you registered (no scheme, no path, no port), another ., then the raw body verbatim.
  5. Base64-decode s to get the 64-byte signature.
  6. Decode the G... strkey for your environment from the table above into a 32-byte Ed25519 public key.
  7. Verify the signature over the plaintext with that key, and reject the notification if verification fails.
  8. Check freshness, and reject if t is more than a few minutes in the future or older than your chosen window. Retries replay the original signed payload, so the timestamp does not advance across redeliveries: the window must be at least 60 minutes, the full retry horizon. Allow a little beyond it for delivery latency. See Delivery and retries.
  9. Only now parse the body as JSON and read its transaction object.
JavaScript
const crypto = require('node:crypto') // Decode a G... strkey into an Ed25519 public key. Base32, then drop the// leading version byte and the trailing two checksum bytes; the 32 bytes left// are the raw key. The DER prefix is the fixed SPKI header for Ed25519.const BASE32 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567'function ed25519FromStrkey(strkey) {  let bits = 0  let value = 0  const bytes = []  for (const char of strkey.replace(/=+$/, '')) {    const index = BASE32.indexOf(char)    if (index === -1) throw new Error('invalid strkey')    value = (value << 5) | index    bits += 5    if (bits >= 8) {      bytes.push((value >>> (bits - 8)) & 0xff)      bits -= 8    }  }  const decoded = Buffer.from(bytes)  const raw = decoded.subarray(1, decoded.length - 2)  if (raw.length !== 32) throw new Error('invalid strkey')   return crypto.createPublicKey({    key: Buffer.concat([Buffer.from('302a300506032b6570032100', 'hex'), raw]),    format: 'der',    type: 'spki',  })} // MGI_WEBHOOK_PUBLIC_KEY is the G... strkey for your environment, from the table above.const webhookKey = ed25519FromStrkey(MGI_WEBHOOK_PUBLIC_KEY) // rawBody is the request body exactly as received, as a string, before any JSON parsing.function handleNotification(signatureHeader, rawBody) {  const parts = {}  for (const piece of String(signatureHeader).split(',')) {    const i = piece.indexOf('=')    parts[piece.slice(0, i).trim()] = piece.slice(i + 1).trim()  }   const plaintext = `${parts.t}.${WEBHOOK_HOST}.${rawBody}`   const verified = crypto.verify(    null,    Buffer.from(plaintext, 'utf8'),    webhookKey,    Buffer.from(parts.s, 'base64')  )  if (!verified) throw new Error('bad signature')   // Retries replay the original signed payload, so the timestamp does not advance.  // The retry horizon is 60 minutes, so that is the floor; the extra 5 minutes are  // headroom for delivery latency, and MAX_SKEW_MS for clock drift against the signer.  const MAX_AGE_MS = 65 * 60 * 1000  const MAX_SKEW_MS = 5 * 60 * 1000  const ageMs = Date.now() - Number(parts.t) * 1000  if (!Number.isFinite(ageMs) || ageMs < -MAX_SKEW_MS || ageMs > MAX_AGE_MS) throw new Error('stale')   return JSON.parse(rawBody).transaction} // Express: register this route before app.use(express.json()), so the body reaches the verifier as raw bytes.// Respond 200 only after the notification is stored, so a failed enqueue is redelivered.app.post('/moneygram/webhook', express.raw({ type: '*/*' }), async (req, res) => {  let transaction  try {    transaction = handleNotification(req.headers.signature, req.body.toString('utf8'))  } catch {    return res.sendStatus(401)  }  try {    await queueForProcessing(transaction)  } catch {    return res.sendStatus(503)  }  res.sendStatus(200)})

crypto.verify and the strkey decoder above are all you need: Node's standard library covers Ed25519, and the G... envelope is a base32 encoding rather than a cryptographic difference. If you already depend on @stellar/stellar-sdk, Keypair.fromPublicKey(MGI_WEBHOOK_PUBLIC_KEY).verify(plaintext, signature) does the same work in one call. In any other language, decode the strkey as described above and pass the 32-byte key and 64-byte signature to any Ed25519 library.

Do not use the RSA scheme from the MoneyGram security page. The Signature: t=..., s=... header looks identical, but that page describes MoneyGram's core notification products, which sign with RSA SHA-256 over the raw body. Wallet transaction status events, on Stellar and on every other network, use the Ed25519 scheme described here.

Delivery and retries

Delivery works as follows. The URL rules come from the MoneyGram webhooks documentation.

  • Delivery is an HTTPS POST to the URL you registered. The URL must use a domain name rather than an IP, listen on port 443, 4443 or 10443, and carry no query parameters.
  • Respond 200 OK within 10 seconds. Store the notification durably first, for example on a queue, then respond and process it asynchronously. Slow downstream work inside the request will trip the timeout and trigger redelivery. If the store fails, respond with an error status so MoneyGram redelivers.
  • A non-200 response, a timeout, or a connection error is retried up to 10 times over about 1 hour. The first retries arrive about 10 seconds apart, and the later ones about 10 minutes apart. After the last retry the event is marked undelivered.
  • Retries replay the original signed payload, including the original t. The timestamp does not advance, so a freshness window shorter than the retry horizon will reject legitimate redeliveries.
  • Retries mean duplicate deliveries are normal. Make your handler idempotent and deduplicate on id together with status and sub_statuses. A PROCESSING notification can repeat with different sub-statuses, and each one is a separate event.
  • Events can arrive out of order. Order by your own receipt time and reconcile with GET /status?sync=true rather than trusting the payload timestamps, which are not reliable for ordering (see the field notes above).
  • Payloads contain no PII.

Partner styleStrategy
Embedded widgetonTransactionCreated + onComplete for UX; webhook for the finished state, and poll to reconcile
Direct API integrationWebhook for the finished state; poll after commit where webhooks are not yet enabled
Custodial + ledgerWebhook to the finished state and reconcile by polling, then custodial-specific crediting (cash-in) or debiting reconciliation (cash-out)

DocumentTopic
Custodial integration overviewShared custodial setup, sessions, profiles, security
RAMPS_TRANSACTION_CREATEDWidget creation event
Custodial cash-inOmnibus crediting on completed
Partner transaction historyHistory storage and view mode