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

📘

  • Finalizing thetransactionId & 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.

NameHTTP MethodEndpointsDescription
Retrieve EnumerationsGET/reference-data/v1/enumerationsRetrieves 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