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

  1. 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


  2. 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.


  3. 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).

  4. 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.

  5. 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

📘

  1. 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
  2. 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.
  3. 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).

  4. 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

  5. Receipts: Refer to Receipts module for detailed information and requirements for receipts.

  6. 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.

  7. 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.

NameHTTP MethodEndpointsDescription
Retrieve EnumerationsGET/reference-data/v1/enumerationsRetrieves enumerated values for fields



API Structure


Header Parameters

NameRequired
/Optional
TypeDescription
X-MG-ClientRequestIdRequiredStringClient 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-SessionIdOptionalStringA GUID MoneyGram generates for correlating multiple calls within a transaction session
X-MG-consumerIPAddressOptionalStringIP Address of the system initiating the session



Path Parameters

Path ParameterTypeRequired
/Optional
Description
transactionIdString
Max length: 36
RequiredUnique id of the transaction resource



Request Body Fields

FieldTypeRequired/
Optional
Description
partnerTransactionIdStringRequiredPartner’s unique session identifier
additionalDetailsDynamicOptionalDynamic field key/values



Response Fields

FieldTypeRequired/
Optional
Description
referenceNumberString
Max length: 8
RequiredMoneyGram's reference number for the transaction
expectedPayoutDateStringRequiredExpected payout date (Example value - YYYY-MM-DD