PATCH Modify Receiver Additional Data

PATCH /amend/v1/transactions/{transactionId}/receiver/additional-data

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

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

Query Parameters

FieldTypeRequired/ OptionalDescription
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
posIdStringOptionalPoint of sale identifier of the client performing the API Call
operatorIdString Max length: 80RequiredOperator 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/ OptionalDescription
transactionIdStringRequiredUnique identifier for the transaction resource

Request Body

FieldTypeRequired/OptionalDescription
amendIdString Min length: 35 Max length: 35RequiredAmend Id from Lookup
receiver.address.line1String Min length: 5 Max length: 30OptionalResidence address line 1
receiver.address.line2String Min length: 0 Max length: 80OptionalResidence address line 2 (if applicable)
receiver.address.line3String Min length: 0 Max length: 80OptionalResidence address line 3 (if applicable)
receiver.address.cityString Min length: 1 Max length: 20Conditionally RequiredCity of residence
receiver.address.countrySubdivisionCodeString Max length: 6OptionalState/province of residence
receiver.address.countryCodeString Max length: 3Conditionally RequiredCountry of residence (ISO Alpha-3 Code)
receiver.address.postalCodeString Min length: 2 Max length: 6OptionalPostal code/ZIP of residence
receiver.mobilePhone.numberString Min length: 5 Max length: 14OptionalPrimary phone number
receiver.mobilePhone.countryDialCodeString Min length: 1 Max length: 3OptionalCountry dial code (Enumerated Values) NOTE: For country calling code see Reference Data API Module /countries endpoint phoneDialCodes
receiver.personalDetails.genderCodeString minLength: 0 maxLength: 30OptionalGender (Enumerated Values) NOTE: For gender code see Reference Data API Module /enumerations endpoint GENDER
receiver.personalDetails.dateOfBirthString Length: 10RequiredDate of birth (CCYY-MM-DD)
receiver.personalDetails.birthCityString Min length: 1 Max length: 20OptionalCity of birth
receiver.personalDetails.birthCountryCodeString Max Length: 3RequiredCountry 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.citizenshipCountryCodeString Max Length: 3OptionalCitizenship 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.occupationCodeString Min Length: 0 Max Length: 30OptionalOccupation/Employment code (Enumerated Values) For a full list of accepted occupation codes see Reference Data API and the enumerations endpoint OCCUPATION
receiver.personalDetails.politicalExposedPersonBooleanOptionalFlag to declare a Politically Exposed Person (PEP)
receiver.personalDetails.nationalityCountryCodeString Min Length: 3 Max Length: 3OptionalCountry of citizenship (ISO alpha-3 code)
receiver.emailString Min length: 1 Max length: 255OptionalEmail Address
receiver.familyDetails.typeStringOptionalType 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.firstNameString Min Length: 1 Max Length: 20OptionalFirst Name
receiver.familyDetails.middleNameString Min Length: 1 Max Length: 20OptionalMiddle Name (if applicable)
receiver.familyDetails.lastNameString Min Length: 1 Max Length: 30OptionalLast Name
receiver.familyDetails.secondLastNameString Min Length: 1 Max Length: 30OptionalSecond Last Name (if applicable)
receiver.additionalDetailsDynamicOptionalDynamic field key/values

Response Fields

NameTypeRequired/OptionalDescription
amendSuccessBooleanOptionalFlag 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.agentHyperLinkStringOptionalHyperlink for the agent receipt (available for five minutes)
receipt.consumerHyperLinkStringOptionalHyperlink for the customer receipt (available for five minutes)