PUT Update a Transaction
PUT /payout/v1/transactions/{transactionId}
Development Guide
The 'Update a Transaction' endpoint determines what information to collect from the consumer, validates the data for compliance purposes and updates the transactionId resource with the data collected.
1. Prepare headers, authentication & parameters
The application must call the 'Update a Transaction' endpoint with a PUT HTTP method, providing the OAuth access_token , the transactionId as a path parameter and all other required headers.
Note:
- MoneyGram uses the OAuth 2.0 framework. The application must use their OAuth client credentials to generate an
access_tokenby 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
transactionIdshould have been returned on the previous Retrieve a tTansaction endpoint response.
Launch Code Example:
👉Payout - Update a Transaction - HeadersOpen Recipe
2. Provide payoutId in the request body:
payoutId in the request body:To Update a Transaction, it is required to pass the refundId which was returned on the previous Retrieve a Transaction API response and all other required fields.
Launch Code Example:
👉Payout - Update a Transaction - payoutIDOpen Recipe
3. Provide request body:
The request body must include the payoutId that was generated and returned in the previous 'Retrieve a transaction’ endpoint and at a minimum collect the receiver.address, receiver.primaryIdentification and receiver.dateOfBirth for MoneyGram to perform a real-time validation and compliance screening.
Note:
- To understand a full list of REQUIRED and OPTIONAL fields, the application can call the Retrieve transactional send fields API. Learn More
- Additional data collection may be required based on the
receiveAmountanddestinationCountryCode.
Launch Code Example:
👉Payout - Update a Transaction - Request BodyOpen Recipe
4. Make a request and handle response
The application must call the 'Update 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 |
"readyForCommit": true
When the 'Update a transaction' endpoint responds with a 200 HTTP Status the response will return the following fields:readyForCommit, andtransactionId.
- Failed | Handle the Error | 400 Bad Request HTTP Status
When the 'Update 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 validation.
Note:
- In some scenario's, enhanced due diligence is need to be undertaken on the consumer. A specific error code will be returned and an array of offending fields. The fields/values need to be provided and resubmitted on the Update API for further checks
- In some cases, send or receive side taxes may be applied. Learn More
- Only when the
"readyForCommit": true, is returned can the application proceed to "Commit a transaction" API and execute the payout of funds.
Launch Code Example:
👉Payout - Update a Transaction - 200 OKcipe TitleOpen Recipe.
👉Payout - Update a transaction - 400 Bad RequestOpen Recipe
5. You're Done! Proceed to the 'Commit a transaction API'
The application can call the Commit endpoint to execute the payout when a 200 HTTP Success Status is returned from the 'Update a transaction' response. The application must use the same transactionId on the subsequent Commit API by providing it as a path parameter. The Commit endpoint is the final API call and will execute the payout.
Note:
- To execute the refund, the
transactionIdreturned in the payload must be persisted and used as a path parameter on subsequent 'Commit a Transaction' API.- To execute the refund, the
payoutIdreturned in the payload must be persisted and used as in the request body of the subsequent 'Commit a Transaction' API.
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 sametransactionIdandpayoutIdto 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
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.
| Name | HTTP Method | Endpoints | Description |
|---|---|---|---|
| Retrieve Countries | GET | /reference-data/v1/Country | Retrieves supported values and metadata for countries |
| Retrieve Countries ISO3 | GET | /reference-data/v1 /countries/{iso3Code} | Retrieves supported values and metadata for countries by ISO 3 Code |
| Retrieve Currencies | GET | /reference-data/v1/currencies | Retrieves supported values and metadata for currencies |
| Retrieve Enumerations | GET | /reference-data/v1/enumerations | Retrieves enumerated values for fields |
| Retrieve Identification Documents | GET | /reference-data/v1/identification-Documents | Retrieves required fields for identification documents |
| Retrieve Service Options | GET | /reference-data/v1/payout-options | Retrieves supported values and metadata for Service Options |
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-SessionId | String | Conditionally Required | A GUID MoneyGram generates for correlating multiple calls within a transaction session. Note: The X-MG-SessionId is not required if the payoutId is passed in the request body. |
X-MG-ConsumerIPAddress | String | Optional | IP address of the system initiating the session. |
Query parameters
| Field | Type | Required/ Optional | Description |
|---|---|---|---|
targetAudience | String | Optional | Tailors MoneyGram’s error messages and field metadata to an in-store, digital or crypto consumer. (Enumerated value) NOTE: For a full list of accepted target audience values. See the TARGET_AUDIENCE enumeration from the Reference Data Enumerations endpoint |
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 |
operatorId | 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 |
|---|---|---|---|
payoutId | String | Conditionally Required | Unique identifier for the transaction session Note: The payoutId is not required if the X-MG-SessionId is passed as a header parameter. |
receiver.address.line1 | String Min length: 5 Max length: 30 | Required | Residence address line 1 |
receiver.address.line2 | String Min length: 0 Max length: 30 | Optional | Residence address line 2 (if applicable) |
receiver.address.line3 | String Min length: 0 Max length: 30 | Optional | Residence address line 3 (if applicable) |
receiver.address.city | String Min length: 1 Max length: 20 | Required | City of residence |
receiver.address.countrySubdivisionCode | String Length: 6 | Optional | State/province of residence |
receiver.address.countryCode | String Length: 3 | Required | Country of residence (ISO Alpha-3 Code) |
receiver.address.postalCode | String Min length: 2 Max length: 10 | Optional | Postal code/ZIP code of residence |
receiver.mobilePhone.number | String Min length: 5 Max length: 14 | Optional | Phone number |
receiver.mobilePhone.countryDialCode | String Min length: 1 Max length: 3 | Optional | Country calling code (ISO alpha-3 code) |
receiver.email | String Min length: 1 Max length: 255 | Optional | Email address |
receiver.notificationPreferences.type | String | Optional | Type of notification content (Enumerated values) |
receiver.notificationPreferences.channel | String | Optional | Delivery method of notification (Enumerated value) |
receiver.notificationPreferences.optIn | Boolean | Optional | Flag to declare consumer opts in to notification type and method |
receiver.notificationLanguagePreference | String Max length: 6 | Optional | Language ISO Alpha-3 code |
receiver.personalDetails.genderCode | String | Optional | Gender (Enumerated value) |
receiver.personalDetails.dateOfBirth | String Length: 10 | Required | Date of birth (YYYY-MM-DD) |
receiver.personalDetails.birthCity | String Min length: 0 Max length: 20 | Optional | City of birth |
receiver.personalDetails.birthCountryCode | String Max Length: 3 | Required | Country of birth (ISO alpha-3 code) NOTE: For a full list of accepted birth.CountryCodes see ‘Reference data API module’ and the countryInfo endpoint: |
receiver.personalDetails.citizenshipCountryCode | String Max Length: 3 | Optional | Occupation/Employment (Enumerated value) |
receiver.personalDetails.occupationCode | String | Optional | Occupation/Employment (Enumerated value) NOTE: For a full list of accepted Occupation Codes. See the OCCUPATION enumeration from the Reference Data Enumerations endpoint |
receiver.personalDetails.politicalExposedPerson | Boolean | Optional | Flag to declare a Politically Exposed Person (PEP) |
receiver.personalDetails.nationalityCountryCode | String Min Length: 3 Max Length: 3 | Optional | Country of citizenship (ISO alpha-3 code) |
receiver.personalDetails.nationalityCountryCode | String Min Length: 3 Max Length: 3 | Optional | Country of citizenship (ISO alpha-3 code) |
receiver.primaryIdentification.typeCode | String | Required | Type of identification document (Enumerated value) |
receiver.primaryIdentification.id | String Max length: 30 | Required | Identification document number |
receiver.primaryIdentification.issueCountrySubdivisionCode | String Max length: 6 | Optional | Issuing state/province of identification document |
receiver.primaryIdentification.issueCountryCode | String Max Length: 3 | Required | Issuing country of identification document |
receiver.primaryIdentification.expirationYear | String Length: 4 Format: YYYY | Optional | Expiration year of identification document (YYYY) |
receiver.primaryIdentification.expirationMonth | String Length: 4 Format: MM | Optional | Expiration month of identification document (MM) |
receiver.primaryIdentification.expirationDay | String Length: 4 Format: DD | Optional | Expiration month of identification document (DD) |
receiver.primaryIdentification.issueAuthority | String Min length: 0 Max length: 30 | Optional | Issuing authority of identification document |
<code>receiver.primaryIdentification.issueCity | String Min length: 0 Max length: 20 | Optional | Issuing city of identification document |
receiver.primaryIdentification.issueYear | String Length: 4 Format: YYYY | Optional | Issuing year of identification document (YYYY) |
receiver.primaryIdentification.issueMonth | String Length: 4 Format: MM | Optional | Issuing month of identification document (MM) |
receiver.primaryIdentification.issueDay | String Length: 4 Format: DD | Optional | Issuing day of identification document (DD) |
receiver.secondaryIdentification.typeCode | String Max length: 3 | Required | Type of identification document (Enumerated value) |
receiver.secondaryIdentification.id | String Max length: 30 | Required | Identification document number |
receiver.secondaryIdentification.issueCountrySubdivisionCode | String Max length: 6 | Optional | Issuing state/province of identification document |
receiver.secondaryIdentification.issueCountryCode | String Max length: 3 | Required | Issuing country of identification document |
receiver.secondaryIdentification.expirationYear | String Length: 4 Format: YYYY | Optional | Expiration year of identification document (YYYY) |
receiver.secondaryIdentification.expirationMonth | String Length: 4 Format: MM | Optional | Expiration month of identification document (MM) |
receiver.secondaryIdentification.expirationDay | String Length: 4 Format: DD | Optional | Expiration month of identification document (DD) |
receiver.secondaryIdentification.issueAuthority | String Min length: 0 Max length: 30 | Optional | Issuing authority of identification document |
receiver.secondaryIdentification.issueCity | String Min length: 0 Max length: 20 | Optional | Issuing city of identification document |
receiver.secondaryIdentification.issueYear | String Length: 4 Format: YYYY | Optional | Issuing year of identification document (YYYY) |
receiver.secondaryIdentification.issueMonth | String Length: 4 Format: MM | Optional | Issuing month of identification document (MM) |
receiver.secondaryIdentification.issueDay | String Length: 4 Format: DD | Optional | Issuing day of identification document (DD) |
receiver.additionalAddress.type | String | Optional | Type of additional address (Enumerated values) |
receiver.additionalAddress.line1 | String Min length: 5 Max length: 30 | Required | Residence address line 1 |
receiver.additionalAddress.line2 | String Min length: 0 Max length: 30 | Optional | Residence address line 2 (if applicable) |
receiver.additionalAddress.line3 | String Min length: 0 Max length: 30 | Optional | Residence address line 3 (if applicable) |
receiver.additionalAddress.city | String Min length: 0 Max length: 20 | Required | City of residence |
receiver.additionalAddress.countrySubdivisionCode | String Max Length: 6 | Optional | State/province of residence |
receiver.additionalAddress.countryCode | String Max length: 3 | Required | Country of residence (ISO Alpha-3 Code) |
receiver.additionalAddress.postalCode | String Min length: 2 Max length: 6 | Optional | Postal code/ZIP code of residence |
receiver.additionalFamilyNames.type | String | Optional | Type of family name (Enumerated values) |
receiver.additionalFamilyNames.firstName | String Min length: 0 Max length: 20 | Optional | First name |
receiver.additionalFamilyNames.middleName | String Min length: 0 Max length: 20 | Optional | Middle name (if applicable) |
receiver.additionalFamilyNames.lastName | String Min length: 0 Max length: 30 | Optional | Last name |
receiver.additionalFamilyNames.secondLastName | String Min length: 0 Max length: 30 | Optional | Second last name |
receiver.profileId | String | Optional | Consumer's unique identifier |
receiver.additionalDetails | Dynamic | Optional | Dynamic field/key value |
relationshipToSender | String Max length: 30 | Optional | Receiver’s relationship to sender based on (Enumerated Values) NOTE: For a full list of accepted relationship to sender values. See the RELATIONSHP_TO_SNDR enumeration from the Reference Data Enumerations endpoint |
receivePurposeOfTransaction | String Max length: 50 | Optional | Receiver’s purpose for the transaction (Enumerated Values) NOTE: For a full list of accepted purpose of transaction values. See the PURPSE_OF_TRNSCTION enumeration from the Reference Data Enumerations endpoint |
intendedUseOfMGIServices | String Max length: 50 | Optional | Receiver’s intended use of MGI services (Enumerated Values) NOTE: For a full list of accepted use of MGI services values. See the TYPICAL_USE_OF_MGI enumeration from the Reference Data Enumerations endpoint |
Response fields
| Field | Type | Required/ Optional | Description |
|---|---|---|---|
readyForCommit | Boolean | Required | Indicates whether the transaction can proceed to commit |
transactionId | String Max length: 36 | Required | Unique identifier for the transaction resource |
Updated 14 days ago
