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 - Headers

Open Recipe

2. Provide `payoutId` in the request body:

To Update a Transaction, it is required to pass the payoutId which was returned on the previous Retrieve a Transaction API response and all other required fields.

🚀
Launch Code Example:

Payout - Update a Transaction - payoutID

Open 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 and destinationCountryCode.

🚀
Launch Code Example:

Payout - Update a Transaction - Request Body

Open 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, and transactionId.

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 Title

Open Recipe

.

Payout - Update a transaction - 400 Bad Request

Open 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 same transactionId and payoutId 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	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
`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: 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	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
`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

Development Guide

1. Prepare headers, authentication & parameters

Launch Code Example:

2. Provide payoutId in the request body:

Launch Code Example:

3. Provide request body:

Launch Code Example:

4. Make a request and handle response

Launch Code Example:

5. You're Done! Proceed to the 'Commit a transaction API'

Business Rules to Code

Code Examples

Support APIs

API Structure

Header parameters

Query parameters

Path parameters

Request body

Response fields

2. Provide `payoutId` in the request body: