Account Validate API

Preview · readme-account-validate

POST /v1/accounts/validate

Who calls this? MoneyGram invokes the 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`	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.

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

HTTP	Error code	Scenario	Message
200	—	Successful validation	—
400	`01`	Name mismatch	Account Name mismatch
400	`02`	Invalid account number	Invalid Account Number
400	`03`	Currency mismatch	Account not eligible for this transaction
400	`04`	Account does not exist	Account Number does not exist
400	`05`	Invalid amount	Invalid Amount
400	`11`	Account blocked	Account Blocked
400	`13`	Invalid bank / routing code	Invalid Bank/Routing code
400	`15`	Invalid account type	Invalid Bank Account Type
400	`16`	Bank unavailable	Bank not available / closed
400	`22`	Invalid request format	Invalid Request
400	`24`	Transfer limit exceeded	Transfer limit exceeded
400	`29`	Service not allowed	Service not allowed
400	`36`	Other validation failure	Other
400	`41`	Daily limit exceeded	Maximum number of transactions per day exceeded
400	`42`	Monthly limit exceeded	Maximum number of transactions per month exceeded
400	`43`	Below minimum amount	Minimum Amount not met
401	`27`	Unauthorized request	Unauthorized
500	`10`	Validation timeout	Unable to verify account
500	`12`	Transaction processing error	Transaction cannot be completed
500	`20`	Internal partner error	Internal Error
500	`30`	Central switch error	Unable to process transaction
503	`40`	Downstream service unavailable	Service unavailable for downstream bank