Development Guide

The 'Retrieve a Transaction' endpoints looks-up a transaction by referenceNumber and will return the transaction details and determine if it is available for payout.

1. Prepare headers, authentication & parameters:

The application must call the 'Retrieve a transaction' endpoint with a GET HTTP method, providing the OAuth access_token and all other required headers. The application must pass the transaction referenceNumber as a query parameter to retrieve the transaction.

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

🚀
Launch Example Code:

Payout - Retrieve Transaction - Headers

Open Recipe

2. Make a request and handle the response:

The application must call 'Retrieve a transaction' endpoint with a GET HTTP method. The application must build to handle the following response scenarios:

Success | Parse the Response | 200 OK HTTP Status | "availableForPayout": true
When the 'Retrieve a transaction' by referenceNumber endpoint responds with a 200 HTTP Status the response will typically return the transactionId, payoutId, sender, receiver and transactionInformation fields.

Failed | Parse the Response | 200 OK HTTP Status | "availableForPayout": false
When the 'Retrieve a transaction' by referenceNumber endpoint responds with a 200 HTTP Status but the "availableForPayout": false, the transaction cannot be paid out. This is because the transactionStatus is not available for payout. Learn More.

Failed | Handle the Error | 400 Bad Request HTTP Status
When the 'Retrieve 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 request.

🚀
Launch Example Code:

Payout - Retrieve a Transaction - 200 OK - 'amendSuccess': true

Open Recipe

.

Payout - Retrieve a Transaction - 200 OK - 'amendSuccess': falseitle

Open Recipe

.

Payout - Retrieve a Transaction - 400 Bad Request

Open Recipe

3. Communicate the transaction status to customer:

The information returned can be used to display a Transaction Summary feature on the application UI.

4. You're Done! Proceed to Update a Transaction API:

The application must execute the 'Update a transaction' endpoint to get the readyForCommit": true.

Note:

To execute the refund, the transactionId returned in the payload must be persisted and used as a path parameter on subsequent 'Update 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 'Update a Transaction' API.

Business Rules to Code:

🔎

Ready for Payout & Available status: The transaction can only be paid out if the transaction is in an AVAILABLE status and the "availableForPayout": true is returned in the response.

Send & Payout at the same store: A Payout cannot be received at the same store location where the transaction was sent (i.e. The application cannot Payout a transaction using the same partnerAgentId that was used to send the transfer).

Code Examples

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

const retrieve = 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 + '/payout/v1/transactions';

    // Step 2: Create the GET headers & params

    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",
        referenceNumber: "your_reference_number",
        userLanguage: "en-US",
        targetAudience: "AGENT_FACING",
    }

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

retrieve();

import requests
import uuid
import json

def retrieve():

    # 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 + '/payout/v1/transactions';

    # 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 = {
        'agentPartnerId': 'your_partner_id',
        'referenceNumber': 'your_reference_number',
        'userLanguage': 'en-US',
        'targetAudience': 'AGENT_FACING',
    }
    
    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)

retrieve()

package payout;

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

    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 referenceNumber = "your_reference_number";
        String userLanguage = "en-US";

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

        String uri = "https://" + host + "/payout/v1/transactions" + "?"
                + "agentPartnerId=" + agentPartnerId
                + "&referenceNumber=" + referenceNumber
                + "&userLanguage=" + userLanguage
                + (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 the value of this field.
`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 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 user/operator
`agentPartnerId`	String	Required	Unique agent or partner identifier
`referenceNumber`	String	Required	MoneyGram's reference number for the transaction
`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.

Response fields

Field	Type	Required/ Optional	Description
`transactionId`	String	Optional	Unique identifier for the transaction resource
`payoutId`	String	Required	Unique identifier for the transaction session
`transactionSendDateTime`	String ($date-time)	Optional	Transaction send date and time
`availableForPayout`	Boolean	Optional	Identifies if the transaction is in a status available for payout
`transactionStatus`	String	Optional	MoneyGram's transaction status
`transactionSubStatus.subStatus`	String	Optional	MoneyGram's transaction sub-status
`transactionSubStatus.targetCustomer`	String	Optional	Customer associated with sub-status code.
`transactionSubStatus.customerAction`	String	Optional	Message associated with the 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
`originatingCountryCode`	String Max Length: 3	Optional	Transaction country of origin (ISO alpha-3 code) NOTE: For a full list of accepted originating country ISO codes see the Reference data API module: Retrieve countries ISO3 endpoint
`destinationCountryCode`	String Max Length: 3	Optional	Transaction destination country (ISO alpha-3 code) NOTE: For a full list of accepted destination countries and supported destination country subdivision codes see Reference data API module: Retrieve countries ISO3 endpoint
`serviceOptionCode`	String Max length: 21	Required	Unique category code to identify the transaction method NOTE: For a full list of accepted service option codes per destination country see the Reference data API module: service-options endpoint
`serviceOptionName`	String Max length: 50	Optional	Unique name to identify the transaction method NOTE: For a full list of accepted service option names per destination country see the Reference data API module: service-options endpoint
`serviceOptionRoutingCode`	String Max length: 21	Required	Unique identifier of the individual banking, wallet, or card provider for the service option. NOTE: For a full list of accepted service option routing codes per destination country see the Reference data API module: service-options endpoint
`sendAmount.amount.value`	String Min length: 0 Max length: 14 Max Decimal Value: 3	Required	Transaction amount and currency excluding fees and exchange rate. Transaction currency (ISO alpha-3 code) _NOTE: For crypto partners this is the fiat currency for the buy/sell or ramp on/ramp off
`sendAmount.amount.currencyCode`	String	Required	The `sendAmount.amount.value` currency code (ISO alpha-3 code)
`sendAmount.fees.value`	String Min length: 0 Max length: 14 Max Decimal Value: 3	Required	Fee amount and fee currency applied to transaction (Fee currency usesISO alpha-3 code)
`sendAmount.fees.currencyCode`	String	Required	The `sendAmount.fees.value` currency code (ISO alpha-3 code)
`sendAmount.taxes.value`	String Min length: 0 Max length: 14 Max Decimal Value: 3	Optional	Tax amount and tax currency applied to the transaction by the the origin country (Tax currency uses ISO alpha-3 code)
`sendAmount.taxes.currencyCode`	String	Optional	The `sendAmount.taxes.value` currency code (ISO alpha-3 code)
`sendAmount.discountsApplied.totalDiscount`	String Min length: 0 Max length: 14 Max Decimal Value: 3	Optional	Transaction discount amount applied and currency type excluding fees and exchange rate. Transaction currency (ISO alpha-3 code)
`sendAmount.discountsApplied.promotionDetails`	String String Max length: 50	Optional	Additional details about the applied promotion to the transaction
`sendAmount.total.value`	String Min length: 0 Max length: 14 Max Decimal Value: 3	Required	Transaction total amount and transaction total currency including fees, taxes and discount. (Transaction total amount uses ISO alpha-3 code)
`sendAmount.total.currencyCode`	String	Required	The `sendAmount.total.value` currency code (ISO alpha-3 code)
`receiveAmount.amount.value`	String Min length: 0 Max length: 14 Max Decimal Value: 3	Required	Transaction received amount and transaction receive currency (Transaction total amount uses ISO alpha-3 code)
`receiveAmount.amount.currencyCode`	String	Required	The `receiveAmount.amount.value` currency code (ISO alpha-3 code)
`receiveAmount.fees.value`	String Min length: 0 Max length: 14 Max Decimal Value: 3	Optional	Received fee and receive currency applied to the transaction by the destination country (Transaction total amount uses ISO alpha-3 code)
`receiveAmount.fees.currencyCode`	String	Optional	The `receiveAmount.fees.value` currency code (ISO alpha-3 code)
`receiveAmount.taxes.value`	String Min length: 0 Max length: 14 Max Decimal Value: 3	Optional	Tax amount and tax currency applied to the transaction by the the origin country (Tax currency uses ISO alpha-3 code)
`receiveAmount.taxes.currencyCode`	String	Optional
`originalReceiveAmount.total.value`	String Min length: 0 Max length: 14 Max Decimal Value: 3	Required	Receive amount total and receive transaction currency to be pickef up/deposited in destination country including fees, taxes and discount (Transaction total amount uses ISO alpha-3 code)
`originalReceiveAmount.total.currencyCode`	String	Required	The `orginalReceiveAmount.total.value` currency code (ISO alpha-3 code)
`originalReceiveAmount.fxRate`	Number Max Decimal Value: 6	Required	FX rate applied to transaction
`originalReceiveAmount.fxRateEstimated`	Boolean	Optional	Indicates whether the FX is “estimated” and amount, taxes and total cannot be guaranteed. The word “estimated” must appear before receiveAmount.amount, receiveAmount.taxes and receiveAmount.total only when true.
`estimatedReceiveAmountInLocalCurrency.amount`	String Min length: 0 Max length: 14 Max Decimal Value: 3	Required	Transaction received amount and transaction receive currency (Transaction total amount uses ISO alpha-3 code)
`estimatedReceiveAmountInLocalCurrency.currencyCode`	String	Required	The `estimatedReceiveAmountInLocalCurrency.amount.value` currency code (ISO alpha-3 code)
`estimatedReceiveAmountInLocalCurrency.fees.value`	String Min length: 0 Max length: 14 Max Decimal Value: 3	Optional	Received fee and receive currency applied to the transaction by the destination country (Transaction total amount uses ISO alpha-3 code)
`estimatedReceiveAmountInLocalCurrency.fees.currencyCode`	String	Optional	The `estimatedReceiveAmountInLocalCurrency.fees.value` currency code (ISO alpha-3 code)
`estimatedReceiveAmountInLocalCurrency.taxes.value`	String Min length: 0 Max length: 14 Max Decimal Value: 3	Optional	Tax amount and tax currency applied to the transaction by the the origin country
`estimatedReceiveAmountInLocalCurrency.taxes.currencyCode`	String	Optional	The `estimatedReceiveAmountInLocalCurrency.taxes.value` currency code (ISO alpha-3 code)
`estimatedReceiveAmountInLocalCurrency.total.value`	String Min length: 0 Max length: 14 Max Decimal Value: 3	Required	Receive amount total and receive transaction currency to be pickef up/deposited in destination country including fees, taxes and discount (Transaction total amount uses ISO alpha-3 code)
`estimatedReceiveAmountInLocalCurrency.total.currencyCode`	String	Required	The `estimatedReceiveAmountInLocalCurrency.total.value` currency code (ISO alpha-3 code)
`estimatedReceiveAmountInLocalCurrency.fxRate`	Number Max Decimal Value: 6	Required	FX rate applied to transaction
`estimatedReceiveAmountInLocalCurrency.fxRateEstimated`	Boolean	Optional	Indicates whether the FX is “estimated” and amount, taxes and total cannot be guaranteed. The word “estimated” must appear before receiveAmount.amount, receiveAmount.taxes and receiveAmount.total only when true.