PUT Update a Staged Transaction
PUT /payout/v1/stagedtransactions/{transactionId}
Development Guide
The 'Update a Transaction' endpoint determines what information to collect from the consumer, validates the data for compliance purposes and updates the transactionId resource with the data collected.
1. Prepare headers, authentication & parameters
The application must call the 'Update a Staged Transaction' endpoint with a PUT HTTP method, providing the OAuth access_token , the transactionId as a path parameter and all other required headers.
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- The
transactionIdshould have been returned on the previous Get Staged Transaction endpoint response.
2. Provide transactionId in the request body:
transactionId in the request body:To Update a staged Transaction, it is required to pass the transactionId and payoutId which was returned on the previous Get Staged Transaction API response and all other required fields at minimum collect the oneOfPayoutStagedRequest, or oneOfPayoutStagedWithAddlnDataRequest for MoneyGram to perform a real-time validation and compliance screening.
Note:
- To understand a full list of REQUIRED and OPTIONAL fields, the application can call the Retrieve transactional send fields API. Learn More
- Additional data collection may be required based on the
receiveAmountanddestinationCountryCode.
3. Make a request and handle response
The application must call the 'Update a staged transaction' endpoint with a PUT HTTP method and be able to handle the following response scenarios:
- Success | Parse the Response | 200 OK HTTP Status |
"readyForCommit": trueWhen the 'Update a transaction' endpoint responds with a 200 HTTP Status the response will return the following fields:readyForCommit, andtransactionId.
- Failed | Handle the Error | 400 Bad Request HTTP Status When the 'Update a transaction' endpoint responds with 400 HTTP Status, 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.
Note:
- In some scenario's, enhanced due diligence is need to be undertaken on the consumer. A specific error code will be returned and an array of offending fields. The fields/values need to be provided and resubmitted on the Update API for further checks
- In some cases, send or receive side taxes may be applied. Learn More
- Only when the
"readyForCommit": true, is returned can the application proceed to "Commit a staged transaction" API and execute the payout of funds.
.
4. You're Done! Proceed to the '[Commit a Staged Transaction API]
The application can call the Commit endpoint to execute the staged payout when a 200 HTTP Success Status is returned from the 'Update a staged transaction' response. The application must use the same transactionId on the subsequent Commit Staged API by providing it as a path parameter. The Commit endpoint is the final API call and will execute the payout.
Note:
- To execute the refund, the
transactionIdreturned in the payload must be persisted and used as a path parameter on subsequent 'Commit a Staged Transaction' API.- To execute the refund, the
payoutIdreturned in the payload must be persisted and used as in the request body of the subsequent 'Commit a Staged Transaction' API.
Business Rules to Code
Making multiple PUT requests to Update the
transactionId: if there are any changes needed for consumer data after the Update a staged transaction endpoint responds, the application should call the Update endpoint to using the sametransactionIdandpayoutIdto provide new consumer/transactional data.
**Enumerated fields: **For all Enumerated Fields (some examples below), agent application must use the valid enumerations returned from the enumerations API response and allow only valid values to be selected. Learn More
*Pre-disclosure: It is regulatory requirement to show pre-disclosure on every transfer, in every country and for every service option. Learn More
Code Examples
const axios = require('axios');
const { v4: uuidv4 } = require('uuid');
const updateTransaction = async () => {
// Step 1: Read configuration values with upmost security
const token = "your_access_token_from_oauth_response"
// For production - api.moneygram.com & For test - sandboxapi.moneygram.com
const transactionId = "current_transaction_id";
const host = "sandboxapi.moneygram.com";
const url = 'https://' + host + '/payout/v1/stagedtransactions/{transactionId}/commit;
// Step 2: Create the PUT request headers, params & body
const headers = {
'Content-Type': 'application/json',
'X-MG-ClientRequestId': uuidv4(), // New UUID for each request tracing
'Authorization': 'Bearer ' + token,
};
const params = {
agentPartnerId: "your_partner_id",
targetAudience: "AGENT_FACING",
userLanguage: "en-US",
}
const request = {
payoutId: "current_payout_id", // generated during the retrieve transaction
receiver: {
address: {
line1: "100 Main St",
city: "Springfield",
countrySubdivisionCode: "US-TX",
countryCode: "USA",
postalCode: "55001"
},
mobilePhone: {
number: "5551231234",
countryDialCode: "1"
},
personalDetails: {
dateOfBirth: "10-10-1998",
birthCountryCode: "USA"
},
primaryIdentification: {
typeCode: "DRV",
id: "123456789",
issueCountrySubdivisionCode: "US-TX",
issueCountryCode: "USA",
}
}
}
try {
// Step 3: Send the request and obtain the response
axios.put(url, request, { params, headers })
.then(function (response) {
// Step 4: Parse the success response and process further
// Verify readyForCommit is true, if yes, transaction is ready to commit
console.log(JSON.stringify(response.data, null, 2))
})
.catch(function (error) {
// Step 5: Parse the error response and handle the errors
if (error.response) {
console.log('Response status:', error.response.status);
console.log('Response body:', error.response.data);
} else {
// TODO: handle generic errors
console.error('Error:', error.message);
}
});
} catch (error) {
// TODO: handle exception
console.error('Error:', error.message);
}
};
updateTransaction();import requests
import uuid
import json
def update_transaction():
# Step 1: Read configuration values with upmost security
token = "your_access_token_from_oauth_response"
# For production - api.moneygram.com & For test - sandboxapi.moneygram.com
transactionId = "current_transaction_id";
host = "sandboxapi.moneygram.com";
url = 'https://' + host + '/payout/v1/transactions/'+ transactionId;
# Step 2: Create the PUT request headers, params & body
headers = {
'Content-Type': 'application/json',
'X-MG-ClientRequestId': str(uuid.uuid4()), # New UUID for each request tracing
'Authorization': 'Bearer ' + token,
}
params = {
'agentPartnerId': 'your_partner_id',
'targetAudience': 'AGENT_FACING',
'userLanguage': 'en-US',
}
request = {
'payoutId': "current_payout_id", # generated during the retrieve transaction
'receiver': {
'address': {
'line1': "100 Main St",
'city': "Springfield",
'countrySubdivisionCode': "US-TX",
'countryCode': "USA",
'postalCode': "55001"
},
'mobilePhone': {
'number': "5551231234",
'countryDialCode': "1"
},
'personalDetails': {
'dateOfBirth': "10-10-1998",
'birthCountryCode': "USA"
},
'primaryIdentification': {
'typeCode': "DRV",
'id': "123456789",
'issueCountrySubdivisionCode': "US-TX",
'issueCountryCode': "USA",
}
}
}
try:
# Step 3: Send the request and obtain the response
response = requests.put(url, json=request, headers=headers)
# Step 4: Parse the success response and process further
if response.status_code == 200:
parsed_response = json.dumps(json.loads(response.text), indent=2)
print(parsed_response)
else:
# Step 5: Parse the error response and handle the errors
print("Request failed with status code:", response.status_code)
print(json.dumps(json.loads(response.text), indent=2))
except requests.exceptions.RequestException as e:
# Print any error that occurred during the request
# TODO: handle exception
print("An error occurred:", e)
update_transaction()
package payout;
import javax.json.Json;
import javax.json.JsonObject;
import javax.json.JsonObjectBuilder;
import javax.json.JsonWriter;
import java.io.StringWriter;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.UUID;
public class UpdateTransaction {
public static void main(String[] args) {
// Step 1: Read configuration values with upmost security
String token = "your_access_token_from_oauth_response";
// For production - api.moneygram.com & For test - sandboxapi.moneygram.com
String host = "sandboxapi.moneygram.com";
String transactionId = "current_transaction_id";
String uri = "https://" + host + "/payout/v1/transactions/" + transactionId;
// Step 2: Create the PUT request headers & body
// Create a JSON object
JsonObjectBuilder receiverBuilder = Json.createObjectBuilder()
.add("address", Json.createObjectBuilder().add("line1", "100 Main St").add("city", "Springfield")
.add("countryCode", "USA").add("countrySubdivisionCode", "US-TX").add("postalCode", "55001"))
.add("mobilePhone", Json.createObjectBuilder().add("number", "5551231234").add("countryDialCode", "1"))
.add("personalDetails", Json.createObjectBuilder().add("dateOfBirth", "10-10-1998").add("birthCountryCode", "USA"))
.add("primaryIdentification", Json.createObjectBuilder().add("typeCode", "DRV").add("id", "123456789").add("issueCountryCode", "USA").add('issueCountrySubdivisionCode': "US-TX"));
JsonObjectBuilder requestBuilder = Json.createObjectBuilder()
.add("payoutId", "current_payout_id")
.add("agentPartnerId", "your_partner_id")
.add("targetAudience", "AGENT_FACING")
.add("userLanguage", "en-US")
.add("receiver", receiverBuilder)
JsonObject jsonObject = requestBuilder.build();
// Create a StringWriter to write the JSON string
StringWriter stringWriter = new StringWriter();
try (JsonWriter jsonWriter = Json.createWriter(stringWriter)) {
jsonWriter.writeObject(jsonObject);
}
// Get the JSON string from the StringWriter
String jsonString = stringWriter.toString();
HttpClient httpClient = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(uri))
.PUT(HttpRequest.BodyPublishers.ofString(jsonString))
.setHeader("Authorization", "Bearer " + token)
.setHeader("X-MG-ClientRequestId", String.valueOf(UUID.randomUUID()))
.build();
try {
// Step 3: Send the request and obtain the response
HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
// Retrieve the status code and body from the response
int statusCode = response.statusCode();
// Step 4: Parse the success response and process further
if (statusCode == 200) {
String responseBody = response.body();
System.out.println(responseBody);
} else {
// Step 5: Parse the error response and handle the errors
String responseBody = response.body();
System.out.println(responseBody);
}
} catch (Exception e) {
e.printStackTrace();
// TODO: handle exception
}
}
}
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 Countries | GET | /reference-data/v1/Country | Retrieves supported values and metadata for countries |
| Retrieve Countries ISO3 | GET | /reference-data/v1 /countries/{iso3Code} | Retrieves supported values and metadata for countries by ISO 3 Code |
| Retrieve Currencies | GET | /reference-data/v1/currencies | Retrieves supported values and metadata for currencies |
| Retrieve Enumerations | GET | /reference-data/v1/enumerations | Retrieves enumerated values for fields |
| Retrieve Identification Documents | GET | /reference-data/v1/identification-Documents | Retrieves required fields for identification documents |
| Retrieve Service Options | GET | /reference-data/v1/payout-options | Retrieves supported values and metadata for Service Options |
API Structure
Header parameters
| Name | Type | Required /Optional | Description |
|---|---|---|---|
X-MG-ClientRequestId | String | Optional | 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-SessionId | String | Conditionally Required | A GUID MoneyGram generates for correlating multiple calls within a transaction session. Note: The X-MG-SessionId is not required if the payoutId is passed in the request body. |
X-MG-ConsumerIPAddress | String | Optional | IP address of the system initiating the session. |
Query parameters
| Field | Type | Required/ Optional | Description |
|---|---|---|---|
targetAudience | String | Optional | 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 |
userLanguage | String | Required | Language used by the user/operator. |
agentPartnerId | String | Required | Unique agent or partner identifier. |
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. |
Path parameters
| Field | Type | Required/ Optional | Description |
|---|---|---|---|
transactionId | String | Required | Unique identifier for the transaction resource. |
Request body for Payout Staged Request
| Field | Type | Required/ Optional |
|---|---|---|
payoutId | String | Conditionally Required |
Request body for Payout Staged with additional Data
| Field | Type | Required/ Optional | Description |
|---|---|---|---|
payoutId | String | Conditionally Required | Unique identifier for the transaction session Note: The payoutId is not required if the X-MG-SessionId is passed as a header parameter. |
receiver.address.line1 | String Min length: 5 Max length: 30 | Required | Residence address line 1 |
receiver.address.line2 | String Min length: 0 Max length: 80 | Optional | Residence address line 2 (if applicable) |
receiver.address.line3 | String Min length: 0 Max length: 80 | Optional | Residence address line 3 (if applicable) |
receiver.address.city | String Min length: 1 Max length: 20 | Required | City of residence |
receiver.address.countrySubdivisionCode | String Length: 6 | Optional | State/province of residence |
receiver.address.countryCode | String Length: 3 | Required | Country of residence (ISO Alpha-3 Code) |
receiver.address.postalCode | String Min length: 2 Max length: 10 | Optional | Postal code/ZIP code of residence |
receiver.mobilePhone.number | String Min length: 5 Max length: 14 | Optional | Phone number |
receiver.mobilePhone.countryDialCode | String Min length: 1 Max length: 3 | Optional | Country calling code (ISO alpha-3 code) |
receiver.email | String Min length: 1 Max length: 255 | Optional | Email address |
receiver.notificationPreferences.type | String | Optional | Type of notification content (Enumerated values) |
receiver.notificationPreferences.channel | String | Optional | Delivery method of notification (Enumerated value) |
receiver.notificationPreferences.optIn | Boolean | Optional | Flag to declare consumer opts in to notification type and method |
receiver.notificationLanguagePreference | String Max length: 6 | Optional | Language ISO Alpha-3 code |
receiver.personalDetails.genderCode | String | Optional | Gender (Enumerated value) |
receiver.personalDetails.dateOfBirth | String Length: 10 | Required | Date of birth (YYYY-MM-DD) |
receiver.personalDetails.birthCity | String Min length: 0 Max length: 20 | Optional | City of birth |
receiver.personalDetails.birthCountryCode | String Max Length: 3 | Required | Country of birth (ISO alpha-3 code) NOTE: For a full list of accepted birth.CountryCodes see ‘Reference data API module’ and the countryInfo endpoint: |
receiver.personalDetails.citizenshipCountryCode | String Max Length: 3 | Optional | Occupation/Employment (Enumerated value) |
receiver.personalDetails.occupationCode | String | Optional | Occupation/Employment (Enumerated value) NOTE: For a full list of accepted Occupation Codes. See the OCCUPATION enumeration from the Reference Data Enumerations endpoint |
receiver.personalDetails.politicalExposedPerson | Boolean | Optional | Flag to declare a Politically Exposed Person (PEP) |
receiver.personalDetails.nationalityCountryCode | String Min Length: 3 Max Length: 3 | Optional | Country of citizenship (ISO alpha-3 code) |
receiver.personalDetails.nationalityCountryCode | String Min Length: 3 Max Length: 3 | Optional | Country of citizenship (ISO alpha-3 code) |
receiver.primaryIdentification.typeCode | String | Required | Type of identification document (Enumerated value) |
receiver.primaryIdentification.id | String Max length: 30 | Required | Identification document number |
receiver.primaryIdentification.issueCountrySubdivisionCode | String Max length: 6 | Optional | Issuing state/province of identification document |
receiver.primaryIdentification.issueCountryCode | String Max Length: 3 | Required | Issuing country of identification document |
receiver.primaryIdentification.expirationYear | String Length: 4 Format: YYYY | Optional | Expiration year of identification document (YYYY) |
receiver.primaryIdentification.expirationMonth | String Length: 4 Format: MM | Optional | Expiration month of identification document (MM) |
receiver.primaryIdentification.expirationDay | String Length: 4 Format: DD | Optional | Expiration month of identification document (DD) |
receiver.primaryIdentification.issueAuthority | String Min length: 0 Max length: 30 | Optional | Issuing authority of identification document |
receiver.primaryIdentification.issueCity | String Min length: 0 Max length: 20 | Optional | Issuing city of identification document |
receiver.primaryIdentification.issueYear | String Length: 4 Format: YYYY | Optional | Issuing year of identification document (YYYY) |
receiver.primaryIdentification.issueMonth | String Length: 4 Format: MM | Optional | Issuing month of identification document (MM) |
receiver.primaryIdentification.issueDay | String Length: 4 Format: DD | Optional | Issuing day of identification document (DD) |
receiver.secondaryIdentification.typeCode | String Max length: 3 | Required | Type of identification document (Enumerated value) |
receiver.secondaryIdentification.id | String Max length: 30 | Required | Identification document number |
receiver.secondaryIdentification.issueCountrySubdivisionCode | String Max length: 6 | Optional | Issuing state/province of identification document |
receiver.secondaryIdentification.issueCountryCode | String Max length: 3 | Required | Issuing country of identification document |
receiver.secondaryIdentification.expirationYear | String Length: 4 Format: YYYY | Optional | Expiration year of identification document (YYYY) |
receiver.secondaryIdentification.expirationMonth | String Length: 4 Format: MM | Optional | Expiration month of identification document (MM) |
receiver.secondaryIdentification.expirationDay | String Length: 4 Format: DD | Optional | Expiration month of identification document (DD) |
receiver.secondaryIdentification.issueAuthority | String Min length: 0 Max length: 30 | Optional | Issuing authority of identification document |
receiver.secondaryIdentification.issueCity | String Min length: 0 Max length: 20 | Optional | Issuing city of identification document |
receiver.secondaryIdentification.issueYear | String Length: 4 Format: YYYY | Optional | Issuing year of identification document (YYYY) |
receiver.secondaryIdentification.issueMonth | String Length: 4 Format: MM | Optional | Issuing month of identification document (MM) |
receiver.secondaryIdentification.issueDay | String Length: 4 Format: DD | Optional | Issuing day of identification document (DD) |
receiver.additionalAddress.type | String | Optional | Type of additional address (Enumerated values) |
receiver.additionalAddress.line1 | String Min length: 5 Max length: 30 | Required | Residence address line 1 |
receiver.additionalAddress.line2 | String Min length: 0 Max length: 30 | Optional | Residence address line 2 (if applicable) |
receiver.additionalAddress.line3 | String Min length: 0 Max length: 30 | Optional | Residence address line 3 (if applicable) |
receiver.additionalAddress.city | String Min length: 0 Max length: 20 | Required | City of residence |
receiver.additionalAddress.countrySubdivisionCode | String Max Length: 6 | Optional | State/province of residence |
receiver.additionalAddress.countryCode | String Max length: 3 | Required | Country of residence (ISO Alpha-3 Code) |
receiver.additionalAddress.postalCode | String Min length: 2 Max length: 6 | Optional | Postal code/ZIP code of residence |
receiver.additionalFamilyNames.type | String | Optional | Type of family name (Enumerated values) |
receiver.additionalFamilyNames.firstName | String Min length: 0 Max length: 20 | Optional | First name |
receiver.additionalFamilyNames.middleName | String Min length: 0 Max length: 20 | Optional | Middle name (if applicable) |
receiver.additionalFamilyNames.lastName | String Min length: 0 Max length: 30 | Optional | Last name |
receiver.additionalFamilyNames.secondLastName | String Min length: 0 Max length: 30 | Optional | Second last name |
receiver.profileId | String | Optional | Consumer's unique identifier |
receiver.additionalDetails | Dynamic | Optional | Dynamic field/key value |
relationshipToSender | String Max length: 30 | Optional | Receiver’s relationship to sender based on (Enumerated Values) NOTE: For a full list of accepted relationship to sender values. See the RELATIONSHP_TO_SNDR enumeration from the Reference Data Enumerations endpoint |
receivePurposeOfTransaction | String Max length: 50 | Optional | Receiver’s purpose for the transaction (Enumerated Values) NOTE: For a full list of accepted purpose of transaction values. See the PURPSE_OF_TRNSCTION enumeration from the Reference Data Enumerations endpoint |
intendedUseOfMGIServices | String Max length: 50 | Optional | Receiver’s intended use of MGI services (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 |
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 |
Response fields
| Field | Type | Required/ Optional | Description |
|---|---|---|---|
readyForCommit | Boolean | Required | Indicates whether the transaction can proceed to commit |
transactionId | String Max length: 36 | Required | Unique identifier for the transaction resource |
Updated 2 days ago
