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_tokenby 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:
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 fieldsreferenceNumber,fundsInStoreConfirmationCodeandexpectedPayoutDate. 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
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
transactionStatususing the Status API to confirm if transaction was successful.**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).
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
Receipts: Refer to Receipts module for detailed information and requirements for receipts.
**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.
| Name | HTTP Method | Endpoints | Description |
|---|---|---|---|
| Retrieve Enumerations | GET | /reference-data/v1/enumerations | Retrieves 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 | Description |
|---|---|---|---|
| String | Required | Unique id of the transaction resource |
Request Body Fields
| Field | Type | Required /Optional | Description |
|---|---|---|---|
fundingSource.tenderType | String | Optional | Funding method, based on enumerations (Enumerated values) NOTE: For a full list of accepted tenderTypes. See Reference Data Enumerations endpoint |
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 | MoneyGram's unique identifier for the consumer account |
partnerTransactionId> | String | Optional | Partner’s unique session identifier |
partnerSettlementId | String | Optional | Partner’s unique identifier for real time settlement only |
additionalDetails | Dynamic | Optional | Dynamic field key/values |
Response Fields
| Field | Type | Required /Optional | Description |
|---|---|---|---|
referenceNumber | String Length: 8 | Optional | MoneyGram's reference number for the transaction |
fundsInStoreConfirmationCode | String | Optional | MoneyGram's unique confirmation number |
expectedPayoutDate | String Format: CCYY-MM-DD | Optional Length: 10 | Date (YYYY-MM-DD) |
settlement.reconcileSendAmount.value | Number Min length: 0 Max length: 14 Max Decimal Value: 3 | Optional | Send Amount to be settled with MoneyGram. This value should be in the same currency as the transaction amount. |
settlement.reconcileSendAmount.currencyCode | String | Optional | Value's Currency code (ISO alpha-3 code) |
settlement.reconcileReceiveAmount.value | Number Min length: 0 Max length: 14 Max Decimal Value: 3 | Optional | Receive amount to be settled with MoneyGram. This value should be in the same currency as the transaction amount. |
settlement.reconcileReceiveAmount.currencyCode | String | Optional | Value's Currency code (ISO alpha-3 code) |
settlement.settlementAccount | String | Optional | MoneyGram settlement account/wallet details |
settlement.settlementMemo | String | Optional | MoneyGram settlement account/wallet memo |
partnerReceiptTextInfo.longLanguageCode | String | Optional | Long Language for the receipt |
partnerReceiptTextInfo.translationText | String | Optional | Translation text for the receipt |
commitReceipt.agentHyperLink | String | Optional | Hyperlink for the agent Receipts |
commitReceipt.consuemrHyperLink | String | Optional | Hyperlink for the consumer receipts |
Updated 1 day ago
