GET Retrieve Service Options

GET /reference-data/v1/service-options

Development Guide

Retrieves superset of applicable service options to use with MoneyGram API Integrations. This is to provide a reference during development as well as to enable implementors to cache the set of enumerations. If a field is an enumerated datatype, the values returned in this API are the only accepted data for the field.


1. Prepare headers & authentication:

Call the 'Retrieve Service Options' endpoint with a GET 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 Code Example:

👉 Reference Data - Retreive Service Options - Headers




2. Provide destinationCountryCode as query parameter.

The application must provide the destinationCountryCodeas a query parameter.

Note: If the destinationCountryCode is not provided the Retrieve Service Options API will return all service options for all countries.


🚀

Launch Code Example:

👉 Reference Data - Retreive Service Options - destinationCountryCode




3. Make the request and handle the response:

The application will call the 'Retrieve Service Options' endpoint with a GET HTTP method. The 'Retrieve Service Options' will generate a response with an array of service options for the destination country. The application must build to handle the following response scenarios.


  • Success | Parse the Response | 200 OK HTTP Status
    When the 'Retrieve Service Options' endpoint responds with a 200 HTTP Status. An array service options will be returned for the destination country.

  • Success | Retrieve Service Options has no content | 204 No Content HTTP Status
    When the 'Retrieve Service Options' endpoint responds with 204 HTTP Status. The 'Retrieve Service Options' endpoint API will return a message of "Content not found".


🚀

Launch Code Example:

👉 Reference Data - Retreive Service Options - 200 OK

👉 Reference Data - Retreive Service Options - 204 Content Not Found





Code Examples

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

const serviceOptions = 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";
    const url = 'https://' + host + '/reference-data/v1/service-options';

    // Step 2: Create the GET request headers & params
    const headers = {
        'Content-Type': 'application/json',
        'X-MG-ClientRequestId': uuidv4(), // New UUID for each request tracing
        'Authorization': 'Bearer ' + token,
    };

    const params = {
        targetAudience: "AGENT_FACING",
        agentPartnerId: "your_partner_id",
        userLanguage: "en-US",
        destinationCountryCode: "USA"
    }

    try {
        // Step 3: Send the request and obtain the response
        axios.get(url, { 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);
    }
};

serviceOptions();
import requests
import uuid
import json

def service_options():

    # 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";
    url = 'https://' + host + '/reference-data/v1/service-options';

    # Step 2: Create the GET request headers & params
    headers = {
        'Content-Type': 'application/json',
        'X-MG-ClientRequestId': str(uuid.uuid4()), # New UUID for each request tracing
        'Authorization': 'Bearer ' + token,
    }

    params = {
        'targetAudience': 'AGENT_FACING',
        'agentPartnerId': 'your_partner_id',
        'userLanguage': 'en-US',
        'destinationCountryCode': "USA"
    }

    try:
        # Step 3: Send the request and obtain the response
        response = requests.get(url, params=params, 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:
            # Print the error message if request fails
            # TODO: handle exception
            print("Request failed with status code:", response.status_code)
            print(json.loads(json.dumps(response.text, indent=4)))

    except requests.exceptions.RequestException as e:
        # Print any error that occurred during the request
        # TODO: handle exception
        print("An error occurred:", e)

service_options()
package status;

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

    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 GET request headers & params
        // Mandatory Query params
        String agentPartnerId = "your_partner_id";
        String userLanguage = "en-US";
        String destinationCountryCode = "USA";

        // Optional Query params
        String targetAudience = "AGENT_FACING";

        String uri = "https://" + host + "/reference-data/v1/service-options?"
                + "agentPartnerId=" + agentPartnerId
                + "&userLanguage=" + userLanguage
                + "&destinationCountryCode=" + destinationCountryCode
                + (targetAudience.isBlank() ? "" : "&targetAudience=" + targetAudience);

        HttpClient httpClient = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(uri))
                .GET()
                .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
        }

    }
}

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. MoneyGram recommends using a UUID for this field value.



Query Parameters

FieldTypeRequired/OptionalDescription
targetAudienceStringOptionalTailors 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
agentPartnerIdStringOptionalUnique agent or partner identifier
userLanguageStringRequiredLanguage used by the user/operator
destinationCountryCodeStringOptionalTransaction Destination Country (ISO alpha-3 code)



Response Fields

FieldTypeRequired/OptionalDescription
destinationCountryCodeStringOptionalTransaction Destination Country (ISO alpha-3 code)
serviceOptions.serviceOptionArrayOptionalMoneyGrams' unique category code to identify the transaction method
serviceOptions.serviceOptionCodeString
Max length: 21
RequiredUnique category code to identify the transaction method
serviceOptions.serviceOptions.serviceOptionNameStringRequiredConsumer facing name to identify the transaction method
serviceOptions.serviceOptionRoutingCodeStringOptionalUnique code to identify the individual transaction method
serviceOptions.serviceOptionRoutingNameStringOptionalUnique name to identify the individual transaction method
serviceOptions.destinationCurrencyCodeStringOptionalTransaction Destination Country (ISO alpha-3 code)
serviceOptions.partnerIdStringOptionalUnique partner identifier
serviceOptions.serviceOptionDisplayDescriptionStringOptionalDescription of service option
serviceOptions.serviceOptionCategoryIdStringOptionalUnique identifier for the account deposit delivery option
serviceOptions.serviceOptionCategoryDisplayNameStringOptionalDisplay name of the account deposit delivery option category
serviceOptions.minReceiveAmtNumberOptionalMinimum receive amount for the selected destination
Note: A minimum amount will be returned only if one has been set for the selected destination.
serviceOptions.maxReceiveAmtNumberOptionalMaximum receive amount for the selected destination
serviceOptions.localCurrencyStringOptionalDefault currency for the country (ISO Alpha-3)
serviceOptions.indicativeRateAvailableBooleanOptionalIndicates if indicative Fx rates are available in the country

NOTE: For more information on Indicative countries see Guaranteed and Estimated Fx Rate