GET Retrieve a Transaction
GET /disbursement/status/v1/transactions/{transactionId}
GET /disbursement/status/v1/transactions/?referenceNumber={referenceNumber}
Development Guide
The 'Retrieve a Transaction' endpoints lookup a transaction by referenceNumber
or transactionId
and return the current status of a transaction.
1. Prepare headers, authentication and parameters:
The application must call the 'Retrieve a Transaction' endpoint with a GET HTTP method, providing the OAuth access_token
, required headers and parameter values. There are two endpoints that can be used to retrieve a transaction status:
- Retrieve a transaction by transactionId |
GET /disbursement/status/v1/transactions/{transactionId}
OR - Retrieve a transaction by referenceNumber |
GET disbursement/status/v1/transactions/?referenceNumber={referenceNumber}
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 Code Example
👉Batch Disbursement Status - By Transaction ID - Headers and ParametersOpen Recipe.
👉Batch Disbursement Status - By Reference Number - Headers and ParametersOpen Recipe
2. Make a request and handle the response:
The application must call the '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
When the 'Retrieve a transaction' bytransactionId
orreferenceNumber
endpoint responds with a 200 HTTP Status the response will typically returntransactionStatus
,transactionSubStatus
,sender
,receiver
,transactionInformation
.
- Failed | Handle the Error | 400 Bad Request HTTP Status
When the 'Retrieve a Transaction' endpoint responds with 400 HTTP Status, specific error codes will be returned with an array of offending fields. The application will need to resolve these errors and resubmit the request.
Note: If the transaction is in a
"transactionStatus": "RECEIVED"
, theexpectedPayoutDate
field will not be returned in the response.
Launch Code Example
👉Batch Disbursement Status - 200 OKOpen Recipe.
👉Batch Disbursement Status - 400 Bad RequestOpen Recipe
3. You're Done! Communicate the transaction status to the consumer:
The information returned can be used to display a Transaction Summary feature on the application UI. The transactionStatus
is a top level transaction status. There is also a transactionSubStatus
which provides more detail about the transaction status and any action needed by the consumer Learn More
Code Examples
Retrieve by transactionId
transactionId
const axios = require('axios');
const { v4: uuidv4 } = require('uuid');
const status = 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 + '/disbursement/status/v1/transactions';
// 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 transactionId = "current_transaction_id";
const params = {
agentPartnerId: "your_partner_id",
userLanguage: "en-US",
targetAudience: "AGENT_FACING"
}
try {
// Step 3: Send the request and obtain the response
axios.get(url + '/' + transactionId, { 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);
}
};
status();
import requests
import uuid
import json
def status():
# 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 + '/disbursement/status/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,
}
transactionId = "current_transaction_id";
params = {
'agentPartnerId': 'your_partner_id',
'userLanguage': 'en-US',
'targetAudience': 'AGENT_FACING',
}
try:
# Step 3: Send the request and obtain the response
response = requests.get(url + '/' + transactionId, 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)
status()
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 StatusByTransactionID {
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";
// Optional Query params
String targetAudience = "AGENT_FACING";
// Mandatory Path params
String transactionId = "current_transaction_id";
String uri = "https://" + host + "/disbursement/status/v1/transactions/" + transactionId + "?"
+ "agentPartnerId=" + agentPartnerId
+ "&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
}
}
}
Retrieve by referenceNumber
referenceNumber
const axios = require('axios');
const { v4: uuidv4 } = require('uuid');
const status = 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 + '/disbursement/status/v1/transactions';
// 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 = {
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
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);
}
};
status();
import requests
import uuid
import json
def status():
# 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 + '/disbursement/status/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)
status()
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 StatusByReferenceNumber {
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 + "disbursement/status/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. |
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 |
Path Parameters
Field | Type | Required /Optional | Description |
---|---|---|---|
transactionId | String | Required | Unique identifier for the transaction resource |
Response Fields
Field | Type | Required/ Optional | Description |
---|---|---|---|
transactionId | String Max length: 36 | Optional | Unique identifier for the transaction resource |
partnerTransactionId | STring | Optional | Partners Unique identifier for the transaction resource |
referenceNumber | String Max length: 8 | Optional | MoneyGram's reference number for the transaction |
transactionSendDateTime | String $date-time | Optional | Transaction send date and time |
expectedPayoutDate | String $date | Optional | Expected Payout date of the transaction |
transactionStatus | String | Optional | MoneyGram's transaction status |
transactionSubStatus.subStatus | String | Optional | MoneyGram's transaction sub-status |
transactionSubStatus.message | String | Optional | Message associated with the sub-status code |
transactionSubStatus.targetCustomer | String | Optional | Customer associated with sub-status code. |
transactionSubStatus.dataToCollect.code | String | Optional | Unique code for data or document needed to be collected from customer |
transactionSubStatus.dataToCollect.datacollection | String | Optional | Data or document needed to be collected from customer |
originatingCountryCode | String Max Length: 3 | Required | Transaction country of Origin (ISO alpha-3 code) NOTE: For a full list of accepted destination country ISO codes see the Reference Data API Module: Retrieve countries iso3Code endpoint |
destinationCountryCode | String Max Length: 3 | Required | Transaction Destination Country (ISO alpha-3 code) NOTE: For a full list of accepted destination country ISO codes see Reference Data API Module: Retrieve countries iso3Code 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: Retrieve Service Options endpoint |
serviceOptionName | String Max length: 50 | Optional | Consumer-facing name to identify the transaction method NOTE: For a full list of accepted service option names per destinationCountry see the Reference Data API Module: Retrieve Service Options endpoint |
serviceOptionRoutingCode | String Max length: 21 | Optional | 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: Retrieve Service Options endpoint |
serviceOptionRoutingName | String Max length: 50 | Optional | Unique name to identify the individual transaction method |
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.additionalCharges.typeCode | String | Optional | Code to indicate if the fee is to be collected by MoneyGram or the partner |
sendAmount.additionalCharges.label | String | Optional | Consumer-facing name to identify the charge type |
sendAmount.additionalCharges.value | String | Optional | Additional fee's amount |
sendAmount.additionalCharges.currencyCode | String | Optional | Additional fee's currency code (ISO alpha-3 code) |
sendAmount.discountsApplied.totalDiscount.value | 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.totalDiscount.currencyCode | String | Optional | The discountsApplied.totalDiscount.value currency code (ISO alpha-3 code) |
sendAmount.discountsApplied.promotionDetails.code | String Min length: 0 Max length: 14 | Optional | Additional Details about the applied promotion to the transaction. currencyCode (ISO alpha-3 code) |
sendAmount.discountsApplied.promotionDetails.discount.amount | String | Optional | The transaction's total discount applied. |
sendAmount.discountsApplied.promotionDetails.discount.currencyCode | String | Optional | Value's Currency code (ISO alpha-3 code) |
sendAmount.discountsApplied.promotionDetails.errorCode | String | Optional | Error code defined by MoneyGram |
sendAmount.discountsApplied.promotionDetails.errorMessage | String | Optional | Error message associated with the error code |
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.currency | 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.fees.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 | The receiveAmount.taxes.value currency code (ISO alpha-3 code) |
receiveAmount.additionalCharges.typeCode | String | Optional | Code to indicate if the fee is to be collected by MoneyGram or the partner |
receiveAmount.additionalCharges.label | String | Optional | Consumer facing name to identify the charge type |
receiveAmount.additionalCharges.value | String | Optional | Additional fee's amount |
receiveAmount.additionalCharges.currencyCode | String | Optional | The additionalCharges.value currency code (ISO alpha-3 code) |
receiveAmount.total.value | String Min length: 0 Max length: 14 Max Decimal Value: 3 | Required | Receive Amount Total and Receive Transaction Currency to be picked-up/deposited in destination country including fees, taxes and discount (Transaction Total Amount uses ISO alpha-3 code) |
receiveAmount.total.currency | String | Required | The receiveAmount.total.value currency code (ISO alpha-3 code) |
receiveAmount.fxRate | Number Max length: 6 | Required | Fx Rate applied to transaction |
sendAmount.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. |
sender.businessInfo.businessName | String Min Length: 1 Max Length: 100 | Optional | Name of the business |
sender.businessInfo.businessRegistrationNumber | String | Optional | Business registration number (ISO Alpha-3 code) |
sender.business.businessCountryOfRegistration | String Length: 3 | Optional | Business's country of registration |
sender.businessProfileId | String | Optional | A unique MoneyGram identifier for the business. |
sender.partnerProfileId | String | Optional | The partners business profileId that will be passed from the partner and mapped to the MoneyGram business profile ID. |
sender.additionalDetails | Dynamic | Optional | Dynamic field key/values |
Beneficiary oneOf Options:
The beneficiary will be "oneOf" two options business
, or consumer
.
Option 1: beneficiary.business
beneficiary.business
Field | Type | Required/ Optional | Description |
---|---|---|---|
beneficiary.businessInfo.businessName | String | Required | Name of the business |
beneficiary.businessInfo.businessRegistrationNumber | String | Required | Business registration number |
beneficiary.business.businessCountryOfRegistration | String | Required | Business's country of registration |
Option 2: beneficiary.consumer
beneficiary.consumer
Field | Type | Required /Optional | Description |
---|---|---|---|
beneficiary.consumer.name.firstName | String Min length: 1 Max length: 20 | Required | First Name |
beneficiary.consumer.name.middleName | String Min length: 1 Max length: 20 | Optional | Middle Name (if applicable) |
beneficiary.consumer.name.lastName | String Min length: 1 Max length: 30 | Required | Last Name |
beneficiary.consumer.name.secondLastName | String Min length: 1 Max length: 30 | Optional | Second Last Name |
Additional Details
Field | Type | Required /Optional | Description |
---|---|---|---|
additionalDetails | Dynamic | Optional | Dynamic field key/values for the transaction |
Updated about 1 month ago