Account Validate API

POST /v1/accounts/validate

Who calls this? MoneyGram invokes the receiving institution's Account Validate endpoint. The receiving institution validates the request and returns the verification result synchronously.

Request fields

Sender details

Field	Required	Type	Description
`transaction.sender.person.firstName`	Optional	String (1/50)	Sender first name.
`transaction.sender.person.middleName`	Optional	String (0/50)	Sender middle name.
`transaction.sender.person.lastName`	Optional	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.

Transaction

Field	Required	Type	Description
`receiveAmount.value`	Required	Decimal (12,3)	Receive amount in transacting currency. Must be greater than `0`.
`receiveAmount.currencyCode`	Required	String (3)	ISO 4217 currency code.
`accountCode`	Required	String (1/15)	Bank code, routing code, wallet provider, or IFSC code — used to route the credit to the beneficiary institution.
`accountNumber`	Required	String (1/X)	Beneficiary bank account or wallet number. Format agreed bilaterally with the partner.
`receiveCountryCode`	Required	String (3)	ISO 3166-1 alpha-3 country code where funds are credited.

Additional data

Extra context for regulatory and routing purposes is sent as key-value pairs inside the additionalData array. All supported keys are always included in the payload (values may be empty) for forward compatibility.

Key	Description
`purposeOfTransaction`	Purpose of remittance.
`senderCountryCode`	Sender country ISO code.
`senderIdType`	Type of sender identification.
`senderIdNumber`	Sender identification number.
`senderNationality`	Sender nationality.
`senderAddressLine1`	Sender address.
`senderDateOfBirth`	Sender date of birth (format: `YYYY-MM-DD`).

Example request

POST /v1/accounts/validate application/json

{
  "sender": {
    "person": {
      "firstName": "Chinwe",
      "middleName": "",
      "lastName": "Adebayo",
      "secondLastName": ""
    }
  },
  "receiver": {
    "person": {
      "firstName": "Kehinde",
      "middleName": "",
      "lastName": "Obi",
      "secondLastName": ""
    }
  },
  "accountCode": "<accountCode>",
  "accountNumber": "<accountNumber>",
  "receiveCountryCode": "<receiveCountryCode>",
  "receiveAmount": {
    "value": 130000.00,
    "currencyCode": "<currencyCode>"
  },
  "additionalData": [
    { "key": "purposeOfTransaction", "value": "" },
    { "key": "senderCountryCode",    "value": "" },
    { "key": "senderIdType",         "value": "" },
    { "key": "senderIdNumber",       "value": "" },
    { "key": "senderNationality",    "value": "" },
    { "key": "senderAddressLine1",   "value": "" },
    { "key": "senderDateOfBirth",    "value": "" }
  ]
}

Responses

200 OK Successful validation

The response body is optional. Partners may enrich the response with receiver account details.

Attribute	Type	Description
`message`	String	Optional response message.
`receiver.accountTitle`	String	Name associated with the account.
`receiver.accountStatus`	String	Account status.
`receiver.accountCurrency`	String	Currency of the account.
`receiver.nameMatchPercentage`	String	Percentage match between the beneficiary name and the institution's records.
`receiver.accountType`	String	Type of account.

HTTP/1.1 200 OK application/json

{
  "message": "Success",
  "receiver": {
    "accountTitle": "",
    "accountStatus": "",
    "accountCurrency": "",
    "nameMatchPercentage": "",
    "accountType": ""
  }
}

4xx / 5xx Validation failed

On failure, return an error object. Optional receiver attributes may still be included for context.

Attribute	Type	Description
`error.code`	String	MoneyGram-defined error code.
`error.message`	String	Human-readable error message.
`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

Returns 200 OK on successful validation. The body is optional; see Responses for the receiver attributes that may be included.

400 Bad Request Validation failure

Error code	Scenario	Message
`01`	Name mismatch	Account Name mismatch
`02`	Invalid account number	Invalid Account Number
`03`	Currency mismatch	Account not eligible for this transaction
`04`	Account does not exist	Account Number does not exist
`05`	Invalid amount	Invalid Amount
`11`	Account blocked	Account Blocked
`13`	Invalid bank / routing code	Invalid Bank/Routing code
`15`	Invalid account type	Invalid Bank Account Type
`16`	Bank unavailable	Bank not available / closed
`22`	Invalid request format	Invalid Request
`24`	Transfer limit exceeded	Transfer limit exceeded
`29`	Service not allowed	Service not allowed
`36`	Other validation failure	Other
`41`	Daily limit exceeded	Maximum number of transactions per day exceeded
`42`	Monthly limit exceeded	Maximum number of transactions per month exceeded
`43`	Below minimum amount	Minimum Amount not met

401 Unauthorized

Error code	Scenario	Message
`27`	Unauthorized request	Unauthorized

500 Internal Server Error Server-side failure

Error code	Scenario	Message
`10`	Validation timeout	Unable to verify account
`12`	Transaction processing error	Transaction cannot be completed
`20`	Internal partner error	Internal Error
`30`	Central switch error	Unable to process transaction

503 Service Unavailable

Error code	Scenario	Message
`40`	Downstream service unavailable	Service unavailable for downstream bank