PUT Commit a Transaction
PUT: /disbursement/v1/transactions/{transactionID}/commit
Overview
The Commit API executes the transactionId
and completes the transfer of funds.
Make a Request
-
Prepare headers & authentication:
The application must call the 'Commit a Transaction' endpoint with a PUT HTTP method, providing the
access_token
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
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
-
Provide the
transactionId
resource as a path parameter:The application must persist the
transactionId
from the Update API and apply as a path parameter to the Commit API.
-
Display Fraud Warnings & Pre-disclosure in application UI:
It is a regulatory requirement to display Learn More - Fraud Warnings US OnlyLearn More - Fraud Warning Global and a Pre-Payment Disclosure to the customer before the transfer of funds is executed. Both the Fraud Warnings and Pre-payment Disclosure must be shown for all transaction (i.e. in all send countries, for all amounts, for all service options).
-
Make a request and handle the response:
The application must call 'Commit a transaction' endpoint with a PUT HTTP method. The application has finalized/executed the transfer when the Commit endpoint returns a 200 OK HTTP Success Status and a unique
referenceNumber
in the payload. The funds are marked for "settlement" on the MoneyGram ledger. -
Communicate the reference number to customer:
The application is recommended to display the
referenceNumber
clearly on the UI or a notification to customer.
Business rules to code
Finalizing the
transactionId
& executing the transfer of funds:
- The commit a transaction may only be used when the
"readyForCommit": true
- The commit a transaction must be sent within 30 minutes of the
"readyForCommit": true
In the event of downtime/drop of connectivity:
- If the application does not receive a response from the Commit a Transaction API within 10-40 seconds, the application must send the request again. This must be retried up to 3 times.
- If the retry attempt fails, check the
transactionStatus
using the Status API to confirm if transaction was successful.Error Code 935: If error code 935 internal system error is returned on commit, it must be handled the same way as if the commit response is not received (see item 2).
Handling Errors: Other errors can be returned on commit a transaction stopping the transaction. The application must handle scenarios where the transaction fails (an error code is returned) on commit. Learn More
Receipts: Refer to Receipts module for detailed information and requirements for receipts.
Start online, fund in store: If a digital application wants to fund the transactions in store they should have market the
"fundInStore": true
on the Update API, the Commit API is not needed.Reference Number Recycling policy: MoneyGram will recycle the reference numbers after the transactions have been closed/received for 4 to 6 months. If you are storing reference numbers in your database, you should also store the transaction date. The combination of the reference number and transaction date will be the unique key for a transaction.
Code Examples
const axios = require('axios');
const { v4: uuidv4 } = require('uuid');
const commitTransaction = 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 transactionId = "current_transaction_id";
const url = 'https://' + host + '/disbursement/v1/transactions/' + transactionId + '/commit';
// Step 2: Create the PUT request headers & body
const headers = {
'Content-Type': 'application/json',
'X-MG-ClientRequestId': uuidv4(), // New UUID for each request tracing
'Authorization': 'Bearer ' + token,
};
const request = {
partnerTransactionId: ""
}
try {
// Step 3: Send the request and obtain the response
axios.put(url, request, { 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);
}
};
commitTransaction();
import requests
import uuid
import json
def commit_transaction():
# 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";
transactionId = "current_transaction_id";
url = 'https://' + host + '/disbursement/v1/transactions/' + transactionId + '/commit';
# Step 2: Create the PUT request headers & body
headers = {
'Content-Type': 'application/json',
'X-MG-ClientRequestId': str(uuid.uuid4()), # New UUID for each request tracing
'Authorization': 'Bearer ' + token,
}
request = {
'partnerTransactionId': ''
}
try:
# Step 3: Send the request and obtain the response
response = requests.put(url, json=request, 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:
# Step 5: Parse the error response and handle the errors
print("Request failed with status code:", response.status_code)
print(json.dumps(json.loads(response.text), indent=2))
except requests.exceptions.RequestException as e:
# Print any error that occurred during the request
# TODO: handle exception
print("An error occurred:", e)
commit_transaction()
package disbursement;
import javax.json.Json;
import javax.json.JsonObject;
import javax.json.JsonObjectBuilder;
import javax.json.JsonWriter;
import java.io.StringWriter;
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 CommitTransaction {
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";
String transactionId = "current_transaction_id";
String tokenEndpoint = "https://" + host + "/disbursement/v1/transactions/" + transactionId + "/commit";
// Step 2: Create the PUT request headers & body
// Create a JSON object
JsonObjectBuilder requestBuilder = Json.createObjectBuilder()
.add("partnerTransactionId", "");
JsonObject jsonObject = requestBuilder.build();
// Create a StringWriter to write the JSON string
StringWriter stringWriter = new StringWriter();
try (JsonWriter jsonWriter = Json.createWriter(stringWriter)) {
jsonWriter.writeObject(jsonObject);
}
// Get the JSON string from the StringWriter
String jsonString = stringWriter.toString();
HttpClient httpClient = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(tokenEndpoint))
.PUT(HttpRequest.BodyPublishers.ofString(jsonString))
.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 Request & Response Examples
curl --request PUT \
--url https://sandboxapi.moneygram.com/disbursement/v1/transactions/{transactionId}/commit \
--header 'X-MG-ClientRequestId: 4c79b06f-a2af-4859-82c8-28cbb0bf361b' \
--header 'X-MG-SessionId: ******************************' \
--header 'accept: application/json' \
--header 'authorization: Bearer ***************************' \
--header 'content-type: application/json' \
--data '
{
"partnerTransactionId": "1aac4a2c-a3d7-49a2-ae2f-5598a0b524e4"
}
'
{
"referenceNumber": "********",
"expectedPayoutDate": "2023-12-19"
}
Support APIs
To make your development easier, MoneyGram has provided a Reference Data APIs Module that can be queried to provide a list of supported fields, values and associated meta-data to use in your integration.
Name | HTTP Method | Endpoints | Description |
---|---|---|---|
Retrieve Enumerations | GET | /reference-data/v1/enumerations | Retrieves enumerated values for fields |
API Structure
Header Parameters
Name | Required /Optional | Type | Description |
---|---|---|---|
X-MG-ClientRequestId | Required | String | 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-SessionId | Optional | String | A GUID MoneyGram generates for correlating multiple calls within a transaction session |
X-MG-consumerIPAddress | Optional | String | IP Address of the system initiating the session |
Path Parameters
Path Parameter | Type | Required /Optional | Description |
---|---|---|---|
transactionId | String Max length: 36 | Required | Unique id of the transaction resource |
Request Body Fields
Field | Type | Required/ Optional | Description |
---|---|---|---|
partnerTransactionId | String | Required | Partner’s unique session identifier |
additionalDetails | Dynamic | Optional | Dynamic field key/values |
Response Fields
Field | Type | Required/ Optional | Description |
---|---|---|---|
referenceNumber | String Max length: 8 | Required | MoneyGram's reference number for the transaction |
expectedPayoutDate | String | Required | Expected payout date (Example value - YYYY-MM-DD |
Updated 10 months ago