Transfer Funds

POST /v1/transfers

Partner workflow

Validate the request payload.
Process the disbursement transaction.
Return a synchronous acknowledgement response.
Report the final transaction status asynchronously via the Status Webhook.

Synchronous acknowledgement, asynchronous settlement This endpoint is synchronous and expects a prompt acknowledgement. Final transaction status should be delivered subsequently via the Status Webhook.

Network (HTTP) headers

Header	Delivery type	Value	Description
`X-MG-DELIVERY-TYPE`	Account Deposit	`BANK_DEPOSIT`	Disbursement credited to a bank account.
`X-MG-DELIVERY-TYPE`	Wallet	`DIRECT_TO_ACCT`	Disbursement credited to a mobile wallet.

Request fields

Transaction details

Field	Required	Type	Description
`transaction.mgiTransactionId`	Required	String (20)	Unique MoneyGram transaction identifier. Format: `XXXXXXXX0000MMddYYYY`.
`transaction.receiveCountryCode`	Required	String (3)	ISO 3166-1 alpha-3 country code where funds are credited.
`transaction.sendCountryCode`	Required	String (3)	ISO 3166-1 alpha-3 country code where funds originate.
`transaction.receiveAmount.value`	Required	Decimal (12,3)	Transaction receive amount.
`transaction.receiveAmount.currencyCode`	Required	String (3)	ISO 4217 currency code.

Sender details

Field	Required	Type	Description
`transaction.sender.person.firstName`	Required	String (1/50)	Sender first name.
`transaction.sender.person.middleName`	Optional	String (0/50)	Sender middle name.
`transaction.sender.person.lastName`	Required	String (1/50)	Sender last name.
`transaction.sender.person.secondLastName`	Optional	String (0/50)	Sender second last name.

Allowed characters: [a-zA-Z \u00C0-\u017F\-\'\/]. Special characters such as - / ' may appear.

Receiver details

Field	Required	Type	Description
`transaction.receiver.person.firstName`	Required	String (1/50)	Beneficiary first name.
`transaction.receiver.person.middleName`	Optional	String (0/50)	Beneficiary middle name.
`transaction.receiver.person.lastName`	Required	String (1/50)	Beneficiary last name.
`transaction.receiver.person.secondLastName`	Optional	String (0/50)	Beneficiary second last name.

Account details

Field	Required	Type	Description
`accountCode`	Required	String (1/15)	Bank code, routing code, wallet provider name, or IFSC.
`accountNumber`	Required	String (1/X)	Beneficiary account or wallet number.

Additional data

Supplementary information may be required depending on the corridor or regulatory obligations. These values are transmitted as key-value pairs within transaction.additionalData.

Key	Description
`purposeOfTransaction`	Purpose of the transfer. See Purpose of Transaction values.
`senderCountryCode`	Sender country (ISO).
`senderIdType`	Type of sender identification. See Remitter ID type values.
`senderIdNumber`	Sender identification number.
`senderNationality`	Sender nationality.
`senderAddressLine1`	Sender address.
`senderCity`	Sender city.
`senderDateOfBirth`	Sender date of birth (`YYYY-MM-DD`).
`sourceOfFund`	Source of funds. See Source of Funds values.
`senderRelationshipToReceiver`	Relationship between sender and beneficiary. See Relationship to Receiver values.

Allowed characters for address fields: [a-zA-Z0-9 \u00C0-\u017F\#\/\.\"\'\,\(\)\-].

Example request

POST /v1/transfers application/json

{
  "transaction": {
    "mgiTransactionId": "99999999000020180524",
    "receiveCountryCode": "IND",
    "sendCountryCode": "USA",
    "receiveAmount": {
      "value": "500.23",
      "currencyCode": "INR"
    },
    "sender": {
      "person": {
        "firstName": "Mark",
        "middleName": "",
        "lastName": "Greg",
        "secondLastName": ""
      }
    },
    "receiver": {
      "person": {
        "firstName": "Lewis",
        "middleName": "",
        "lastName": "Jack",
        "secondLastName": ""
      }
    },
    "additionalData": [
      { "key": "purposeOfTransaction",         "value": "" },
      { "key": "senderCountryCode",            "value": "" },
      { "key": "senderIdType",                 "value": "" },
      { "key": "senderIdNumber",               "value": "" },
      { "key": "senderNationality",            "value": "" },
      { "key": "senderAddressLine1",           "value": "" },
      { "key": "senderCity",                   "value": "" },
      { "key": "senderDateOfBirth",            "value": "" },
      { "key": "sourceOfFund",                 "value": "" },
      { "key": "senderRelationshipToReceiver", "value": "" }
    ]
  },
  "accountCode": "<accountCode>",
  "accountNumber": "<accountNumber>"
}

Responses

200 OK Acknowledgement

Attribute	Type	Description
`response.responseCode`	String	Transaction processing status.
`response.message`	String	Human-readable status message.
`partnerTransactionId`	String	Optional partner transaction reference.

HTTP/1.1 200 OK application/json

{
  "response": {
    "responseCode": "PEN1200",
    "message": "Transaction Acknowledged; In Progress"
  },
  "partnerTransactionId": "988588585869"
}

4xx Validation error

If the request fails validation, return an error object.

Attribute	Type	Description
`error.code`	String	MoneyGram-defined error code.
`error.message`	String	Description of the error.
`error.target`	String	Field causing the error.

HTTP/1.1 400 Bad Request application/json

{
  "error": {
    "code": "02",
    "message": "Invalid Account",
    "target": "accountNumber"
  }
}

Response codes

200 OK Success

Code	Scenario
`PEN1200`	Acknowledged — delivery in progress
`REC1504`	Received — confirmed credited
`REC1505`	Received — assumed credited

400 Bad Request Validation / business rejection

Code	Scenario
`01`	Account Name mismatch
`02`	Invalid Account Number
`03`	Account not eligible for this transaction
`04`	Account Number does not exist
`05`	Invalid Amount / Currency
`06`	Invalid Sender
`07`	Invalid Date of Birth
`08`	Invalid State
`09`	Invalid Country
`11`	Account Blocked
`13`	Invalid Bank / Routing code
`15`	Invalid Bank Account Type
`16`	Bank not available / closed
`21`	Invalid Transaction
`22`	Invalid Request
`23`	Transaction frequency exceeded
`24`	Transfer limit exceeded
`25`	Exchange rate error
`26`	Suspected fraud
`29`	Service not allowed
`36`	Other
`37`	Transaction cannot be completed — violation of law
`38`	Transaction does not fulfil AML requirement
`41`	Maximum number of transactions per day exceeded
`42`	Maximum number of transactions per month exceeded
`43`	Minimum amount for processing the transaction not met

500 Internal Server Error Server-side failure

Code	Scenario
`10`	Unable to verify account
`12`	Transaction cannot be completed
`20`	Internal Error
`30`	Unable to process transaction

503 Service Unavailable

Code	Scenario
`40`	Service unavailable for downstream bank

Duplicate handling

MoneyGram may retry the Fund Transfer request in the event of network or timeout issues. Partners must implement idempotency keyed on transaction.mgiTransactionId. When the same transaction is received again, the partner must respond based on the current processing state:

Scenario	Expected response
Transaction still processing	Return `PEN1200`
Transaction already credited	Return `REC1504`
Transaction previously rejected	Return the original rejection response

Retry flow

MoneyGram calls Fund Transfer; partner responds PEN1200.
MoneyGram's response is lost due to network or operational issue.
MoneyGram retries with the same mgiTransactionId.
Partner returns current state: PEN1200, REC1504, or original rejection.

Prefunding handling

For corridors requiring prefunding with the partner institution, the following rules apply when the MoneyGram prefund account is temporarily unavailable:

Do not reject on prefund issues The partner must not reject the transaction. Instead:

Return PEN1200 to acknowledge the transaction.
Hold the transaction as pending until prefund is replenished.
Process normally once prefunding is restored.
Report the final status via the Partner Connect API.

If the transaction is ultimately rejected, funds are refunded to the sender.

Implementation expectations

Capability	Expectation
Request validation	Validate required fields, formats, and bilaterally agreed data rules.
Duplicate handling	Detect duplicate requests using `mgiTransactionId`.
Pending handling	Support `PEN1200` for in-progress transactions.
Final status update	Deliver the final transaction status via the Partner Connect API.
Prefunding support	Hold and resume transactions when prefund issues exist.
Optional data handling	Support agreed optional and conditional fields.
Configurable value lists	Treat ID type, purpose, source-of-funds, and relationship value lists as configurable; do not reject on unrecognised values.
Error mapping	Return MoneyGram standard response and error codes.

Field value reference

Treat these lists as configurable These values may change without notice if there are regulatory changes on the send side. Each field should be implemented as a configurable item, and a transaction must not be rejected if a new, previously unseen value is received.

Remitter ID type values — senderIdType

ALIEN_ID DRIVERS_LICENSE GOVERNMENT_ID INTERNATIONAL_ID PASSPORT SOCIAL_SECURITY_NUMBER STATE_ID TAX_ID

Purpose of Transaction values — purposeOfTransaction

BUSINESS_EXPENSE DONATION EDUCATION_TRAIN XFER_OWN_SAVNG FAMILY_SUPPORT GIFT INVEST_SAVING LEGAL_OBLIGATION LOAN PURCHASE_GOODS TRAVEL_EXPENSES TRAVEL_EXPENSES_VACATION TRAVEL_EXPENSES_MEDICAL HOUSE_CONSTRUCTION INSURANCE_PAYMENTS PENSION RNT_PYMT_ON_PROPRTY_HLD_ABROAD SUBSCRIPTIONS TICKETS_FOR_INTL_AIR_TRAVEL TICKETS_FOR_INTL_LAND_TRAVEL MEDICAL VACATION_EXPENSES SALARY BILLS FOOD BUSINESS_RELATED FAMILY_FRIENDS_SUPPORT PERSONAL_USE FAMILY_MAINTENANCE OTHERS

Source of Funds values — sourceOfFund

FAMILY_FUNDS GIFT_WINNINGS INHERITANCE LOAN LOTTERY_GAMBLING PENSION SALARY_EMPLOY SALE_OF_PROPERTY SAVINGS SOCIAL_BENEFITS THIRD_PARTY OTHERS

Relationship to Receiver values — senderRelationshipToReceiver

ACQUAINTANCE BUSINESS_PARTNER CLIENT CONTRACTOR EMPLOYER EMPLOY_EMPLOYER FAMILY FRIEND MYSELF ONLINE_FRIEND THIRD_PARTY VENDOR OTHERS