GET Retrieve a Transaction
GET /payout/v1/transactions/?referenceNumber={referenceNumber}
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 - HeadersOpen 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' byreferenceNumber
endpoint responds with a 200 HTTP Status the response will typically return thetransactionId
,payoutId
,sender
,receiver
andtransactionInformation
fields.
- Failed | Parse the Response | 200 OK HTTP Status |
"availableForPayout": false
When the 'Retrieve a transaction' byreferenceNumber
endpoint responds with a 200 HTTP Status but the "availableForPayout": false
, the transaction cannot be paid out. This is because thetransactionStatus
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": trueOpen Recipe.
👉Payout - Retrieve a Transaction - 200 OK - "amendSuccess": falseitleOpen Recipe.
👉Payout - Retrieve a Transaction - 400 Bad RequestOpen 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 | Optional | 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 Max length: 36 | Optional | Unique identifier for the transaction resource |
payoutId | String | Optional | Unique identifier for the transaction session |
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 | The receiveAmount.taxes.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.currencyCode | String | Required | The receiveAmount.total.value currency code (ISO alpha-3 code) |
receiveAmount.fxRate | Number Max Decimal Value: 6 | Required | FX rate applied to transaction |
receiveAmount.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. |
originalReceiveAmount.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) |
originalReceiveAmount.amount.currencyCode | String | Required | The orginalReceiveAmount.amount.value currency code (ISO alpha-3 code) |
originalReceiveAmount.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) |
originalReceiveAmount.fees.currencyCode | String | Optional | The orginalReceiveAmount.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 picked 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. |
sender.name.firstName | String Min length: 1 Max length: 20 | Required | First name |
sender.name.middleName | String Min length: 1 Max length: 20 | Optional | Middle name (if applicable) |
sender.name.lastName | String Min length: 1 Max length: 30 | Optional | Last name |
sender.name.secondLastName | String Min length: 1 Max length: 30 | Optional | Second last name |
receiver.name.firstName | String Min length: 1 Max length: 20 | Required | First name |
receiver.name.middleName | String Min length: 1 Max length: 20 | Optional | Middle name (if applicable) |
receiver.name.lastName | String Min length: 1 Max length: 30 | Optional | Last name |
receiver.name.secondLastName | String Min length: 1 Max length: 30 | Optional | Second last name (if applicable) |
additionalDetails | Dynamic | Optional | Dynamic field key/values |
Updated about 13 hours ago