Development Guide

The Search Staged Transaction endpoint searches for staged transactions based on sender information, phone number, or confirmation number.

1. Prepare headers & authentication:

The application must call the 'Search Transactions' endpoint with a POST 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 request body.

The application must use the 'Search Transactions' endpoint to search for a staged transaction by agentPartnerId. There are also optional attributes that can be used to narrow the search sender.name.firstName, sender.name.lastName, or mobilePhone.number mobilePhone.countryDialCode or confirmationNumber.

🚀
Launch Code Example

Business Rules to Code

🔍

thisLocationOnly: "true" will return only staged transaction for this agentPartnerId

If an exact match is not found for sender.name.firstName, sender.name.lastName, OR mobilePhone.number mobilePhone.countryDialCode OR confirmationNumber it will return all staged transactions for this agentPartnerId.

3. 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 transaction' endpoint responds with a 200 HTTP Status and the "readytoCommit": true, transactionId, serviceOption, sendAmount, sendCurrency, fees, fxRate, discountsApplied and the receiveAmount. In some cases, send or receive side taxes are applied. The application can proceed to "Commit a transaction" API and execute the transfer of funds.
Failed | Handle the Error | 400 Bad Request HTTP Status

When the 'Update a transaction' endpoint responds with 400 Bad Request HTTP Status the application cannot proceed to the "Commit a 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

🚀

4. You're Done! Proceed to 'Update 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 searchStagedTransactions = async () => {
  const token = 'ziFFlw2qJwDRNUB8LXo0AstGj3RI';
  const host  = 'sandboxapi.moneygram.com';
  const url   = `https://${host}/transfer/v1/stagedtransactions`;

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

  const body = {
    targetAudience:    'AGENT_FACING, CONSUMER_FACING',
    agentPartnerId:    '30150519',
    posId:             '01',
    operatorId:        'djug',
    userLanguage:      'en-us',
    confirmationNumber:'1234584',
    thisLocationOnly:  true,
  };

  try {
    const response = await axios.post(url, body, { headers });
    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);
    }
  }
};

searchStagedTransactions();

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

const searchStagedTransactions = async () => {
  const token = 'ziFFlw2qJwDRNUB8LXo0AstGj3RI';
  const host  = 'sandboxapi.moneygram.com';
  const url   = `https://${host}/transfer/v1/stagedtransactions`;

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

  const body = {
    targetAudience:    'AGENT_FACING, CONSUMER_FACING',
    agentPartnerId:    '30150519',
    posId:             '01',
    operatorId:        'djug',
    userLanguage:      'en-us',
    confirmationNumber:'1234584',
    thisLocationOnly:  true,
  };

  try {
    const response = await axios.post(url, body, { headers });
    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);
    }
  }
};

searchStagedTransactions();

import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.http.*;
import java.net.URI;
import java.util.*;

public class SearchStagedTransactions {

  public static void main(String[] args) throws Exception {

    String token = "ziFFlw2qJwDRNUB8LXo0AstGj3RI";
    String url   = "https://sandboxapi.moneygram.com/transfer/v1/stagedtransactions";

    Map<String, Object> body = new LinkedHashMap<>();
    body.put("targetAudience",     "AGENT_FACING, CONSUMER_FACING");
    body.put("agentPartnerId",     "30150519");
    body.put("posId",              "01");
    body.put("operatorId",         "djug");
    body.put("userLanguage",       "en-us");
    body.put("confirmationNumber", "1234584");
    body.put("thisLocationOnly",   true);

    String json = new ObjectMapper().writeValueAsString(body);

    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create(url))
      .header("Content-Type",         "application/json")
      .header("Accept",               "application/json")
      .header("Authorization",        "Bearer " + token)
      .header("X-MG-ClientRequestId", "4c79b06f-a2af-4859-82c8-28cbb0bf361b")
      .POST(HttpRequest.BodyPublishers.ofString(json))
      .build();

    HttpResponse<String> response = HttpClient.newHttpClient()
      .send(request, HttpResponse.BodyHandlers.ofString());

    System.out.println("Status: " + response.statusCode());
    System.out.println(response.body());
  }
}

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

Request Body Fields

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
`sender.name.firstName`	String Min length: 1 Max length: 20	Optional	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	Optional	Last Name
`sender.name.secondLastName`	String Min length: 1 Max length: 30	Optional	Second Last Name
`sender.mobilePhone.number`	String Min length: 5 Max Length: 14	Optional	Phone Number
`sender.mobilePhone.countryDialCode`	String Min length: 1 Max length: 3	Optional	Country calling code NOTE: For country calling code see Reference Data API Module /countries endpoint `phoneDialCodes`
`confirmationNumber`	String	Optional	Transaction confirmation number
`thisLocationOnly`	Boolean	Optional	Flag to search only at this location

Response Fields

Field	Type	Required /Optional	Description
`stagedTransactions.transactionId`	String	Optional	Unique identifier for the transaction resource
`stagedTransactions.confirmationNumber`	String	Optional	Transaction confirmation number
`stagedTransactions.sender.name.firstName`	String Min length: 1 Max length: 20	Required	First name
`stagedTransactions.sender.name.middleName`	String Min length: 1 Max length: 20	Optional	Middle name
`stagedTransactions.sender.name.lastName`	String Min length: 1 Max length: 30	Required	Last Name
`stagedTransactions.sender.name.secondLastName`	String Min length: 1 Max length: 30	Optional	Second Last Name
`stagedTransactions.sender.address.line1`	String Min length: 5 Max length: 30	Required	Residence address line 1
`stagedTransactions.sender.address.line2`	String Min length: 0 Max length: 80	Optional	Residence address line 2 (if applicable)
`stagedTransactions.sender.address.line3`	String Min length: 0 Max length: 80	Optional	Residence address line 3 (if applicable)
`stagedTransactions.sender.address.city`	String Min length: 1 Max length: 40	Required	City of residence
`stagedTransactions.sender.address.countrySubdivisionCode`	String Length: 6	Optional	State/province of residence
`stagedTransactions.sender.address.countryCode`	String Length: 3	Required	Country of residence (ISO Alpha-3 Code)
`stagedTransactions.sender.address.postalCode`	String Min length: 2 Max length: 6	Optional	Postal code/ZIP of residence
`stagedTransactions.sender.mobilePhone.number`	String Min length: 5 Max length: 14	Required	Phone Number
`stagedTransactions.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`
`stagesTransactions.receiver.name.firstName`	String Min length: 1 Max length: 20	Required	First Name
`stagesTransactions.receiver.name.middleName`	String Min length: 1 Max length: 20	Optional	Middle Name
`stagesTransactions.receiver.name.lastName`	String Min length: 1 Max length: 30	Required	Last Name
`stagesTransactions.receiver.name.secondLastName`	String Min length: 1 Max length: 30	Optional	Second Last Name