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:




2. Provide the 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:




3. Provide 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:




4. Provide 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:




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:

.




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

FieldTypeRequired
/Optional
Description
X-MG-ClientRequestIdStringOptionalClient 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-SessionIdStringOptionalA GUID MoneyGram generates for correlating multiple calls within a transaction session.
X-MG-ConsumerIPAddressStringOptionalIP Address of the system initiating the session



Query Parameters

FieldTypeRequired
/Optional
Description
targetAudienceStringRequiredTailors 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
userLanguageStringRequiredLanguage used by the operator
agentPartnerIdStringRequiredUnique agent or partner identifier
payoutIdStringOptionalPoint of sale identifier of the client performing the API Call
operatorIdStringOptionalOperator 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

FieldTypeRequired
/Optional
Description
transactionIdString
Max length: 36
RequiredUnique id of the transaction resource



Request Body Fields

NameTypeRequired
/Optional
Description
amendIdStringRequiredUnique identifier for the amend session
receiver.name.firstNameString
Min length: 1
Max length: 20
RequiredFirst Name
receiver.name.middleNameString
Min length: 1
Max length: 20
OptionalMiddle Name (if applicable)
receiver.name.lastNameString
Min length: 1
Max length: 30
RequiredLast Name
receiver.name.secondLastNameString
Min length: 1
Max length: 30
OptionalSecond last name (if applicable)



Response Fields

NameTypeRequired
/Optional
Description
amendSuccessBooleanRequiredFlag that indicates a successful amend
transactionStatusStringOptionalMoneyGram's transaction status
transactionSubStatus.subStatusStringOptionalLatest sub-status of transaction
transactionSubStatus.messageStringOptionalMessage associated with the sub-status code.
transactionSubStatus.targetCustomerStringOptionalCustomer associated with sub-status code
transactionSubStatus.dataToCollect.codeStringOptionalUnique code to identify the data or document to collect
transactionSubStatus.dataToCollect.dataCollectionStringOptionalData or document needed to be collected from customer
receipt.primaryLanguageString
Max length: 6
OptionalPrimary receipt language of the transacting partner.
receipt.secondaryLanguageString
Max length: 6
OptionalSecondary receipt language of the transacting partner.
receipt.imageStringOptionalReceipt image string of the transacting partner.