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.

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 À-ſ-'/]. 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.
`senderCountryCode`	Sender country (ISO).
`senderIdType`	Type of sender identification.
`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.
`senderRelationshipToReceiver`	Relationship between sender and beneficiary.

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

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

HTTP	Code	Scenario
200	`PEN1200`	Acknowledged — delivery in progress
200	`REC1504`	Received — confirmed credited
200	`REC1505`	Received — assumed credited
400	`01`	Account Name mismatch
400	`02`	Invalid Account Number
400	`03`	Account not eligible for this transaction
400	`04`	Account Number does not exist
400	`05`	Invalid Amount / Currency
400	`06`	Invalid Sender
400	`07`	Invalid Date of Birth
400	`08`	Invalid State
400	`09`	Invalid Country
400	`11`	Account Blocked
400	`13`	Invalid Bank / Routing code
400	`15`	Invalid Bank Account Type
400	`16`	Bank not available / closed
400	`21`	Invalid Transaction
400	`22`	Invalid Request
400	`23`	Transaction frequency exceeded
400	`24`	Transfer limit exceeded
400	`25`	Exchange rate error
400	`26`	Suspected fraud
400	`29`	Service not allowed
400	`36`	Other
400	`37`	Transaction cannot be completed — violation of law
400	`38`	Transaction does not fulfil AML requirement
400	`41`	Maximum number of transactions per day exceeded
400	`42`	Maximum number of transactions per month exceeded
400	`43`	Minimum amount for processing the transaction not met
500	`10`	Unable to verify account
500	`12`	Transaction cannot be completed
500	`20`	Internal Error
500	`30`	Unable to process transaction
503	`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.
Error mapping	Return MoneyGram standard response and error codes.