PUT Update a Transaction
PUT /payout/v1/transactions/{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 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_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- The
transactionId
should have been returned on the previous Retrieve a tTansaction endpoint response.
Launch Code Example:
👉Payout - Update a Transaction - HeadersOpen Recipe
2. Provide payoutId
in the request body:
payoutId
in the request body:To Update a Transaction, it is required to pass the refundId
which was returned on the previous Retrieve a Transaction API response and all other required fields.
Launch Code Example:
👉Payout - Update a Transaction - payoutIDOpen Recipe
3. Provide request body:
The request body must include the payoutId
that was generated and returned in the previous 'Retrieve a transaction’ endpoint and at a minimum collect the receiver.address
, receiver.primaryIdentification
and receiver.dateOfBirth
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
receiveAmount
anddestinationCountryCode
.
Launch Code Example:
👉Payout - Update a Transaction - Request BodyOpen Recipe
4. Make a request and handle response
The application must call the 'Update a 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": true
When 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 transaction" API and execute the payout of funds.
Launch Code Example:
👉Payout - Update a Transaction - 200 OKcipe TitleOpen Recipe.
👉Payout - Update a transaction - 400 Bad RequestOpen Recipe
5. You're Done! Proceed to the 'Commit a transaction API'
The application can call the Commit endpoint to execute the payout when a 200 HTTP Success Status is returned from the 'Update a transaction' response. The application must use the same transactionId
on the subsequent Commit 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
transactionId
returned in the payload must be persisted and used as a path parameter on subsequent 'Commit a Transaction' API.- To execute the refund, the
payoutId
returned in the payload must be persisted and used as in the request body of the subsequent 'Commit a 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 transaction endpoint responds, the application should call the Update endpoint to using the sametransactionId
andpayoutId
to 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/transactions/' + transactionId;
// 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 | Optional | 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
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: 30 | Optional | Residence address line 2 (if applicable) |
receiver.address.line3 | String Min length: 0 Max length: 30 | 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 |
<code>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 |
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 about 13 hours ago