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

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.

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.

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.

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: "en-US",
      secondaryLanguage: "es-MX",
      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": "en-US",
            "secondaryLanguage": "es-MX",
            "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": "en-US",
          "secondaryLanguage": "es-MX",
          "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.

API Structure

Header Parameters

Path Parameters

Request Body Parameters

Request Body Fields with TransfersStagedTranRequest

Request Body Fields with TransfersStagedTranWithAddlnRequest

Response Fields