Development Guide

The 'Update a Staged Transaction' endpoint determines the information to collect from the consumer, it also validates the data for compliance purposes and updates the transactionId resource with the data gathered. Use this endpoint after retrieving a staged transaction via the Search Staged Transactions endpoint.

1. Prepare headers & authentication:

The application must call the 'Update a Staged Transaction' endpoint with a PUT HTTP method, providing the OAuth access_token in the header and all other required header values.

Note: MoneyGram uses the OAuth 2.0 framework. The application must use their OAuth client credentials to generate an access_token by calling the Get access token endpoint. The token is valid for **1 hour ** and must be passed as a header value in all subsequent API HTTP calls. Learn More

🚀
Launch Code Example

2. Provide the `transactionId` resource as a path parameter

The application must pass the associated transactionId as a path parameter on the Update API. This will allow the application to update the transactionId resource with consumer and transactional information. The transactionId will have been previously generated from search staged transaction.

🚀
Launch Code Example

3. Provide request body.

The application must use the oneOfto select the appropriate request schema: TransfersStagedTranRequest or TransfersStagedTranWithAddlnDataRequestoneOf:

TransfersStagedTranRequestThe application can provide the following optional fields in the request body: targetAudience, agentPartnerId, posId , operatorId, userLanguage, receipt.primaryLanguage, and receipt.secondarylanguage receipt.image.
OR

TransfersStagedTranWithAddlnDataRequest The application can provide the following optional fields in the request body: targetAudience, agentPartnerId, posId , operatorId, userLanguage, transactionInformation.purposeOfTransactionCode, transactionInformation.sourceOfFundsCode, transactionInformation.proofofFundsCode, transactionInformation.intendedUseOfMGIServicesCode, transactionInformation.relationshipToReceiver, transactionInformation.senderAnnaulIncome, receipt.primaryLanguage, receipt.secondarylanguage, additionalDetails.key, additionalDetails.value, documentImage.imageReferenceId, documentImage.imageVerification, and documentImage.imageTypeCode.

🚀
Launch Code Example
.

4. Make a request and handle response:

The application must call the 'Update a transaction' endpoint with a PUT HTTP method. The application must build to handle the following response scenarios:

Success | Parse the Response | 200 OK HTTP Status | "readyToCommit": true

When the 'Update a staged transaction' endpoint responds with a 200 HTTP Status and the "readytoCommit": true, transactionId, serviceOption, sender, receiver, sendAmount, sendCurrency, fees, fxRate, discountsApplied , receiveAmount and the total. In some cases, send or receive side taxes and/or additional charges are applied. The application can proceed to "Commit a staged transaction" API and execute the transfer of funds.

Failed | Handle the Error | 400 Bad Request HTTP Status

When the 'Update a staged transaction' endpoint responds with 400 Bad Request HTTP Status the application cannot proceed to the "Commit a staged transaction" endpoint. Specific error code/s will be returned with an array of offending fields. The application will need to resolve these errors and resubmit the transaction for validation. The application can make repeated attempts on the 'Update a transaction' endpoint until validation is successful.

Note: In some scenarios, enhanced due diligence needs to be undertaken on the consumer. Specific error code/s will be returned and an array of offending fields. The fields/values must to be provided and resubmitted on the Update API for further checks.

🚀
Launch Code Example
.

7. You're Done! Proceed to 'Commit a Staged Transaction API':

The application can call the 'Commit a staged transaction' endpoint to execute the transfer when a 200 HTTP Success Status and the boolean "readyForCommit": true is returned on the Update response. The application must use the associated transactionId on the subsequent Commit a Staged Transaction API by providing it as a path parameter. The Commit endpoint is the final API call and will execute the transaction to MoneyGram.

Note: the application cannot proceed until the "readyForCommit": true. The Application must correct and resubmit the data to until they get a "readyForCommit": true

Code Examples

const axios = require('axios');
const { v4: uuidv4 } = require('uuid');

const updateStagedTransaction = async () => {
  const token = "your_access_token_from_oauth_response";
  const transactionId = "transactionId"; 
  // Production: extapi.moneygram.com | Test: sandboxapi.moneygram.com
  const host = "sandboxapi.moneygram.com";
  const url = `https://${host}/transfer/v1/stagedtransactions/${transactionId}`;

  const headers = {
    'Content-Type': 'application/json',
    'X-MG-ClientRequestId': uuidv4(),
    'Authorization': `Bearer ${token}`,
  };

  const request = {
    agentPartnerId: "your_partner_id",
    targetAudience: "AGENT_FACING",
    userLanguage: "en-US",
    receipt: {
      primaryLanguage: "ENG",
      secondaryLanguage: "SPA",
      image: "base64_receipt_image_string"
    },
    transactionInformation: {
      purposeOfTransactionCode: "FAMILY_SUPPORT",
      sourceOfFundsCode: "SALARY",
      relationshipToReceiver: "FAMILY"
    },
    additionalDetails: [
      { key: "customKey", value: "customValue" }
    ]
  };

  try {
    const response = await axios.put(url, request, { headers });
    // Check readyForCommit before proceeding to Commit API
    console.log(JSON.stringify(response.data, null, 2));
  } catch (error) {
    if (error.response) {
      console.log('Status:', error.response.status);
      console.log('Body:', error.response.data);
    } else {
      console.error('Error:', error.message);
    }
  }
};

updateStagedTransaction();

import requests, uuid

def update_staged_transaction():
    token = "your_access_token_from_oauth_response"
    transaction_id = "staged_tx_id"
    host = "sandboxapi.moneygram.com"
    url = f"https://{host}/transfer/v1/stagedtransactions/{transactionId}"

    headers = {
        "Content-Type": "application/json",
        "X-MG-ClientRequestId": str(uuid.uuid4()),
        "Authorization": f"Bearer {token}",
    }

    payload = {
        "agentPartnerId": "your_partner_id",
        "targetAudience": "AGENT_FACING",
        "userLanguage": "en-US",
        "receipt": {
            "primaryLanguage": "ENG",
            "secondaryLanguage": "SPA",
            "image": "base64_receipt_image_string"
        },
        "transactionInformation": {
            "purposeOfTransactionCode": "FAMILY_SUPPORT",
            "sourceOfFundsCode": "SALARY",
            "relationshipToReceiver": "FAMILY"
        },
        "additionalDetails": [
            {"key": "customKey", "value": "customValue"}
        ]
    }

    resp = requests.put(url, json=payload, headers=headers)
    if resp.ok:
        print(resp.json())
    else:
        print(f"Error {resp.status_code}:", resp.json())

update_staged_transaction()

import java.net.http.*;
import java.net.URI;
import java.util.UUID;

public class UpdateStagedTransaction {
  public static void main(String[] args) throws Exception {
    String token = "your_access_token_from_oauth_response";
    String transactionId = "transactionId";
    String host = "sandboxapi.moneygram.com";
    String url = "https://" + host + "/transfer/v1/stagedtransactions/" + transactionId;

    String body = """
      {
        "agentPartnerId": "your_partner_id",
        "targetAudience": "AGENT_FACING",
        "userLanguage": "en-US",
        "receipt": {
          "primaryLanguage": "ENG",
          "secondaryLanguage": "SPA",
          "image": "base64_receipt_image_string"
        },
        "transactionInformation": {
          "purposeOfTransactionCode": "FAMILY_SUPPORT",
          "sourceOfFundsCode": "SALARY",
          "relationshipToReceiver": "FAMILY"
        }
      }""";

    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create(url))
      .header("Content-Type", "application/json")
      .header("Authorization", "Bearer " + token)
      .header("X-MG-ClientRequestId", UUID.randomUUID().toString())
      .PUT(HttpRequest.BodyPublishers.ofString(body))
      .build();

    HttpResponse<String> response =
      client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}

Support APIs

To make your development easier, MoneyGram has provided a Reference Data APIs Module that can be queried to provide a list of supported fields, values and associated meta-data to use in your integration.

Name	HTTP Method	Endpoints	Description
Retrieve Enumerations	GET	/reference-data/v1/enumerations	Retrieves enumerated values for fieldsRetrieves enumerated values for fields

API Structure

Header Parameters

Field	Type	Required /Optional	Description
`X-MG-ClientRequestId`	String	Required	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.
`X-MG-ConsumerIPAddress`	String	Optional	IP Address of the system initiating the session

Path Parameters

Path Parameter	Type	Required /Optional	Description
`transactionId`	String Max length: 36	Required	Unique id of the transaction resource Pattern.compile("^[0-9a-fA-F]8-[0-9a-fA-F]4-[0-9a-fA-F]4-[0-9a-fA-F]4-[0-9a-fA-F]12$")

Request Body Parameters

Body Parameter	Description
TransferByStagedTranRequest	Business details + receipt object. Basic update with receipt language and image.
TransferByStagedTranWithAddlnDataRequest	Extends the base request with transactionInformation, additionalDetails, and documentImage.

Request Body Fields with TransfersStagedTranRequest

Field	Type	Required /Optional	Description
`targetAudience`	String	Required	Tailors MoneyGram’s error messages and field metadata to an in-store, digital or crypto consumer. (Enumerated value) _NOTE: For a full list of accepted target audience values. See the TARGET_AUDIENCE enumeration from the Reference Data Enumerations endpoint _
`agentPartnerId`	String Max length: 8	Required	Unique identifier for the agent or partner
`posId`	String	Optional	Point of sale identifier of the client performing the API Call
`operatorId`	String Max length: 80	Required	Operator name or ID of the user performing the transaction. Name or ID must be populated from the agent/partner system and cannot be edited by the user.
`userLanguage`	String Max length: 6	Optional	Language used by the user/operator
`receipt.primaryLanguage`	String	Optional	Primary receipt language of the transacting partner
`receipt.secondaryLanguage`	String	Optional	Secondary receipt language of the transacting partner
`receipt.image`	String	Optional	Receipt image string of the transacting partner

Request Body Fields with TransfersStagedTranWithAddlnRequest

Field	Type	Required /Optional	Description
`targetAudience`	String	Required	Tailors MoneyGram’s error messages and field metadata to an in-store, digital or crypto consumer. (Enumerated value) _NOTE: For a full list of accepted target audience values. See the TARGET_AUDIENCE enumeration from the Reference Data Enumerations endpoint _
`agentPartnerId`	String Max length: 8	Required	Unique identifier for the agent or partner
`posId`	String	Optional	Point of sale identifier of the client performing the API Call
`operatorId`	String Max length: 80	Required	Operator name or ID of the user performing the transaction. Name or ID must be populated from the agent/partner system and cannot be edited by the user.
`userLanguage`	String Max length: 6	Optional	Language used by the user/operator
`receipt.primaryLanguage`	String	Optional	Primary receipt language of the transacting partner
`receipt.secondaryLanguage`	String	Optional	Secondary receipt language of the transacting partner
`receipt.image`	String	Optional	Receipt image string of the transacting partner
`transactionInformation.purposeofTransactionCode`	String	Optional	Explanation or reason for transferring funds (Enumerated Values) Reference Data Enumerations endpoint _
`transactionInformation.sourceOfFundsCode`	String	Optional	Declaration of where the transaction funds were sourced (Enumerated Values) Reference Data Enumerations endpoint _
`transactionInformation.proofOfFundsCode`	String	Optional	Proof of where the transaction funds were sourced (Enumerated Values) NOTE: For a full list of accepted proof of funds values. See the PROOF_OF_FUNDS enumeration from the Reference Data Enumerations endpoint
`transactionInformation.intendedUseOfMGIServicesCode`	String Max length: 30	Optional	Explanation for using MoneyGram service (Enumerated Values) NOTE: For a full list of accepted use of MGI services values. See the TYPICAL_USE_OF_MGI enumeration from the Reference Data Enumerations endpoint
`transactionInformation.relationshipToReceiver`	String Max length: 30	Optional	Declaration of consumer's relationship to the counter party (Enumerated Values) NOTE: For a full list of relationships values. See the RLTIONSHP_TO_RECIVR enumeration from the Reference Data Enumerations endpoint
`transactionInformation.senderAnnualIncome`	String Enumerated Value	Optional	Sender's annual income bracket
`additionalDetails`	Dynamic	Optional	Dynamic field key/values
`documentImage.imageReferenceId`	String	Optional	Document Reference ID from Upload
`documentImage.imageVerification`	String	Optional	Verification of ID on file with entering ID Number
`documentImage.imageTypeCode`	String	Optional	Type of identification document (Enumerated Value)

Response Fields

Field	Type	Required /Optional	Description
`readyForCommit`	Boolean	Required	Indicates whether the transaction can proceed to commit
`rewardsNumber`	String Max length: 8	Optional	Unique identifier for the agent or partner
`transactionId`	String Max Length: 20	Required	MoneyGram Rewards number
`serviceOptionName`	String	Required	Consumer facing name to identify the transaction method
`serviceOptionRoutingName`	String	Optional	Unique name of the individual banking, wallet, or card provider
`destinationCountryCode`	String Max Length: 3	Required	Transaction Destination Country (ISO alpha-3 code) NOTE: For a full list of accepted destination Countries and supported destinationCountrySubdivisionCode see Reference Data API Module: Retrieve Countries ISO3 endpoint
`destinationCountrySubdivisionCode`	String Max length: 6	Conditionally Required	Destination state/province is conditionally required when transacting to the United States or Canada. NOTE: For a full list of accepted destination Countries and supported destinationCountrySubdivisionCode see Reference Data API Module: Retrieve Countries ISO3 Endpoint
`sender.name.firstName`	String Min length: 1 Max length: 20	Required	First Name
`sender.name.middleName`	String Min length: 1 Max length: 20	Optional	Middle Name (if applicable)
`sender.name.lastName`	String Min length: 1 Max length: 30	Required	Last Name
`sender.name.secondLastName`	String Min length: 1 Max length: 30	Optional	Second Last Name
`sender.address.line1`	String Min length: 5 Max length: 30	Required	Residence address line 1
`sender.address.line2`	String Min length: 0 Max length: 80	Optional	Residence address line 2 (if applicable)
`sender.address.line3`	String Min length: 0 Max length: 80	Optional	Residence address line 3 (if applicable)
`sender.address.city`	String Min length: 1 Max length: 40	Required	City of residence
`sender.address.countrySubdivisionCode`	String Length: 6	Optional	State/province of residence
`sender.address.countryCode`	String Length: 3	Required	Country of residence (ISO Alpha-3 Code)
`sender.address.postalCode`	String Min length: 2 Max length: 6	Optional	Postal code/ZIP of residence
`sender.mobilePhone.number`	String Min length: 5 Max length: 14	Required	Phone number
`sender.mobilePhone.countryDialCode`	String Min length: 1 Max length: 3	Required	Country calling code NOTE: For country calling code see Reference Data API Module /countries endpoint `phoneDialCodes`
`sender.email`	String Min length: 1 Max length: 255	Optional	Email address
`sender.personalDetails.genderCode`	String	Optional	Gender (Enumerated Value)
`sender.personalDetails.dateOfBirth`	String Length: 10	Required	Date of birth (YYYY-MM-DD)
`sender.personalDetails.birthCity`	String Min length: 0 Max length: 40	Optional	City of birth
`sender.personalDetails.birthCountryCode`	String Max Length: 3	Conditionally Required	Country of birth (ISO alpha-3 code) NOTE: For a full list of accepted birth.CountryCodes see ‘Reference Data API Module’ and the Retrieve Countries ISO3 endpoint: ]
`sender.personalDetails.citizenshipCountryCode`	String Max Length: 3	Optional	Country of birth. (ISO alpha-3 code)
`sender.personalDetails.occupationCode`	String	Optional	Occupation/Employment (Enumerated Value) NOTE: For a full list of accepted occupation codes see Reference Data Enumerations endpoint
`sender.personalDetails.politicalExposedPerson`	Boolean	Optional	Flag to declare a Politically Exposed Person (PEP)
`sender.personalDetails.nationalityCountryCode`	String Min Length: 3 Max Length: 3	Optional	Country of citizenship (ISO alpha-3 code)
`sender.primaryIdentification.typeCode`	String Max length: 3	Required	Type of identification document (Enumerated Value) NOTE: For a full list of accepted Identification documents by country. see Reference Data Enumerations endpoint
`sender.primaryIdentification.id`	String Max length: 30	Required	Identification document number
`sender.primaryIdentification.issueCountrySubdivisionCode`	String Max length: 6	Optional	Issuing state/province of identification document.
`sender.primaryIdentification.issueCountryCode`	String Max Length: 3	Required	Issuing country of identification document (ISO alpha-3 code)
`sender.primaryIdentification.expirationYear`	String Length: 4 Format: YYYY	Optional	Expiration year of identification document (YYYY)
`sender.primaryIdentification.expirationMonth`	String Length: 2 Format: MM	Optional	Expiration month of identification document (MM)
`sender.primaryIdentification.expirationDay`	String Length: 2 Format: DD	Optional	Expiration month of identification document (DD)
`sender.primaryIdentification.issueAuthority`	String Min length: 0 Max length: 30	Optional	Issuing authority of identification document
`sender.primaryIdentification.issueCity`	String Min length: 0 Max length: 40	Optional	Issuing city of identification document
`sender.primaryIdentification.issueYear`	String Length: 4 Format: YYYY	Optional	Issuing year of identification document (YYYY)
`sender.primaryIdentification.issueMonth`	String Length: 2 Format: MM	Optional	Issuing month of identification document (MM)
`sender.primaryIdentification.issueDay`	String Length: 2 Format: DD	Optional	Issuing day of identification document (DD)
`sender.secondaryIdentification.typeCode`	String Max length: 3	Optional	Type of identification document (Enumerated Value)
`sender.secondaryIdentification.id`	String Max length: 30	Optional	Identification document number
`sender.secondaryIdentification.issueCountrySubdivisionCode`	String Max length: 6	Optional	Issuing state/province of identification document.
`sender.secondaryIdentification.issueCountryCode`	String Max length: 3	Required	Issuing country of identification document. (ISO alpha-3 code)
`sender.secondaryIdentification.expirationYear`	String Length: 4 Format: YYYY	Optional	Expiration year of identification document (YYYY)
`sender.secondaryIdentification.expirationMonth`	String Length: 2 Format: MM	Optional	Expiration month of identification document (MM)
`sender.secondaryIdentification.expirationDay`	String Length: 2 Format: DD	Optional	Expiration month of identification document (DD)
`sender.secondaryIdentification.issueAuthority`	String Min length: 0 Max length: 30	Optional	Issuing authority of identification document
`sender.secondaryIdentification.issueCity`	String Min length: 0 Max length: 40	Optional	Issuing city of identification document
`sender.secondaryIdentification.issueYear`	String Length: 4 Format: YYYY	Optional	Issuing year of identification document (YYYY)
`sender.secondaryIdentification.issueMonth`	String Length: 4 Format: MM	Optional	Issuing month of identification document (MM)
`sender.secondaryIdentification.issueDay`	String Length: 4 Format: DD	Optional	Issuing day of identification document (DD)
`receiver.name.firstName`	String Min length: 1 Max length: 20	Required	First Name
`receiver.name.middleName`	String Min length: 0 Max length: 20	Optional	Middle Name (if applicable)
`receiver.name.lastName`	String Min length: 1 Max length: 30	Required	Last Name
`receiver.name.secondLastName`	String Min length: 1 Max length: 30	Optional	Second Last Name
`sendAmount.amount.value`	Number Max length: 14	Required	Transaction amount and currency excluding fees and exchange rate. Transaction Currency (ISO alpha-3 code) For Crypto partners this is the fiat currency for the BUY/Sell or Ramp-on/Ramp-off
`sendAmount.amount.currencyCode`	String	Required	The sendAmount.amount.value currency code (ISO alpha-3 code)
`sendAmount.fees.value`	Number Min length: 0 Max length: 14	Required	Fee Amount and Fee Currency applied to transaction (Fee currencyCode uses ISO alpha-3 code)
`sendAmount.fees.currencycode`	String	Required	Value's Currency code (ISO alpha-3 code)
`sendAmount.taxes.value`	Number Min length: 0 Max length: 14	Conditionally Required	Tax Amount and Tax Currency applied to the Transaction by the the origin country
`sendAmount.taxes.currencyCode`	Sting	Conditionally Required	Value's Currency code (ISO alpha-3 code)
`sendAmount.additionalCharges.typeCode`	String	Conditionally Required	Type Code to indicate if the fee or tax is to be collected by MoneyGram or the partner
`sendAmount.additionalCharges.label`	String	Conditionally Required	Consumer facing label name to identify the charge type
`sendAmount.additionalCharges.value`	Number	Conditionally Required	Additional fee or tax amount
`sendAmount.additionalCharges.currencyCode`	String	Conditionally Required	The `sendAmount.additionalCharges.value currency` (ISO alpha-3 code)
`sendAmount.discountApplied.totalDiscount`	String	Optional	Transaction discount amount applied and currency type excluding fees and exchange rate. Transaction discount currencyCode (ISO alpha-3 code)
`sendAmount.discountApplied.promotionalDetails`	String	Optional	Additional Details about the applied promotion to the transaction. currencyCode (ISO alpha-3 code)
`sendAmount.total.value`	Number Max length 14	Required	Transaction Total Amount including fees, taxes and discount.
`sendAmount.total.currencyCode`	String	Required	the `sendAmount.total.value` code (ISO alpha-3 code)
`receiveAmount.amount.value`	Number Max length: 14	Required	Transaction receive amount
`receiveAmount.amount.currencyCode`	String	Required	the `receiveAmount.amount.value` currency code (ISO alpha-3 code)
`receiveAmount.fees.value`	Number Max length: 14	Optional	Receive fee by the destination country.
`receiveAmount.fees.currencyCode`	String	Optional	The `receiveAmount.fees.value`currency code (ISO alpha-3 code)
`receiveAmount.taxes.value`	Number Max length: 14	Optional	Tax Amount applied to the Transaction by the the origin country
`receiveAmount.taxes.currencyCode`	String	Optional	The `receiveAmount.taxes.value` currency code (ISO alpha-3 code)
`receiveAmount.additionalCharges.typeCode`	String	Optional	Type code to indicate if the fee or tax is to be collected by MoneyGram or the partner
`receiveAmount.additionalCharges.label`	String	Optional	Consumer facing label name to identify the charge type
`receiveAmount.additionalCharges.value`	Number Max length: 14	Optional	Additional fee or tax amount
`receiveAmount.additionalCharges.currencyCode`	String	Optional	The `receiveAmount.additionalCharges.value` currency code (ISO alpha-3 code)
`receiveAmount.total.value`	Number Max length: 14	Required	Receive Amount Total and Receive Transaction Currency to be picked-up/deposited in destination country including fees, taxes and discount
`receiveAmount.total.currencyCode`	String	Required	The `receiveAmount.total.value` currencyCode ( ISO alpha-3 code)
`receiveAmount.fxRate`	Number Max length: 6	Required	Fx Rate applied to transaction
`receiveAmount.fxRateEstimated`	Boolean	Optional	Indicates whether the Fx is “estimated” and amount, taxes and total cannot be guaranteed. The word “estimated” must appear before receiveAmount.amount, receiveAmount.fees, receiveAmount.taxes and receiveAmount.total only when true.
`additionalDetails`	Dynamic	Optional	Dynamic field key/values
`targetAccountProfileId`	String	Optional	Unique identifier for Target Account Resource
`preCommitReceipt.consumerHyperLink`	String	Optional	Receipt image string of the transacting partner
`fundingSource.tenderType`	String	Optional	Funding method, based on enumerations
`fundingSource.provider`	String	Optional	Name of the payment provider
`fundingSource.providerNetworkCode`	String	Optional	Providers unique network identifier code
`fundingSource.providerAccountNumber`	String	Optional	Account number of payment source
`fundingSource.accountIdentifier`	String	Optional	MoneyGrams unique identifier for the consumer account

Development Guide

1. Prepare headers & authentication:

Launch Code Example

2. Provide the transactionId resource as a path parameter

Launch Code Example

3. Provide request body.

Launch Code Example

4. Make a request and handle response:

Launch Code Example

7. You're Done! Proceed to 'Commit a Staged Transaction API':

Code Examples

Support APIs

API Structure

Header Parameters

Path Parameters

Request Body Parameters

Request Body Fields with TransfersStagedTranRequest

Request Body Fields with TransfersStagedTranWithAddlnRequest

Response Fields

2. Provide the `transactionId` resource as a path parameter