Development Guide

The 'Modify Receiver Additional Data' endpoint can be used to amend the transactionId resource with new information about the receiver. The new receiver data submitted will be re-screened and used to clear any "compliance hold" that may be on the transaction. The endpoint will respond synchronously with a success or fail of any compliance re-screening.

1. Prepare headers & authentication:

The application must call the 'Modify Receiver Additional Information' 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 accessToken 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 modify the receiver's additional data, 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 the receivers additional information, 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 the additional `receiver` information in the request body:

The application can provide the following receiver additional information in the request body: mobilePhone, genderCode, dateOfBirth, birthCity, birthCountryCode, citizenshipCountryCode, occupationCode, politicalExposedPerson, familyDetails.

Note: The API will allow you to provide one or all fields. MoneyGram recommended collecting as much receiver information as possible to clear any compliance HOLD.

🚀
Launch Example Code:

5. Make a request and handle response:

The application must call 'Modify Receiver Additional Information' endpoint with a PATCH HTTP method. The endpoint will respond with following scenarios:

Success | Parse the Response | "amendSuccess": true | "Status": "AVAILABLE"

When the 'Amend Receiver Additional-Data endpoint responds with a 200 HTTP Status and the "amendSuccess": true, the transaction has been successfully amended and re-screening is passed. The new transaction will be returned "Status": "Available".

Failed | Parse the Response | 200 OK HTTP Status | "amendSuccess": false | "Status": "PROCESSING"
When the 'Amend Receiver Additional-Data' endpoint responds with a 200 HTTP Status and the "amendSucces": false, the transaction has been unsuccessful updated and re-screening was not passed. The transaction will remain "Status": "PROCESSING" and the subStatus will also be returned.

Failed | Handle the Error | 400 BAD REQUEST HTTP Status

When the 'Amend Receiver Additional-Data' 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 Additonal Data Confirmation" on the application UI.

Business Rules to Code

🔎
Condition to allow amend:

To Modify Receiver Additional Data: The transaction must be an "PROCESSING" status.

**Using Webhooks & Status API:**MoneyGram will need further receiver data to re-screen and clear the transaction. MoneyGram Webhooks or Status API will notify you of any held transaction and the receiver information needed to rescreen and release the transaction.
Retrieving a transactionId:If the application does not store the transactionId, it can be retrieved using the refund/v1/transactions/?referenceNumber={referenceNumber} endpoint
Handling Timeout & Retry: If application experiences a "timeout" during commit you can retry the Commit transaction endpoint.
Limit on Additional Amend: API allows to amend the additional data associated with a record only once. Subsequent amendments are not permitted.

Code Examples

const axios = require('axios');
const { v4: uuidv4 } = require('uuid');

const modifyReceiverAdditionalData = 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/additional-data';

    const request = {
        'receiver': {
                'mobilePhone': {
                'number': '4592694333',
                'countryDialCode': '1'
            },
            'personalDetails': {
                'genderCode': 'MALE',
                'dateOfBirth': '1999-07-19',
                'birthCity': 'Albuquerque',
                'birthCountryCode': 'USA',
                'citizenshipCountryCode': 'USA',
                'occupationCode': 'ADMIN',
                'politicalExposedPerson': false
            },
            'familyDetails': [
                {
                    'type': 'FATHER_S_NAME',
                    'firstName': 'John',
                    'middleName': 'Jacob',
                    'lastName': 'Smith',
                }
            ]
        }
    }

    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);
    }
};

modifyReceiverAdditionalData();

import requests
import uuid
import json

def modifyReceiverAdditionalData():

    # 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/additional-data';

    # 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': {
                'mobilePhone': {
                'number': '4592694333',
                'countryDialCode': '1'
            },
            'personalDetails': {
                'genderCode': 'MALE',
                'dateOfBirth': '1999-07-19',
                'birthCity': 'Albuquerque',
                'birthCountryCode': 'USA',
                'citizenshipCountryCode': 'USA',
                'occupationCode': 'ADMIN',
                'politicalExposedPerson': False
            },
            'familyDetails': [
                {
                    'type': 'FATHER_S_NAME',
                    'firstName': 'Roger',
                    'middleName': 'Kite',
                    'lastName': 'Walters',
                    'secondLastName': 'Junior'
                }
            ],
            'additionalDetails': [      
            ]
        }
    }

    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)

modifyReceiverAdditionalData()

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 ModifyReceiverAdditionalData {

    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/additional-data" + "?"
                + "agentPartnerId=" + agentPartnerId
                + "&targetAudience=" + targetAudience
                + "&userLanguage=" + userLanguage;

        // Create a JSON object
        JsonObjectBuilder requestBuilder = Json.createObjectBuilder()
                .add("receiver",
                        Json.createObjectBuilder().add("mobilePhone",
                                        Json.createObjectBuilder().add("number", "4592694333")
                                                .add("countryDialCode", "1"))
                                .add("personalDetails",
                                        Json.createObjectBuilder().add("genderCode", "MALE")
                                                .add("dateOfBirth", "1999-07-19")
                                                .add("birthCity", "Albuquerque")
                                                .add("birthCountryCode", "USA")
                                                .add("citizenshipCountryCode", "USA")
                                                .add("occupationCode", "ADMIN")
                                                .add("politicalExposedPerson", false))
                                .add("familyDetails",
                                        Json.createArrayBuilder().add(Json.createObjectBuilder().add("type", "FATHER_S_NAME")
                                                .add("firstName", "Roger")
                                                .add("middleName", "Kite")
                                                .add("lastName", "Walters")
                                                .add("secondLastName", "Junior")))
                                .add("additionalDetails", Json.createArrayBuilder()));

        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.
`X-MG-SessionId`	String	Required	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
`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

Field	Type	Required/Optional	Description
`amendId`	String Min length: 35 Max length: 35	Required	Amend Id from Lookup
`receiver.address.line1`	String Min length: 5 Max length: 30	Optional	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	Conditionally Required	City of residence
`receiver.address.countrySubdivisionCode`	String Max length: 6	Optional	State/province of residence
`receiver.address.countryCode`	String Max length: 3	Conditionally Required	Country of residence (ISO Alpha-3 Code)
`receiver.address.postalCode`	String Min length: 2 Max length: 6	Optional	Postal code/ZIP of residence
`receiver.mobilePhone.number`	String Min length: 5 Max length: 14	Optional	Primary phone number
`receiver.mobilePhone.countryDialCode`	String Min length: 1 Max length: 3	Optional	Country dial code (Enumerated Values) NOTE: For country calling code see Reference Data API Module /countries endpoint `phoneDialCodes`
`receiver.personalDetails.genderCode`	String minLength: 0 maxLength: 30	Optional	Gender (Enumerated Values) NOTE: For gender code see Reference Data API Module /enumerations endpoint `GENDER`
`receiver.personalDetails.dateOfBirth`	String Length: 10	Required	Date of birth (CCYY-MM-DD)
`receiver.personalDetails.birthCity`	String Min length: 1 Max length: 20	Optional	City of birth
`receiver.personalDetails.birthCountryCode`	String Max Length: 3	Required	Country of birth (ISO alpha-3 code) For a full list of accepted birth.CountryCodes see Reference Data API Module: Retrieve Countries ISO3 endpoint
`receiver.personalDetails.citizenshipCountryCode`	String Max Length: 3	Optional	Citizenship Country (ISO alpha-3 code) NOTE: For a full list of accepted countries and supported destination country subdivision codes see Reference Data API Module: Retrieve Countries ISO3 endpoint
`receiver.personalDetails.occupationCode`	String Min Length: 0 Max Length: 30	Optional	Occupation/Employment code (Enumerated Values) For a full list of accepted occupation codes see Reference Data API and the enumerations endpoint OCCUPATION
`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.email`	String Min length: 1 Max length: 255	Optional	Email Address
`receiver.familyDetails.type`	String	Optional	Type of family details Values: FATHER_S_NAME MOTHER_S_NAME SIBLING_S_NAME NAME_AT_BIRTH MOTHER_S_MAIDEN_NAME GRANDFATHER_S_NAME
`receiver.familyDetails.firstName`	String Min Length: 1 Max Length: 20	Optional	First Name
`receiver.familyDetails.middleName`	String Min Length: 1 Max Length: 20	Optional	Middle Name (if applicable)
`receiver.familyDetails.lastName`	String Min Length: 1 Max Length: 30	Optional	Last Name
`receiver.familyDetails.secondLastName`	String Min Length: 1 Max Length: 30	Optional	Second Last Name (if applicable)
`receiver.additionalDetails`	Dynamic	Optional	Dynamic field key/values

Response Fields

Name	Type	Required/Optional	Description
`amendSuccess`	Boolean	Optional	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.