---
updatedAt: 2026-04-16T19:32:48.000Z
---

# Retrieve a Transaction By Reference Number

The application can invoke the Retrieve a Transaction endpoint to lookup by referenceNumber and return the current status of a transaction

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "version": "0.0.3",
    "title": "Business-Disbursements Status API",
    "contact": {
      "name": "Developer Support",
      "url": "http://api.moneygram.com/support",
      "email": "developersupport@moneygram.com"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "servers": [
    {
      "url": "https://{host}/disbursement/status/v1",
      "variables": {
        "host": {
          "default": "sandboxapi.moneygram.com",
          "enum": [
            "sandboxapi.moneygram.com"
          ]
        }
      }
    }
  ],
  "paths": {
    "/transactions": {
      "get": {
        "summary": "Retrieve a Transaction",
        "description": "The application can invoke the Retrieve a Transaction endpoint to lookup by referenceNumber and return the current status of a transaction",
        "operationId": "TransactionLookupWithReferenceNumber",
        "security": [
          {
            "OAuth2": [
              "write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ClientRequestId"
          },
          {
            "$ref": "#/components/parameters/TargetAudience"
          },
          {
            "$ref": "#/components/parameters/UserLanguage"
          },
          {
            "$ref": "#/components/parameters/AgentPartnerId"
          },
          {
            "$ref": "#/components/parameters/ReferenceNumber"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-MG-SessionId": {
                "required": false,
                "schema": {
                  "type": "string"
                },
                "description": "This GUID is generated by MoneyGram for correlating multiple calls within transaction session."
              },
              "X-MG-ClientRequestId": {
                "required": false,
                "schema": {
                  "type": "string"
                },
                "description": "Client Request Id that can be passed by the client application. Client request Id must be unique within a single session for unique requests. This attribute can be used for ensuring idempotent request processing for some APIs."
              },
              "X-MG-RequestId": {
                "required": false,
                "schema": {
                  "type": "string"
                },
                "description": "This GUID is generated by MoneyGram for each incoming request. It is passed to MoneyGram services. This attribute will be used to correlate logging across multiple MoneyGram services/applications."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetBusinessTransactionResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "403": {
            "$ref": "#/components/responses/ForbiddenError"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "OAuth2": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://moneygram-sandbox.apigee.net/oauth/accesstoken?grant_type=client_credentials",
            "scopes": {
              "read": "Grants read access",
              "write": "Grants write access"
            }
          }
        }
      }
    },
    "parameters": {
      "ClientRequestId": {
        "in": "header",
        "name": "X-MG-ClientRequestId",
        "schema": {
          "type": "string",
          "default": "4c79b06f-a2af-4859-82c8-28cbb0bf361b"
        },
        "description": "Client Request Id that can be passed by the client application. Client request Id must be unique within a single session for unique requests. This attribute can be used for ensuring idempotent request processing for some APIs. MoneyGram recommends using a UUID for the value of this field."
      },
      "ReferenceNumber": {
        "in": "query",
        "name": "referenceNumber",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "MoneyGram's reference number for the transaction."
      },
      "TargetAudience": {
        "in": "query",
        "name": "targetAudience",
        "schema": {
          "type": "string",
          "default": "AGENT_FACING"
        },
        "description": "Tailors MoneyGram’s error messages and field metadata to an in-store, digital or crypto customer."
      },
      "AgentPartnerId": {
        "in": "query",
        "name": "agentPartnerId",
        "schema": {
          "type": "string",
          "default": 30150519
        },
        "required": true,
        "description": "Unique agent or partner identifier"
      },
      "UserLanguage": {
        "in": "query",
        "name": "userLanguage",
        "required": true,
        "schema": {
          "type": "string",
          "default": "en-US"
        },
        "description": "Language used by the user/operator"
      }
    },
    "responses": {
      "BadRequestError": {
        "description": "Bad request. Returns error details.",
        "headers": {
          "X-MG-SessionId": {
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "A GUID MoneyGram generates for correlating multiple calls within a transaction session."
          },
          "X-MG-ClientRequestId": {
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Client Request Id that can be passed by the client application. Client request Id must be unique within a single session for unique requests. This attribute can be used for ensuring idempotent request processing for some APIs."
          },
          "X-MG-RequestId": {
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "This GUID is generated by MoneyGram for each incoming request. It is passed to MoneyGram services. This attribute will be used to correlate logging across multiple MoneyGram services/applications."
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/errorResponse"
            }
          }
        }
      },
      "ForbiddenError": {
        "description": "Forbidden. Returns error details.",
        "headers": {
          "X-MG-SessionId": {
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "This GUID is generated by MoneyGram for correlating multiple calls within transaction session."
          },
          "X-MG-ClientRequestId": {
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Client Request Id that can be passed by the client application. Client request Id must be unique within a single session for unique requests. This attribute can be used for ensuring idempotent request processing for some APIs."
          },
          "X-MG-RequestId": {
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "This GUID is generated by MoneyGram for each incoming request. It is passed to MoneyGram services. This attribute will be used to correlate logging across multiple MoneyGram services/applications."
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/errorResponse"
            }
          }
        }
      },
      "UnauthorizedError": {
        "description": "Unauthorized. Returns error details.",
        "headers": {
          "X-MG-SessionId": {
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "This GUID is generated by MoneyGram for correlating multiple calls within transaction session."
          },
          "X-MG-ClientRequestId": {
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Client Request Id that can be passed by the client application. Client request Id must be unique within a single session for unique requests. This attribute can be used for ensuring idempotent request processing for some APIs."
          },
          "X-MG-RequestId": {
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "This GUID is generated by MoneyGram for each incoming request. It is passed to MoneyGram services. This attribute will be used to correlate logging across multiple MoneyGram services/applications."
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/errorResponse"
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Internal server error. Returns error details.",
        "headers": {
          "X-MG-SessionId": {
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "This GUID is generated by MoneyGram for correlating multiple calls within transaction session."
          },
          "X-MG-ClientRequestId": {
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Client Request Id that can be passed by the client application. Client request Id must be unique within a single session for unique requests. This attribute can be used for ensuring idempotent request processing for some APIs."
          },
          "X-MG-RequestId": {
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "This GUID is generated by MoneyGram for each incoming request. It is passed to MoneyGram services. This attribute will be used to correlate logging across multiple MoneyGram services/applications."
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/errorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "Name": {
        "type": "object",
        "required": [
          "firstName",
          "lastName"
        ],
        "properties": {
          "firstName": {
            "type": "string",
            "minLength": 0,
            "maxLength": 30,
            "pattern": "^([a-zA-Z \\u00C0-\\u017F\\-\\'\\/])*$",
            "description": "First name"
          },
          "middleName": {
            "type": "string",
            "minLength": 0,
            "maxLength": 30,
            "pattern": "^([a-zA-Z \\u00C0-\\u017F\\-\\'\\/])*$",
            "description": "Middle name (if applicable)"
          },
          "lastName": {
            "type": "string",
            "minLength": 0,
            "maxLength": 30,
            "pattern": "^([a-zA-Z \\u00C0-\\u017F\\-\\'\\/])*$",
            "description": "Last name"
          },
          "secondLastName": {
            "type": "string",
            "minLength": 0,
            "maxLength": 30,
            "pattern": "^([a-zA-Z \\u00C0-\\u017F\\-\\'\\/])*$",
            "description": "Second lastname (if applicable)"
          }
        }
      },
      "Amount": {
        "type": "object",
        "properties": {
          "value": {
            "type": "number",
            "description": "The transaction's send or receive amount, fee, taxes, total discount applied, transaction total, or reconcile amounts. See the APIs documentation for detailed information for the field"
          },
          "currencyCode": {
            "type": "string",
            "description": "Value's Currency code (ISO alpha-3 code)"
          }
        }
      },
      "BusinessSenderDetails": {
        "type": "object",
        "properties": {
          "businessName": {
            "type": "string",
            "description": "Name of business"
          },
          "businessRegistrationNumber": {
            "type": "string",
            "description": "Business registration number"
          },
          "businessCountryOfRegistration": {
            "type": "string",
            "description": "Business's country of registration (ISO alpha-3 code)"
          }
        }
      },
      "BusinessBeneficiaryDetails": {
        "type": "object",
        "properties": {
          "businessName": {
            "type": "string",
            "description": "Name of business"
          },
          "businessRegistrationNumber": {
            "type": "string",
            "description": "Business registration number"
          },
          "businessCountryOfRegistration": {
            "type": "string",
            "description": "Business's country of registration (ISO alpha-3 code)"
          }
        }
      },
      "CustomFields": {
        "minItems": 0,
        "type": "array",
        "description": "Dynamic field key/values",
        "items": {
          "type": "object",
          "properties": {
            "key": {
              "type": "string"
            },
            "value": {
              "type": "string"
            }
          }
        }
      },
      "ErrorDetails": {
        "type": "object",
        "required": [
          "category",
          "message"
        ],
        "properties": {
          "category": {
            "type": "string",
            "description": "Error category defined by MoneyGram",
            "pattern": "^[a-zA-Z]*-\\d{5}$"
          },
          "code": {
            "type": "string",
            "description": "Error codes defined by MoneyGram"
          },
          "message": {
            "type": "string",
            "description": "Error message associated with the error code"
          },
          "offendingFields": {
            "minItems": 0,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string",
                  "description": "Offending field causing the error"
                }
              }
            }
          }
        }
      },
      "AdditionalChargesDetails": {
        "type": "object",
        "properties": {
          "typeCode": {
            "type": "string",
            "description": "Code to indicate if the fee is to be collected by MoneyGram or the partner"
          },
          "label": {
            "type": "string",
            "description": "Consumer facing name to identify the charge type"
          },
          "value": {
            "type": "number",
            "description": "Additional fee's amount"
          },
          "currencyCode": {
            "type": "string",
            "description": "Additional fee's Currency (ISO alpha-3 code)"
          }
        }
      },
      "PromotionDetail": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Additional Details about the applied promotion to the transaction. currencyCode (ISO alpha-3 code)"
          },
          "discount": {
            "$ref": "#/components/schemas/Amount"
          },
          "errorCode": {
            "type": "string",
            "description": "The transaction's  total discount applied."
          },
          "errorMessage": {
            "type": "string",
            "description": "Error message associated with the error code."
          }
        }
      },
      "SendAmountDetails": {
        "type": "object",
        "required": [
          "amount",
          "fees",
          "total"
        ],
        "properties": {
          "amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "fees": {
            "$ref": "#/components/schemas/Amount"
          },
          "taxes": {
            "$ref": "#/components/schemas/Amount"
          },
          "additionalCharges": {
            "$ref": "#/components/schemas/AdditionalChargesDetails"
          },
          "discountsApplied": {
            "type": "object",
            "properties": {
              "totalDiscount": {
                "$ref": "#/components/schemas/Amount"
              },
              "promotionDetails": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PromotionDetail"
                }
              }
            }
          },
          "total": {
            "$ref": "#/components/schemas/Amount"
          }
        }
      },
      "ReceiveAmountDetails": {
        "type": "object",
        "required": [
          "amount",
          "fxRate",
          "total"
        ],
        "properties": {
          "amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "fees": {
            "$ref": "#/components/schemas/Amount"
          },
          "taxes": {
            "$ref": "#/components/schemas/Amount"
          },
          "additionalCharges": {
            "$ref": "#/components/schemas/AdditionalChargesDetails"
          },
          "total": {
            "$ref": "#/components/schemas/Amount"
          },
          "fxRate": {
            "type": "number",
            "description": "Fx Rate applied to transaction"
          },
          "fxRateEstimated": {
            "type": "boolean",
            "description": "Indicates whether the Fx is “estimated” and amount, taxes and total cannot be guaranteed. The word “estimated” must appear before recieveAmount.amount, recieveAmount.taxes and reieveAmount.total only when true."
          }
        }
      },
      "transactionSubStatusDetails": {
        "properties": {
          "subStatus": {
            "type": "string",
            "description": "MoneyGram's transaction sub-status"
          },
          "message": {
            "type": "string",
            "description": "Message associated with the substatus code."
          },
          "targetCustomer": {
            "type": "string",
            "description": "Customer associated with substatus code."
          },
          "dataToCollect": {
            "minItems": 0,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "Code": {
                  "type": "string",
                  "description": "Unique code for data or document needed to be collected from customer."
                },
                "dataCollection": {
                  "type": "string",
                  "description": "Data or document needed to be collected from customer."
                }
              }
            }
          }
        }
      },
      "errorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ErrorDetails"
          }
        }
      },
      "GetBusinessTransactionResponse": {
        "type": "object",
        "properties": {
          "transactionId": {
            "type": "string",
            "description": "Unique identifier for the transaction resource"
          },
          "partnerTransactionId": {
            "type": "string",
            "description": "Partners Unique identifier for the transaction resource."
          },
          "referenceNumber": {
            "type": "string",
            "description": "MoneyGram's reference number for the transaction"
          },
          "transactionSendDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "Transaction send date and time"
          },
          "expectedPayoutDate": {
            "type": "string",
            "format": "date",
            "description": "Expected Payout date of the transaction"
          },
          "transactionStatus": {
            "type": "string",
            "description": "MoneyGram's transaction status"
          },
          "transactionSubStatus": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/transactionSubStatusDetails"
            }
          },
          "originatingCountryCode": {
            "type": "string",
            "description": "Transaction country of Origin (ISO alpha-3 code)"
          },
          "destinationCountryCode": {
            "type": "string",
            "description": "Transaction Destination Country (ISO alpha-3 code)"
          },
          "serviceOptionCode": {
            "type": "string",
            "description": "Unique category code to identify the transaction method"
          },
          "serviceOptionName": {
            "type": "string",
            "description": "Consumer-facing name to identify the transaction method"
          },
          "serviceOptionRoutingCode": {
            "type": "string",
            "description": "Unique identifier of the individual banking, wallet, or card provider for the service option"
          },
          "serviceOptionRoutingName": {
            "type": "string",
            "description": "Unique name to identify the individual transaction method"
          },
          "sendAmount": {
            "$ref": "#/components/schemas/SendAmountDetails"
          },
          "receiveAmount": {
            "$ref": "#/components/schemas/ReceiveAmountDetails"
          },
          "sender": {
            "type": "object",
            "properties": {
              "businessInfo": {
                "$ref": "#/components/schemas/BusinessSenderDetails"
              },
              "businessProfileId": {
                "type": "string",
                "description": "A unique MoneyGram identifier for the business."
              },
              "partnerProfileId": {
                "type": "string",
                "description": "The partners business profileId that will be passed from the partner and mapped to the MoneyGram business profile ID."
              },
              "additionalDetails": {
                "$ref": "#/components/schemas/CustomFields"
              }
            }
          },
          "beneficiary": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "business": {
                    "$ref": "#/components/schemas/BusinessBeneficiaryDetails"
                  }
                }
              },
              {
                "type": "object",
                "properties": {
                  "consumer": {
                    "$ref": "#/components/schemas/Name"
                  }
                }
              }
            ]
          },
          "additionalDetails": {
            "$ref": "#/components/schemas/CustomFields"
          }
        }
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  }
}
```