POST Quote a Transaction
POST /transfer/v1/transactions/quote
Development Guide
The 'Quote a Transaction' endpoint creates an array of transaction quotes for a given destination country. Each transaction quote will include the unique service option, send amount, receive amount, currencies, fees and fx. A unique transactionId resource will be created for each transaction quote.
1. Prepare headers & authentication:
Call the 'Quote a transaction' endpoint with a POST HTTP method, providing the OAuth access_token in the header 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
accessTokenby 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
Launch Code Example:Transfer Quote - HeadersOpen Recipe
2. Provide Request Body: "Quote by send amount" OR "Quote by receive amount":
The Quote API uses the oneOf Keyword to allow the application to either quote a transaction by send or receive amount:
- Quote by send amount: The application must provide at a minimum the
targetAudience,agentPartnerId,destinationCountryCodeand thesendAmount.valuefields in the request.
OR
- Quote by receive amount: The application must provide the at a minimum the
targetAudience,agentPartnerId,destinationCountryCode, and thereceiveAmount.valuefields in the request.
Note: The Quote API uses ISO Standards for country and currency values. MoneyGram provide Reference Data APIs which can be queried to understand and list the supported values and associated metadata.
Launch Code Example:Transfer Quote - By Send AmountOpen Recipe.
Transfers Quote - By Receive AmountOpen Recipe
3. Provide serviceOptionCode in the request body (optional):
serviceOptionCode in the request body (optional):The Quote API allows the application to specify one or all service options to be returned to the given destination country:
- Quote all service options: If the
serviceOptionCodeis not provided in the request body, the quote endpoint will return _all _service options in an array of quoted transactions (i.e. the API will return all cash pickup, bank, wallet & card deposit options available to the destination country). Learn More
OR
- Quote a single service option: If the
serviceOptionCodeis provided in the request body, the quote endpoint will only return an array of quoted transactions for that specified code. (e.g. if"serviceOptionCode": "Bank_Deposit"is passed in the request, the endpoint will only quote the bank deposit options available to the destination country) Learn More
Launch Code Example:Transfer Quote - serviceOptionCode - Not providedOpen Recipe.
Transfer Quote - serviceOptionCode - ProvidedOpen Recipe
4. Provide discounts to the request body (optional):
The Quote API also allows the application to apply promotional discounts and participate in the MoneyGram Plus Rewards program to accrue/redeem loyalty discounts.
- If a
promotionCodesis passed, a discount will be applied to the fee quote.
- If a
rewardsNumberis passed, a discount the will be applied to the quote. This is only for eligible transactions.
Launch Code Example:Transfer Quote - Promo Codes & Rewards (optional)Open Recipe
5. Make a request and handle the response:
The application must call 'Quote a transaction' endpoint with a POST HTTP method. The endpoint will respond with a HTTP 200 OK status. The Quote API response will provide an array of quoted transactions, each with a unique transactionId resource. The consumer must choose one quote to continue with and the application must persist the associated transactionId to use when calling the subsequent Update API.
- Success | Parse the Response | 200 OK HTTP Status
For eachtransactionIdresource generated, the endpoint will typically respond with the following fieldsserviceOptionCode,serviceOptionName,estimatedDelivery,sendAmount,sendCurrency,fees,taxes,additionalCharges,fxRate,discountsApplied, and thereceiveAmount. In some cases send or receive side taxes are applied.
- Failed | Handle the Error | 400 Bad Request HTTP Status
When the 'Quote 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 quote.
Note: The list of transactions returned on the Quote API is priced uniquely by the service options and receive currency. The Fee and FX rate is guaranteed for 30 minutes from the time of the quote. However, the FX rate may change if the transaction is not committed within 30 minutes of the quote.
Launch Code Example:Transfer Quote - 200 OKOpen Recipe.
Transfer Quote - 400 Bad RequestOpen Recipe
Request Fields
| Field | Type | Required/Optional | Description |
|---|---|---|---|
targetAudience | String | Required | API purpose: MONEY_TRANSFER, BILL_PAY, CRYPTO |
agentPartnerId | String Max length: 5 | Required | Unique code to identify the MoneyGram Partner |
posid | String | Optional | Point of sale identifier of the client performing the API Call |
operatorId | String | Required | 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. |
userLanguage | String Max Length: 6 | Optional | Language used by the user/operator |
destinationCountryCode | String Length: 3 | Required | ISO alpha-3 country code identifying the destination country NOTE: For a full list of destination countries see the Reference Data API Module: countries endpoint |
serviceOptionCode | String Max length: 21 | Optional | Unique category code to identify the transaction method. NOTE: For a full list of accepted service option codes per destination country see the Reference Data API Module: service-options endpoint |
serviceOptionRoutingCode | String Max length: 21 | Optional | Unique code to identify the individual transaction method. This field may only appear in quote if destination country requires sender to provide more detail on the routing information. NOTE: For a full list of accepted service option routing codes per destination country see the Reference Data API Module: service-options endpoint |
sendAmount.value | String Min length: 0 Max length: 14 Max decimal Value: 3 | Required (Quote by Send) | Quote by Send Amount value OR Quote by Receive Amount value |
sendAmount.currencyCode | String Length: 3 | Required (Quote by Send) | Send/Receive Currency ISO alpha-3 code NOTE: For a full list of transaction currency codes see the API Reference Data Module: currencies endpoint |
receiveAmount.value | String Min length: 0 Max length: 14 Max decimal Value: 3 | Required (Quote by Receive) | Quote by Send Amount value OR Quote by Receive Amount value |
receiveAmount.currencyCode | String Length: 3 | Required (Quote by Receive) | Send/Receive Currency ISO alpha-3 code NOTE: For a full list of transaction currency codes see the API Reference Data Module: currencies endpoint |
originationCountry | String | Optional | ISO alpha-3 code of the origination country. This field is usually required for those partners having cross-country capabilities or partners having a different registration country vs. transaction country. For most partners this field is derived from the consumer IP address. |
amountIncludesFee | Boolean | Optional | Indicates if the 'Send Amount' in the request body is inclusive of the transaction fee. Default value: false. |
thirdPartyId | String Max length: 16 | Optional | Unique code used to identify an intermediary partner. |
promotionCode | String Max length: 16 | Optional | Discount code associated with a specific business promotion. NOTE: To receive the list of promotion codes contact your MoneyGram Relationship Manager |
promotionCodeChannel | String Max length: 16 | Optional | Channel associated with the promotion code. NOTE: To receive the list of promotion code channels contact your MoneyGram Relationship Manager |
rewardsNumber | String Max length: 16 | Optional | Consumer's loyalty program account number NOTE: For a full list of countries supporting Rewards see the Reference Data API Module: countries endpoint |
customOrderingData.key | String Max length: 36 | Optional | Dynamic field key |
customOrderingData.value | String Max length: 256 | Optional | Dynamic field value |
purposeOfTransaction | String Max length: 20 | Optional | Identifies the Purpose of Transaction. This field is required for certain destination countries. NOTE: For a list of destination countries requiring the purposeOfTransaction field see the Reference Data API Module: countries endpoint |
sourceOfFunds | String Max length: 20 | Optional | Identifies the Source of Funds. This field is required for certain destination countries. NOTE: For a list of destination countries requiring the sourceOfFunds field see the Reference Data API Module: countries endpoint |
extendedData | Dynamic | Optional | Dynamic field key/values |
Response Fields
| Field | Type | Required/Optional | Description |
|---|---|---|---|
transactions.transactionId | String Max length: 36 | Required | Unique identifier for the transaction resource |
transactions.serviceOptionCode | String Max length: 21 | Required | Unique category code to identify the transaction method NOTE: For a full list of accepted service option codes per destination country see the Reference Data API Module: service-options endpoint |
transactions.serviceOptionName | String Max length: 50 | Required | Consumer facing name to identify the transaction method |
transactions.serviceOptionRoutingCode | String Max length: 21 | Optional | Unique code to identify the individual transaction method NOTE: For a full list of accepted service option routing codes per destination country see the Reference Data API Module: service-options endpoint |
transactions.serviceOptionRoutingName | String Max length: 50 | Optional | Unique name to identify the individual transaction method |
transaction.estimatedDelivery | String | Required | Estimated delivery time of the transaction |
transactions.sendAmount.amount | String Min length: 0 Max length: 14 Max decimal Value: 3 | Required | Transaction amount value and currency type excluding fees and exchange rate. NOTE: For Crypto partners this is the fiat currency for the BUY/Sell or Ramp-on/Ramp-off For a full list of transaction currency codes see the API Reference Data Module: currencies endpoint |
transactions.sendAmount.fees | String Min length: 0 Max length: 14 Max Decimal Value: 3 | Required | Fee Amount and Fee Currency applied to transaction (Fee Currency uses ISO alpha-3 code) |
transactions.sendAmount.taxes | String Min length: 0 Max length: 14 Max Decimal Value: 3 | Optional | Tax Amount and Tax Currency applied to the Transaction by the the origin country (Tax Currency uses ISO alpha-3 code) |
transactions.sendAmount.additionalCharges.typeCode | String | Optional | Code to indicate if the fee is to be collected by MoneyGram or the partner |
transactions.sendAmount.additionalCharges.label | String | Optional | Consumer facing name to identify the charge type |
transactions.sendAmount.additionalCharges.value | String | Optional | Additional fee's amount |
transactions.sendAmount.additionalCharges.currencyCode | String | Optional | Additional fee's Currency (ISO alpha-3 code) |
transactions.sendAmount.discountsApplied.totalDiscount | String Min length: 0 Max length: 14 Max Decimal Value: 3 | Optional | Transaction discount amount applied and currency type excluding fees and exchange rate. Transaction Currency (ISO alpha-3 code) |
transactions.sendAmount.discountsApplied.promotionDetails | String Min length: 0 Max length: 14 Max Decimal Value: 3 | Optional | Discount code associated with a specific business promotion |
transactions.sendAmount.total | String Min length: 0 Max length: 14 Max Decimal Value: 3 | Required | Transaction Total Amount and Transaction Total Currency including fees, taxes and discount. (Transaction Total Amount uses ISO alpha-3 code) |
transactions.receiveAmount.amount | String Min length: 0 Max length: 14 Max Decimal Value: 3 | Required | Transaction Received Amount and Transaction Receive currency (Transaction Total Amount uses ISO alpha-3 code) |
transactions.receiveAmount.fees | String Min length: 0 Max length: 14 Max Decimal Value: 3 | Optional | Received Fee and Receive Currency applied to the transaction by the destination country (Transaction Total Amount uses ISO alpha-3 code) |
transactions.receiveAmount.taxes | String Min length: 0 Max length: 14 Max Decimal Value: 3 | Optional | Tax Amount and Tax Currency applied to the Transaction by the the |
transactions.receiveAmount.additionalCharges.typeCode | String | Optional | Code to indicate if the fee is to be collected by MoneyGram or the partner |
transactions.receiveAmount.additionalCharges.label | String | Optional | Consumer facing name to identify the charge type |
transactions.receiveAmount.additionalCharges.value | String | Optional | Additional fee's amount |
transactions.receiveAmount.additionalCharges.currencyCode | String | Optional | Additional fee's Currency (ISO alpha-3 code) |
transactions.receiveAmount.total | String Min length: 0 Max length: 14 Max Decimal Value: 3 | Required | Receive Amount Total and Receive Transaction Currency to be picked-up/deposited in destination country including fees, taxes and discount (Transaction Total Amount uses ISO alpha-3 code) |
transactions.receiveAmount.fxRate | Number Max Decimal Value: 6 | Required | FX Rate applied to transaction |
transactions.receiveAmount.fxRateEstimated | Boolean | Optional | Indicates whether the Fx is "estimated" and amount, taxes and total cannot be guaranteed. The word "estimated" must appear before receiveAmount.amount, receiveAmount.fees, receiveAmount.taxes and receiveAmount.total only when true. |
Updated 2 days ago