Open API 3.0 Spec

All MoneyGram APIs are REST endpoints and are defined the standardized Swagger Specification. All MoneyGram OpenAPI Specifications are defined in YAML and can be imported to Swagger Editor.

Environments

MoneyGram API platform provides two distinct environments – Sandbox and Production. Both environments have distinct OAuth 2.0 credentials. To start development Sandbox credentails will be provided to you by MoneyGram. Production credentials will be provided after application certification has been completed.

• Sandbox Environment - https://sandboxapi.moneygram.com
  
  MoneyGram provides a sandbox environment for developers to build and test the applications. This is a pre-production environment set up to allow development and QA teams to develop and test the integration with MoneyGram. A certification effort is done with MoneyGram before agents can access Production environment. In this environment, there is no real money movement and it does not impact customers.

• Production Environment - https://api.moneygram.com
  
  MoneyGram provides this as a Live environment for developers. Developers don't test here, but for agents to start pilot/beta testing before full/complete rollout for real-time transactions. In this environment, real money transfers are live and they impact customers, agents and settlement.

👍

Good to know:

Secure Client Credentials: The Client secret is a very sensitive piece of data as it could be used to impersonate your company on the MoneyGram APIs. It should be handled and stored with the utmost security.

URI Patterns

MoneyGram APIs use industry-best practices around URI (Universal Resource Identifier). Each REST API resource can be accessed by using a unique URI.

https://api.moneygram.com/<product-type>/<version>/<resource>/{resourceId}/<command>
|________________________|______________|_________|__________|____________|________|
            base              module      version   resource   resourceId   command

https://sandboxapi.moneygram.com/transfer/v1/transactions/{transactionID}/quote
|_______________________________|___________|____________|_______________|____|
            base                 module      resource      resourceID     command

https://api.moneygram.com/transfer/v1/transactions/{transactionID}/quote
|________________________|___________|____________|_______________|_____|
            base              module    resource     resourceID     command

Guidelines

Base:

• Sandbox: https://sandbox.moneygram.com
• MoneyGram APIs are secured by hypertext transfer protocol secure (HTTPS)
• MoneyGram servers uses HTTPS Port 443

Modules:

• A <product-type> is used to identify the module
  examples: Transfer, Status, Refund, Amend, Payout, Disbursement

Versioning:

• MoneyGram will version the module for the entire product and not at the resource level.

Resources:

• Nouns are used to represent resources
• A resource may contain sub-collection resources
• A resource can be a singleton or a collection
• Plural names are used to denote the collection resource

Command Pattern:

• Use command pattern to explicitly indicate actions required during transaction flows.

Authentication & Authorization

MoneyGram uses an OAuth 2.0 framework. The application must use their OAuth client credentials to generate an access token and pass it as a header value in subsequent HTTP calls.

HTTP Methods

MoneyGram APIs support the following HTTP Methods:

API Parameters

MoneyGram APIs support the following parameters:

Path parameters

PUT https://sandboxapi.moneygram.com/transfer/v1/transactions/{transactionID}

Query parameters

GET https://sandboxapi.moneygram.com/status/v1/transactions/?referenceNumber={referenceNumber}

Header parameters

X-MG-ClientRequestId:{Value}

ISO Codes Supported

• When entering country values, the three-letter code (alpha-3) must be used. ISO 3166 Country Codes
• When entering currency values, the three-letter code (alpha-3) must be used. ISO 4217 Currency Codes

👍

Good to know:

MoneyGram has provided a Reference Data API module that can be queried to provide a list of supported ISO standards and associated meta-data for the APIs. Below is a list of endpoints that will provide ISO values for country and currency fields:

• GET: /reference-data/v1/countries
• GET: /reference-data/v1/countries/{iso3Code}
• GET /reference-data/v1/currencies

Http Status

Languages

Our APIs support the following languages. Enter the desired language code in the userLanguage field for errors and other language-specific information to be translated.

👍

Good to know:

Default language: If translation is not available English will be returned.

Development and Testing Do's and Don'ts

DO

1. Your production credentials and URL will differ from those in the test environment.
2. After certification signoff, your production credentials (secret and key) will be provided.
3. Where applicable, review and follow the “Business rules to code” section for each API on the MoneyGram Developer Portal. These are additional rules/logic that must be built into the application.
4. The maximum field lengths the system allows could be shorter than the documentation defines. For a send transaction, follow the maximum field length returned by the “Retrieve required and optional fields” endpoint in the Reference Data API.
5. The fee and FX are only estimated at the time of the quote. The FX rate is guaranteed for 30 minutes from the time of the quote until the transaction is committed. However, the FX rate may change if the transaction is not committed within 30 minutes. Any exchange rate and fee provided to the customer from the quote should have a disclaimer that it’s subject to change.
6. When in the pre-certification stage, please follow all instructions for each test case. If you cannot perform a specific task in a test case, please comment on why.
7. When quoting by receive amount in the Transfers Quote API Endpoint, it is normal that the receive amount returned in the Response is slightly different from the one input in the Quote Request. This is due to the exchange rate, and the calculation does not allow for an exact match.

Don't

1. An agent ID will be assigned to each partner. Do not hardcode the agent ID or security token.
2. Don’t use the same agent ID to send and receive the same transaction.
3. Don’t hardcode any of the customer data.
4. Don’t use the same customer and transaction data in your testing. Our standard screening will identify the customer as high-risk and place the transaction on hold or reject it. After several transactions, change the consumer data (name, address, phone, birth date, photo ID number, etc.).
5. Don’t schedule your go-live window on a Friday, weekend, or holiday. Go-live should be Monday through Wednesday.