Overview

Retrieves fields for identification documents. The data returned by the endpoint gives you an overview of primary identifications & secondary identifications supported by a given country and the metadata associated with the document. For example, the API will let you know the ID Type, what other fields to collect with the ID (such as number, issue country and expiry date) and the metadata for each field.

Authentication & Authorization

MoneyGram uses the OAuth 2.0 framework. The application must use their OAuth client credentials to generate an accesstoken and pass it as a header value in subsequent HTTP calls.

Make a Request

The application must invoke API with a HTTP GET method and enter the countryCode and userLanguage as a query parameter to lookup and retrieve a list of Identification Documents and corresponding required fields supported by the given country.
The Retrieve Identification Documents API will respond with an HTTP 200 OK status and an array of Identification documents and enumeration to the given consumer country.

API Request & Response Examples

curl --request GET \
     --url 'https://sandboxapi.moneygram.com/reference-data/v1/identification-documents?targetAudience=AGENT_FACING&agentPartnerId=30150519&userLanguage=EN-US&countryCode=USA' \
     --header 'X-MG-ClientRequestId: 4c79b06f-a2af-4859-82c8-28cbb0bf361b' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ***************************'

[
  {
    "countryCode": "string",
    "primaryIdentifications": [
      {
        "typeCode": "string",
        "description": "string",
        "fields": [
          {
            "dataType": "string",
            "fieldLabel": "sender.primaryIdentification.issueCountrySubdivisionCode",
            "required": false,
            "staticFieldOverRide": null,
            "fieldMin": null,
            "fieldMax": null,
            "regEx": null,
            "exampleText": null,
            "enumerationItem": null
          },
          {
            "dataType": "gDay",
            "fieldLabel": "sender.primaryIdentification.expirationDay",
            "required": false,
            "staticFieldOverRide": null,
            "fieldMin": null,
            "fieldMax": null,
            "regEx": null,
            "exampleText": "dd",
            "enumerationItem": null
          },
          {
            "dataType": "gMonth",
            "fieldLabel": "sender.primaryIdentification.expirationMonth",
            "required": false,
            "staticFieldOverRide": null,
            "fieldMin": null,
            "fieldMax": null,
            "regEx": null,
            "exampleText": "mm",
            "enumerationItem": null
          },
          {
            "dataType": "gYear",
            "fieldLabel": "sender.primaryIdentification.expirationYear",
            "required": false,
            "staticFieldOverRide": null,
            "fieldMin": null,
            "fieldMax": null,
            "regEx": null,
            "exampleText": "yyyy",
            "enumerationItem": null
          },
          {
            "dataType": "enum",
            "fieldLabel": "sender.PersonalId1.Issue.Authority",
            "required": false,
            "staticFieldOverRide": null,
            "fieldMin": null,
            "fieldMax": "30",
            "regEx": null,
            "exampleText": null,
            "enumerationItem": null
          },
          {
            "dataType": "string",
            "fieldLabel": "sender.PersonalId1.Issue.City",
            "required": false,
            "staticFieldOverRide": null,
            "fieldMin": null,
            "fieldMax": "20",
            "regEx": "^([a-zA-Z \\u00C0-\\u017F\\#\\/\\.\\\"\\'\\,\\(\\)\\-])*$",
            "exampleText": null,
            "enumerationItem": null
          },
          {
            "dataType": "string",
            "fieldLabel": "sender.primaryIdentification.issueCountryCode",
            "required": true,
            "staticFieldOverRide": null,
            "fieldMin": null,
            "fieldMax": null,
            "regEx": null,
            "exampleText": null,
            "enumerationItem": null
          },
          {
            "dataType": "gDay",
            "fieldLabel": "sender.PersonalId1.Issue.Day",
            "required": false,
            "staticFieldOverRide": null,
            "fieldMin": null,
            "fieldMax": null,
            "regEx": null,
            "exampleText": null,
            "enumerationItem": null
          },
          {
            "dataType": "gMonth",
            "fieldLabel": "sender.PersonalId1.Issue.Month",
            "required": false,
            "staticFieldOverRide": null,
            "fieldMin": null,
            "fieldMax": null,
            "regEx": null,
            "exampleText": null,
            "enumerationItem": null
          },
          {
            "dataType": "gYear",
            "fieldLabel": "sender.PersonalId1.Issue.Year",
            "required": false,
            "staticFieldOverRide": null,
            "fieldMin": null,
            "fieldMax": null,
            "regEx": null,
            "exampleText": null,
            "enumerationItem": null
          },
          {
            "dataType": "string",
            "fieldLabel": "sender.primaryIdentification.id",
            "required": true,
            "staticFieldOverRide": null,
            "fieldMin": null,
            "fieldMax": "25",
            "regEx": "^(([0-9A-Za-z]\\-*\\**\\s*)*([0-9A-Za-z]*\\s*\\-*\\**))*$",
            "exampleText": null,
            "enumerationItem": null
          },
          {
            "dataType": "string",
            "fieldLabel": "sender.PersonalId1.ImageReferenceId",
            "required": false,
            "staticFieldOverRide": null,
            "fieldMin": null,
            "fieldMax": "20",
            "regEx": "^[0-9]*$",
            "exampleText": null,
            "enumerationItem": null
          }
        ]
      }
    ]
  }
]

Code Examples

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

const identificationDocuments = 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/identification-documents';

    // 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",
        countryCode: "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);
    }
};

identificationDocuments();

import requests
import uuid
import json

def identification_documents():

    # 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/identification-documents';

    # 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',
        'countryCode': "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)

identification_documents()

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

    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 countryCode = "USD";

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

        String uri = "https://" + host + "/reference-data/v1/identification-documents?"
                + "agentPartnerId=" + agentPartnerId
                + "&userLanguage=" + userLanguage
                + "&countryCode" + countryCode
                + (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

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

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 customer. (Enumerated value) NOTE: For a full list of accepted target audience values. See the TARGET_AUDIENCE enumeration from the Reference Data Enumerations endpoint
`agentPartnerId`	String	Optional	Unique agent or partner identifier
`userLanguage`	String	Required	Language used by the user/operator
`countryCode`	String	Required	Country code of identification document (ISO Alpha-3 code)

Response Fields

Field	Type	Required/ Optional	Description
`countryCode`	String	Optional	Country code of identification document (ISO Alpha-3 code)
`primaryIdentifications`	Array	Optional	Array of primary identifications
`primaryIdentifications.typeCode`	String	Optional	Unique identifier of the identification document. (Enumerated values)
`primaryIdentifications.description`	String	Optional	Name of the identification document
`primaryIdentifications.fields`	Array	Optional	Data fields and metadata for the Identification document
`secondaryIdentifications.typeCode`	String	Optional	Unique identifier of the identification document. (Enumerated values)
`secondaryIdentifications.description`	String	Optional	Name of the identification document
`secondaryIdentifications.fields`	Array	Optional	Data fields and metadata for the Identification document

identification.fields Array Structure

The data descriptions below relate to both the primaryIdentification.fields and secondaryIdentifications.fields in the table above.

FieldName/Metadata	Description	Example Value
`dataType`	Data type of the `field`	string, gDay,
`fieldLabel`	Field name described in dot notation	sender.primaryIdentification.issueCountryCode
`required`	Indicates if the data is required to be collected for the field	Boolean: (true/false)
`fieldMin`	Min `field` length	0
`fieldMax`	Max `field` length	255
`regEx`	Regular expression for data validation of the `Field`.	"^([a-zA-Z \À-\ſ-'/])*$"
`exampleText`	Example field value	USA
`enumerationItem`	An array of accepted values for the `field`.	{ "value": "ALN", "description": "Alien ID" }, { "value": "DRV", "description": "Drivers License" },