Errors

Reading a response

1. Look at the HTTP status. 2xx: request accepted. 4xx: a problem in your request. 5xx: a problem on the MoyaPay side or at the operator.
2. In a 200 response, always test the success field.
3. Then read the error detail: the description field (business errors) or message (validation and authentication errors).

Error responses come in four shapes, depending on the stage at which the request is rejected.

1. Business error

A refusal decided after the body is validated (account, payment method, duplicate, operator failure...). The HTTP status is repeated in code. The precise reason is in description; message is generic text.

{
  "status": "error",
  "description": "Marchand not have provider",
  "success": false,
  "code": 400,
  "message": "Invalid request parameters"
}

2. Body validation error

Missing or invalid field. The reason is in err.message.

{
  "err": {
    "status": "error",
    "message": "You must add telephone to your body",
    "code": 400
  }
}

For a few fields (business_code, country_code, merchant_transaction_id) and for /login, the same error is returned without the err envelope:

{
  "status": "error",
  "message": "You must add business_code to your body",
  "code": 400
}

3. Authentication error

Missing, invalid or expired token (HTTP 401). The exact text of message varies by route; only the HTTP status and success: false are stable.

{
  "success": false,
  "message": "No Bearer Token Provided",
  "code": 401
}

{
  "success": false,
  "message": "Token Signature could not be verified.",
  "code": 401,
  "error": "jwt expired"
}

4. Insufficient balance (payout)

A payout rejected for lack of balance returns a 400: the status field is FAILED, message gives the reason, and the response repeats your merchant_transaction_id. No transaction is created: you can retry with the same identifier after topping up your balance.

Common errors

HTTP	Where to read the reason	Reason	What to do
400	err.message	You must add <field> to your body	Add the missing field
400	err.message	PAYMENT_METHOD_NOT_EXIST	Use a code from Payment methods
400	err.message	Amount must be ...	Respect the Limits
400	err.message	Amount must be a number	Send amount as a number, not a string
400	err.message	Invalid payment_method add OTP field	Add otp_code (required for OM_CI)
400	err.message	CURRENCY_NOT_EXIST	Use a currency from the Currencies by country table
400	description	Currency not valid for this country, expected XOF	currency does not match the transaction's country: send the indicated currency, see Currencies by country
400	description	Phone number not valid	Fix the number, see Limits
400	description	Marchand not have provider	Payment method not enabled on your account: contact MoyaPay
400	description	Business not exist for this merchant contact administrator	business_code unknown or not belonging to your account
400	description	The merchant does not have any operator configured.	No payment method enabled: contact MoyaPay
400	description	An identical transaction is already in progress. Please wait.	Wait for the identical transaction to finish
400	description	Transaction ID ... allready existe	merchant_transaction_id already used: choose a new one
400	message	Insufficient balance (payout)	Top up the balance
401	message	Missing, invalid or expired token	Log in again via /login
401	message	Marchand not found for this user	Unknown refercence_cl. The code field in the body may be 404 while the HTTP status is 401
401	message	You are not authorized to perform this action for this marchand ...	refercence_cl does not match your account
401	description	Marchand disabled	Account disabled: contact MoyaPay
500	description	Impossible to make the transaction	Failure at the operator. Check the status before sending again
500	description	Impossible to get transaction	On /check-status: transaction not found

tip

Do not base your logic on the exact text of messages: they can be reworded. Rely on the HTTP status, on success, and on transaction statuses (SUCCESS, FAILED...).