Development Guide

The 'Reverse a Transaction' endpoint will rollback the payout of a transaction, if paid out in error or in the event of a system failure.

1. Headers & authentication:

The application must call the 'Reverse a Transaction ' endpoint with a PUT HTTP method, providing the OAuth access_token and all other required header and parameter values. To invoke the Reverse a Transaction API, the application must pass the transactionId as a path parameter.

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

The transaction can only be reversed by the same application and agentPartnerId that committed the payout of the transaction.

Only a transaction in a "RECEIVED" status can be reversed.

A transaction can only be reversed within 30 minutes from the time the transaction "commit" was invoked.

🚀
Launch Code Example:
👉
Payout - Reversal - Headers
Open Recipe

2. Provide the `referenceNumber` & `receiveReversalReasonCode` in the Request Body

The request body must at a minimum must include the referenceNumber & receiveReversalReasonCode for the transaction to be reversed.

🚀
Launch Code Example:
👉
Payout - Reverse - Request Body
Open Recipe

3. Make a request and handle the response:

The application must call the 'Reverse a transaction' endpoint with a PUT HTTP method and be able to handle the following response scenarios:

Success | Parse the Response | 200 OK HTTP Status
When the 'Reverse a transaction' endpoint responds with a 200 HTTP status, the transaction will change back from a "RECEIVED" status to an "AVAILABLE" status. The transaction will not be settled with MoneyGram, and the partner will be able to try paying out the transaction again.

Failed | Handle the Error | 400 Bad Request HTTP Status
When the 'Reverse 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 transaction for reversal.

🚀
Launch Code Example:
👉
Payout - Reverse - 200 OK
Open Recipe
.
👉
Payout - Reverse - 400 Bad Request
Open Recipe

4. You're Done! Provide a receipt:

A receipt most be printed and handed to the customer.

Business Rules to Code

🔎

Making multiple PUT requests to Update the transactionId: if there are any changes needed for consumer data after the Update a transaction endpoint responds, the application should call the Update endpoint to using the same transactionId and payoutId to provide new consumer/transactional data.

Enumerated fields: For all Enumerated Fields (some examples below), agent application must use the valid enumerations returned from the enumerations API response and allow only valid values to be selected. Learn More

Pre-disclosure: It is regulatory requirement to show pre-disclosure on every transfer, in every country and for every service option. Learn More

API Structure

Header Parameters

Name	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	Identifies the client. Error messages and attribute metadata tailored to client [agent (store client) vs consumer (digital client)]
`userLanguage`	String	Required	Language used by the user/operator
`agentPartnerId`	String	Required	Unique agent or partner identifier
`posId`	String	Optional	Point of sale identifier of the client performing the API Call
`operataorId`	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.

Path Parameters

Field	Type	Required/ Optional	Description
`transactionId`	String	Required	Unique identifier for the transaction resource

Request Body

Field	Type	Required/ Optional	Description
`referenceNumber`	String	Required	Unique identifier for the transaction resource
`retryIndicator`	Boolean	Optional	If agent application has sent a receive reversal request and did not receive a response, the application can retry the receive reversal request again and set this indicator to true
`receiveReversalReasonCode`	String	Optional	Reason for the reversal of transaction (Enumerated values) NOTE: For a list of accepted enumerated values for receive reversal reason codes see the Reference Data API Module - Enumerations endpoint - RCV_REVERSAL_RSNS

Response fields

Field	Type	Required/Optional	Description
`receiveReversalSuccess`	Boolean	Required	Indicates whether the reversal is success or failure

PUT Reverse a Transaction

Development Guide

1. Headers & authentication:

🚀
Launch Code Example:

2. Provide the `referenceNumber` & `receiveReversalReasonCode` in the Request Body

🚀
Launch Code Example:

3. Make a request and handle the response:

🚀
Launch Code Example:

4. You're Done! Provide a receipt:

Business Rules to Code

🔎

API Structure

Header Parameters

Query Parameters

Path Parameters

Request Body

Response fields

Development Guide

1. Headers & authentication:

🚀Launch Code Example:

2. Provide the referenceNumber & receiveReversalReasonCode in the Request Body

🚀Launch Code Example:

3. Make a request and handle the response:

🚀Launch Code Example:

4. You're Done! Provide a receipt:

Business Rules to Code

🔎

API Structure

Header Parameters

Query Parameters

Path Parameters

Request Body

Response fields

🚀
Launch Code Example:

2. Provide the `referenceNumber` & `receiveReversalReasonCode` in the Request Body

🚀
Launch Code Example:

🚀
Launch Code Example: