PUT Commit a Staged Transaction

PUT /transfer/v1/stagedtransactions/{transactionId}/commit

Development Guide

The Commit a Staged Transaction endpoint executes the staged transactionId and completes the transfer of funds. This is the final API call in the staged transaction flow and can only be called after a successful Update response with readyForCommit: true.


1. Prepare headers & authentication:

The application must call the 'Commit a Staged transaction' endpoint with a PUT HTTP method, providing the OAuth access_token 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 and prepare the request body:

The application must persist the transactionId from the Update a staged transaction endpoint and apply it as a path parameter to the Commit a staged transaction endpoint.


🚀

Launch Code Example




3. Display 'Fraud Warnings' & 'Pre-disclosure' in application UI:

It is a regulatory requirement to display Fraud Warnings (US Only, Global) and a Pre-Payment Disclosure to the consumer before the transfer of funds is executed. Both the Fraud Warnings and Pre-payment Disclosure must be displayed for all transactions (i.e. in all send countries, for all amounts, for all service options).




4. Make a request and handle the response:

The application must call the 'Commit a staged 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
    When the 'Commit a transaction' endpoint responds with a 200 HTTP Status the application has finalized and executed the transfer. The response payload, will return the following fields referenceNumber, fundsInStoreConfirmationCode and expectedPayoutDate. The funds are marked for "settlement" on the MoneyGram ledger.

  • Failed | Handle the Error | 400 Bad Request HTTP Status
    When the 'Commit a transaction' endpoint responds with 400 Bad Request HTTP Status a specific error message/s will be returned. The application will need to resolve these errors and resubmit the transaction for commit.

🚀

Launch Code Example

.




5. You're Done! Communicate the reference number to consumer:

It is recommended to prominently display the referenceNumber on the application UI and send a notification to the consumer and provide receipts




Business Rules to Code


🔍
  1. Idempotent: If the application does not receive a response from the Commit a Staged Transaction API within 5-10 seconds, the application must send the request again. This must be retried up to 3 times within a 30-minute time frame from the first commit call. If the retry attempt still fails, check the transactionStatus using the Status API to confirm if transaction was successful.

  2. **Error Code 935: **If error code 935 internal system error is returned on commit; it must be handled the same way as if the commit response is not received (see item 1).

  3. Handling Errors: Other errors can be returned on commit a transaction stopping the transaction. The application must handle scenarios where the transaction fails (an error code is returned) on commit. Learn More

  4. Receipts: Refer to Receipts module for detailed information and requirements for receipts.

  5. **Reference Number Recycling policy: **MoneyGram will recycle the reference numbers after the transactions have been closed/received for 4 to 6 months. If you are storing reference numbers in your database, you should also store the transaction date. The combination of the reference number and transaction date will be the unique key for a transaction.




Code Examples

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

const commitStagedTransaction = async () => {
  const token = "your_access_token_from_oauth_response";
  const transactionId = "staged_tx_id"; // 8-char staged transaction ID
  // Production: extapi.moneygram.com | Test: sandboxapi.moneygram.com
  const host = "sandboxapi.moneygram.com";
  const url = `https://${host}/transfer/v1/stagedtransactions/${transactionId}/commit`;

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

  const request = {
    fundingSource: {
      tenderType: "CASH",
      provider: "your_provider_name",
      providerNetworkCode: "provider_network_code",
      providerAccountNumber: "provider_account_number",
      accountIdentifier: "mgi_consumer_account_id"
    },
    partnerTransactionId: "your_unique_partner_session_id",
    partnerSettlementId: "your_settlement_id", // Required for real-time settlement
    additionalDetails: [
      { key: "customKey", value: "customValue" }
    ]
  };

  try {
    const response = await axios.put(url, request, { headers });
    const { referenceNumber, fundsInStoreConfirmationCode,
            expectedPayoutDate, commitReceipt } = response.data;
    console.log("Reference Number:", referenceNumber);
    console.log("Confirmation Code:", fundsInStoreConfirmationCode);
    console.log("Expected Payout:", expectedPayoutDate);
    console.log("Agent Receipt:", commitReceipt?.agentHyperLink);
    console.log("Consumer Receipt:", commitReceipt?.consumerHyperLink);
  } catch (error) {
    if (error.response) {
      console.log('Status:', error.response.status);
      console.log('Body:', error.response.data);
    } else {
      console.error('Error:', error.message);
    }
  }
};

commitStagedTransaction();
import requests, uuid

def commit_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/{transaction_id}/commit"

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

    payload = {
        "fundingSource": {
            "tenderType": "CASH",
            "provider": "your_provider_name",
            "providerNetworkCode": "provider_network_code",
            "providerAccountNumber": "provider_account_number",
            "accountIdentifier": "mgi_consumer_account_id"
        },
        "partnerTransactionId": "your_unique_partner_session_id",
        "partnerSettlementId": "your_settlement_id",
        "additionalDetails": [
            {"key": "customKey", "value": "customValue"}
        ]
    }

    resp = requests.put(url, json=payload, headers=headers)
    if resp.ok:
        data = resp.json()
        print("Reference Number:", data.get("referenceNumber"))
        print("Confirmation Code:", data.get("fundsInStoreConfirmationCode"))
        print("Expected Payout:", data.get("expectedPayoutDate"))
        receipt = data.get("commitReceipt", {})
        print("Agent Receipt:", receipt.get("agentHyperLink"))
        print("Consumer Receipt:", receipt.get("consumerHyperLink"))
    else:
        print(f"Error {resp.status_code}:", resp.json())

commit_staged_transaction()
import java.net.http.*;
import java.net.URI;
import java.util.UUID;

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

    String body = """
      {
        "fundingSource": {
          "tenderType": "CASH",
          "provider": "your_provider_name",
          "providerNetworkCode": "provider_network_code",
          "providerAccountNumber": "provider_account_number",
          "accountIdentifier": "mgi_consumer_account_id"
        },
        "partnerTransactionId": "your_unique_partner_session_id",
        "partnerSettlementId": "your_settlement_id",
        "additionalDetails": [
          { "key": "customKey", "value": "customValue" }
        ]
      }""";

    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.

NameHTTP MethodEndpointsDescription
Retrieve EnumerationsGET/reference-data/v1/enumerationsRetrieves enumerated values for fields



API Structure


Header Parameters

FieldTypeRequired
/Optional
Description
X-MG-ClientRequestIdStringRequiredClient 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-ConsumerIPAddressStringOptionalIP 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 Fields

FieldTypeRequired
/Optional
Description
fundingSource.tenderTypeStringOptionalFunding method, based on enumerations
(Enumerated values)
NOTE: For a full list of accepted tenderTypes. See Reference Data Enumerations endpoint
fundingSource.providerStringOptionalName of the payment provider
fundingSource.providerNetworkCodeStringOptionalProviders unique network identifier code
fundingSource.providerAccountNumberStringOptionalAccount number of payment source
fundingSource.accountIdentifierStringOptionalMoneyGram's unique identifier for the consumer account
partnerTransactionId>StringOptionalPartner’s unique session identifier
partnerSettlementIdStringOptionalPartner’s unique identifier for real time settlement only
additionalDetailsDynamicOptionalDynamic field key/values



Response Fields

FieldTypeRequired
/Optional
Description
referenceNumberString
Length: 8
OptionalMoneyGram's reference number for the transaction
fundsInStoreConfirmationCodeStringOptionalMoneyGram's unique confirmation number
expectedPayoutDateString
Format: CCYY-MM-DD
Optional
Length: 10
Date (YYYY-MM-DD)
settlement.reconcileSendAmount.valueNumber
Min length: 0
Max length: 14
Max Decimal Value: 3
OptionalSend Amount to be settled with MoneyGram. This value should be in the same currency as the transaction amount.
settlement.reconcileSendAmount.currencyCodeStringOptionalValue's Currency code (ISO alpha-3 code)
settlement.reconcileReceiveAmount.valueNumber
Min length: 0
Max length: 14
Max Decimal Value: 3
OptionalReceive amount to be settled with MoneyGram. This value should be in the same currency as the transaction amount.
settlement.reconcileReceiveAmount.currencyCodeStringOptionalValue's Currency code (ISO alpha-3 code)
settlement.settlementAccountStringOptionalMoneyGram settlement account/wallet details
settlement.settlementMemoStringOptionalMoneyGram settlement account/wallet memo
partnerReceiptTextInfo.longLanguageCodeStringOptionalLong Language for the receipt
partnerReceiptTextInfo.translationTextStringOptionalTranslation text for the receipt
commitReceipt.agentHyperLinkStringOptionalHyperlink for the agent Receipts
commitReceipt.consuemrHyperLinkStringOptionalHyperlink for the consumer receipts