PATCH Modify Receiver Name
PATCH /amend/v1/transactions/{transactionId}/receiver/name
Development Guide
The 'Modify Receiver Name' endpoint can be used to amend the transactionId
resource with new receiver name details. The endpoint can modify the receiver.firstName
, receiver.middleName
, receiver.lastName
, and receiver.secondLastName
.
1. Prepare headers & authentication:
The application must call the 'Modify Receiver Name' endpoint with a PATCH 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
Launch Example Code:
👉Amend - Modify Recevier's Name - HeadersOpen Recipe
2. Provide the transactionId
as a path parameter:
transactionId
as a path parameter:To commit the Modify Receiver Name, it is required to pass the transactionID
which was returned on the previous Retrieve a Transaction API response and all other required fields.
Launch Example Code:
👉Amend - Modify Recevier's Name - Provide Transaction IDOpen Recipe
3. Provide amendId
in the request body:
amendId
in the request body:To modify a receiver's name, it is required to pass the amendId
which was returned on the previous Retrieve a Transaction API response and all other required fields.
Launch Example Code:
👉Amend - Modify Recevier's Name - Provide Amend IDOpen Recipe
4. Provide receiver.name
details in the request body:
receiver.name
details in the request body:To amend the receiver's name, it is required to pass the receiver.firstName
, receiver.lastName
, and optional to pass the receiver.middleName
, and receiver.secondLastName
.
Launch Example Code:
👉Amend - Modify Recevier's Name - Receiver's NameOpen Recipe
5. Make a request and handle response:
The application must call 'Modify Receiver Name' endpoint with a PATCH HTTP method. The application must build to handle the following response scenarios:
- Success | Parse the Response | 200 OK HTTP Status | "amendSuccess": true
When the 'Modify receiver name' endpoint responds with a 200 HTTP Status the response will typically return"amendSuccess": true
- Failed | Handle the Error | 400 BAD REQUEST HTTP Status
When the 'Modify receiver name' 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 request.
Launch Example Code:
👉Amend - Modify Recevier's Name - 200 OkOpen Recipe.
👉Amend - Modify Recevier's Name - 400 Bad RequestOpen Recipe
6. You're Done! Communicate the "Amend Confirmation" to the customer:
The information returned can be displayed in a "Amend Confirmation" on the application UI.
Business Rules to Code
Condition to allow an amend:
- To Modify the Receiver's Name: The transaction must be in an "AVAILABLE" status.
Handling Timeout & Retry: If application experiences a "timeout" during you can retry the 'Modify Receiver Name' endpoint .
Code Examples
const axios = require('axios');
const { v4: uuidv4 } = require('uuid');
const modifyReceiverName = 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 host = "sandboxapi.moneygram.com";
// Step 2: Create the PATCH request headers, params & body
const headers = {
'Content-Type': 'application/json',
'X-MG-ClientRequestId': uuidv4(), // New UUID for each request tracing
'Authorization': 'Bearer ' + token,
'X-MG-SessionId': 'current_session_id'
};
params = {
'agentPartnerId': 'your_partner_id',
'userLanguage': 'en-US',
'targetAudience': 'AGENT_FACING'
}
const transactionId = "current_transaction_id";
const url = 'https://' + host + '/amend/v1/transactions/' + transactionId + '/receiver/name';
const request = {
'receiver': {
'name': {
'firstName': 'Ricky',
'middleName': 'Livingstone',
'lastName': 'Ben',
'secondLastName': 'Junior'
}
}
}
try {
// Step 3: Send the request and obtain the response
axios.patch(url, request, { params, headers })
.then(function (response) {
// Step 4: Parse the success response and process further
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);
}
};
modifyReceiverName();
import requests
import uuid
import json
def modifyReceiverName():
# 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
host = "sandboxapi.moneygram.com";
transactionId = "current_transaction_id";
url = 'https://' + host + '/amend/v1/transactions/' + transactionId + '/receiver/name';
# Step 2: Create the PATCH request headers, params & body
headers = {
'Content-Type': 'application/json',
'X-MG-ClientRequestId': str(uuid.uuid4()), # New UUID for each request tracing
'Authorization': 'Bearer ' + token,
'X-MG-SessionId': 'current_session_id'
}
params = {
'agentPartnerId': 'your_partner_id',
'userLanguage': 'en-US',
'targetAudience': 'AGENT_FACING',
}
request = {
'receiver': {
'name': {
'firstName': 'Ricky',
'middleName': 'Livingstone',
'lastName': 'Ben',
'secondLastName': 'Junior'
}
}
}
try:
# Step 3: Send the request and obtain the response
response = requests.patch(url, json=request, headers=headers, params=params)
# 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)
modifyReceiverName()
package amend;
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 ModifyReceiverName {
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";
// Step 2: Create the PATCH request headers, params & body
// Mandatory Query params
String agentPartnerId = "your_partner_id";
String targetAudience = "AGENT_FACING";
String userLanguage = "en-US";
// Mandatory Path params
String transactionId = "current_transaction_id";
String uri = "https://" + host + "/amend/v1/transactions/" + transactionId + "/receiver/name" + "?"
+ "agentPartnerId=" + agentPartnerId
+ "&targetAudience=" + targetAudience
+ "&userLanguage=" + userLanguage;
// Create a JSON object
JsonObjectBuilder requestBuilder = Json.createObjectBuilder()
.add("receiver",
Json.createObjectBuilder().add("name",
Json.createObjectBuilder().add("firstName", "Ricky")
.add("middleName", "Livingstone")
.add("lastName", "Ben")
.add("secondLastName", "Junior")));
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))
.method("PATCH", HttpRequest.BodyPublishers.ofString(jsonString))
.setHeader("Authorization", "Bearer " + token)
.setHeader("X-MG-ClientRequestId", String.valueOf(UUID.randomUUID()))
.setHeader("X-MG-SessionId", "current_session_id")
.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
}
}
}
API Structure
Header Parameters
Field | 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 | Optional | A GUID MoneyGram generates for correlating multiple calls within a transaction session. |
X-MG-ConsumerIPAddress | String | Optional | IP Address of the system initiating the session |
Query Parameters
Field | Type | Required /Optional | Description |
---|---|---|---|
targetAudience | String | Required | Tailors MoneyGram’s error messages and field metadata to an in-store, digital or crypto customer. (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 operator |
agentPartnerId | String | Required | Unique agent or partner identifier |
payoutId | 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 Max length: 36 | Required | Unique id of the transaction resource |
Request Body Fields
Name | Type | Required /Optional | Description |
---|---|---|---|
amendId | String | Required | Unique identifier for the amend session |
receiver.name.firstName | String Min length: 1 Max length: 20 | Required | First Name |
receiver.name.middleName | String Min length: 1 Max length: 20 | Optional | Middle Name (if applicable) |
receiver.name.lastName | String Min length: 1 Max length: 30 | Required | Last Name |
receiver.name.secondLastName | String Min length: 1 Max length: 30 | Optional | Second last name (if applicable) |
Response Fields
Name | Type | Required /Optional | Description |
---|---|---|---|
amendSuccess | Boolean | Required | Flag that indicates a successful amend |
transactionStatus | String | Optional | MoneyGram's transaction status |
transactionSubStatus.subStatus | String | Optional | Latest sub-status of transaction |
transactionSubStatus.message | String | Optional | Message associated with the sub-status code. |
transactionSubStatus.targetCustomer | String | Optional | Customer associated with sub-status code |
transactionSubStatus.dataToCollect.code | String | Optional | Unique code to identify the data or document to collect |
transactionSubStatus.dataToCollect.dataCollection | String | Optional | Data or document needed to be collected from customer |
receipt.primaryLanguage | String Max length: 6 | Optional | Primary receipt language of the transacting partner. |
receipt.secondaryLanguage | String Max length: 6 | Optional | Secondary receipt language of the transacting partner. |
receipt.image | String | Optional | Receipt image string of the transacting partner. |
Updated 11 days ago