Payment Errors

Acquire a better understanding of Maya's Payment error codes and their resolution methods to ensure appropriate management of errors.

Maya Payment Solutions adopts a RESTful architecture and relies on HTTP response and codes to notify clients about the outcome of their requests, whether successful or not.

Error responses are returned in JSON format:

{
    "code": "PY0009",
    "message": "Payment does not exist.",
}

ℹ️ Error Code: 2553

If an error with a 2553 code appears in the response body, there will be a parameter object - an array of object containing information about the invalid fields for other errors.
{
    "code": "2553",
    "message": "Missing/invalid parameters.",
    "parameters": [
        {
            "description": "value must be a number",
            "field": "totalAmount.value"
        },
        {
            "description": "A valid currency is required.",
            "field": "totalAmount.currency"
        }
    ]
}

Error Codes

Error codes, which are alphanumeric in nature, are associated with certain errors and are integral to the suggested error management procedures. See below list of errors:

General Errors

Error Code (`code`)	HTTP Status	Description (`message`)	What to do?
2553	400	Missing/invalid parameters.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS This message will appear if any of the mandatory request payload properties are absent or do not conform to the given specifications. We suggest that you validate your request and ensure that you furnish all the required payload properties with accurate values.
PY0001	400	Generic system error.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS If an unspecified error occurs, this generic error code will be returned, and it is advisable to attempt the operation again. ℹ️ If the error persists even after multiple retries, please escalate the issue to Support by providing any of the following: -`customerId` or `linkId` -`paymentId`
PY0064	400	Invalid JSON Format.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS This error will arise if the payload request is not a valid JSON format. Please check your payload and ensure that you are sending the correct JSON format.

Server Related Errors

Error Code (`code`)	HTTP Status	Description (`message`)	What to do?
PY9999 PY0013 PY0014 PY0015 PY0016 PY0040 PY0041 PY0059 PY0060 PY0066 PY0067 PY0069 PY0122 PY0143 PY0144	400	System has encountered a systematic error or is unreachable / timed out.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS ℹ️ If the error persists even after multiple retries, please escalate the issue to Support by providing any of the following: -`customerId` or `linkId` -`paymentId`

Third Party Errors

Error Code (`code`)	HTTP Status	Description (`message`)	What to do?
PY0114	400	WeChat Service unreachable / timed out.	Product/s: INVOICE CHECKOUTVAULTPLUGINS WeChat service is unreachable or taking too long to respond. Kindly retry transaction. ℹ️ If the error persists even after multiple retries, please escalate the issue to Support.
PY0115	400	WeChat Service error.	Product/s: INVOICE CHECKOUTVAULTPLUGINS This is a systematic error on WeChat Service. Kindly retry transaction. ℹ️ If the error persists even after multiple retries, please escalate the issue to Support.
PY0129	400	GCash Service unreachable / timed out.	Product/s: INVOICE CHECKOUTVAULTPLUGINS GCash Service is unreachable or taking too long to respond. Kindly retry transaction. ℹ️ If the error persists even after multiple retries, please escalate the issue to Support.
PY0130	400	GCash Service error.	Product/s: INVOICE CHECKOUTVAULTPLUGINS This is a systematic error on GCash Service. Kindly retry transaction. ℹ️ If the error persists even after multiple retries, please escalate the issue to Support.
PY0134	400	ShopeePay Service unreachable / timed out	Product/s: INVOICE CHECKOUTVAULTPLUGINS ShopeePay Service is unreachable or taking too long to respond. Kindly retry transaction. ℹ️ If the error persists even after multiple retries, please escalate the issue to Support.
PY0135	400	ShopeePay Service error.	Product/s: INVOICE CHECKOUTVAULTPLUGINS This is a systematic error on ShopeePay Service. Kindly retry transaction. ℹ️ If the error persists even after multiple retries, please escalate the issue to Support.

Customer, Account and Card Related Errors

Error Code (`code`)	HTTP Status	Description (`message`)	What to do?
PY0021	400	Failed to add customer.	Product/s: VAULT This is a systemic error that occurs when creating a customer record. Please review the mandatory fields for creating a customer and try again. ℹ️ If the error persists even after multiple retries, please escalate the issue to Support.
PY0023	400	Customer does not exist.	Product/s: VAULT The `customerId` provided does not exist in the merchant's records. Please ensure that you have provided the correct `customerId` under your merchant and retry the operation.
PY0024	400	Failed to delete customer.	Product/s: VAULT This is a systematic error in deleting a customer record. Validate the status of the customer record by calling Retrieve Customer. If it still exist, retry sending another request to delete the customer record. ℹ️ If the error persists even after multiple retries, please escalate the issue to Support.
PY0025	400	Failed to update customer details.	Product/s: VAULT This is a systematic error in updating Customer details. Validate the status of the customer record by calling Retrieve Customer. If it exist and details are not modified, retry sending another request to update the customer record. ℹ️ If the error persists even after multiple retries, please escalate the issue to Support.
PY0127	400	Please update incomplete customer records.	Product/s: VAULT You will encounter this error when Fraud protection is enabled and the provided customer details are incomplete. Make sure to provide the minimum required customer details, as described in Fraud Protection guide, and retry the transaction.
PY0002 PY0121	400	Card is expired.	Product/s: INVOICE CHECKOUTVAULTPLUGINS ⚠️ Applicable for Card payments only. This occurs when an expired card is used. You can suggest to the customer to attempt the transaction using a valid and active card.
PY0026	400	Failed to update card details.	Product/s: VAULT This is a systematic error in updating Card details. Kindly retry transaction. ℹ️ If the error persists even after multiple retries, please escalate the issue to Support.
PY0027	404	Card does not exist.	Product/s: VAULT This error happens when the Card token does not exist for Customer. Validate that the Card token used is not deleted and kindly retry the transaction.
PY0028	400	Failed to delete card.	Product/s: VAULT This is a systematic error in deleting Card. Kindly retry transaction. Validate the Card record by calling Retrieve Card. If it is still exist, retry sending another request to delete the card record. ℹ️ If the error persists even after multiple retries, please escalate the issue to Support.
PY0029	400	No card found for customer.	Product/s: VAULT This error response will be encountered when no Card record is associated to the customer. Please ensure that you have successfully linked a card to this customer record.
PY0036	400	Card is not supported.	Product/s: INVOICE CHECKOUTVAULTPLUGINS ⚠️ Applicable for Card payments only. If you encounter this error, it means that the card scheme being used is not supported by the application. Please ensure that you are using one of the supported card schemes, which are MasterCard, Visa, and JCB.
PY0043	400	Card already exists.	Product/s: VAULT This error will happen if the card you are trying to link is already linked to the customer. Validate the Card record by calling Retrieve Card.
PY0117	400	Card is invalid.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS This error will happen if card being used is invalid or no longer valid (card BIN is not supported or card is inactive). Make sure you are using a valid and active card when making a transaction.
PY0007	400	Invalid token status.	Product/s: VAULT Please note that tokens are for one-time use only. This error will occur when the token has already been used on a transaction. Please create new token and retry the transaction.
PY0030	400	Invalid card token status.	Product/s: VAULT This error will happen if the Card token status is not allowed for payment. Possible reasons are any of the following: - Used Card Token - Deleted Card Token - Linking of Card token that is not successful Kindly retry transaction and use a valid and existing Card Token.
PY0008	400	Token is invalid.	Product/s: VAULT If the token is unavailable for payment, you will encounter this error. Please verify that the token is not expired or deleted. Kindly retry the transaction using a valid and existing token. ℹ️ If the error persists even after multiple retries, please escalate the issue to Support by providing any of the following: -`customerId` or `linkId` -`token`
PY0105	400	Account has insufficient balance to perform this transaction.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS Linked account or the account being used does not have sufficient balance to make the transaction. You can inform the user that the transaction was declined due to insufficient funds and advise them to cash in prior to making a transaction.
PY0119	400	Issuer declined card or account.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS You will encounter this issue when Issuer instructed to stop any transactions to be made using this card. Recommend to try with a different card.
PY0120	400	Issuer decline.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS You will encounter this error when customer has provided invalid card details (e.g. expired card, or wrong card number). Recommend to try a different card.
PY0123	400	Account limit exceeded.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS Linked account or the account being used has reached the maximum number of transactions. You can inform the user that the transaction was declined due to limit. They can retry the transaction on the next day or use other account.
PY0136	400	Account / Card is compromised.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS You will encounter this error when account was closed and is no longer usable. You have to unlink the account and ask user to link another account.

Payment-related Errors

Error Code (`code`)	HTTP Status	Description (`message`)	What to do?
PY0009 PY0076	404	Payment does not exist.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS If the `paymentId` provided does not correspond to any existing payment intent, this error will occur. Please verify the payment and ensure that you are passing the correct `paymentId`. You can also attempt to retrieve payment details (including the ID) by calling the Retrieve Payment via RRN endpoint to validate your `paymentId`.
PY0044	400	Payment is invalid.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS Will be encountered when `paymentId` does not exist. Make sure you have supplied a correct `paymentId` and retry again.
PY0057	422	The payment has expired and cannot be processed.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS You will encounter this error when a transaction exceeds the given time limit. You can also get and validate the payment status by calling the Retrieve Payment Status. Once a payment has expired, it cannot be processed any further. If the user still wishes to proceed with the payment, a new payment transaction must be created.
PY0103	400	Payment is already expired.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS You will encounter this error when a transaction exceeds the given time limit. You can also get and validate the payment status by calling the Retrieve Payment Status. Once a payment has expired, it cannot be processed any further. If the user still wishes to proceed with the payment, a new payment transaction must be created.
PY0093	400	Payment has already been updated.
PY0128	400	Payment is ineligible for the option/s provided.
PY0068	400	Payment not executed due to authorization failure.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS This is a systematic error for Authentication. Kindly retry transaction. ℹ️ If the error persists even after multiple retries, please escalate the issue to Support.
PY0094	400	Payment is not available for capture.	Product/s: INVOICE CHECKOUTVAULTPLUGINS Will be encountered when the payment state is not allowed to be captured. Validate the payment by getting the payment status via Retrieve Payment via ID endpoint. Kindly also refer to the Manual Capture document for the transition rules.
PY0095	400	Amount must be less than or equal to amount authorized.	Product/s: INVOICE CHECKOUTVAULTPLUGINS This error will occur when the requested amount to capture is greater that the authorization amount. Refer to Manual Capture and follow the recommended steps.
PY0096	400	Amount must be equal to amount authorized.	Product/s: INVOICE CHECKOUTVAULTPLUGINS This error will occur when the requested amount to capture is not equal to the authorization amount. Refer to Manual Capture and follow the recommended steps.
PY0017	401	Merchant not found.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS You will encounter this if there is a problem with the configuration of your merchant account. ℹ️ If the error occurs, please escalate the issue to Support.
PY0019	401	Forbidden.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS This error may happen when your merchant profile is not allowed to do a specific request. ℹ️ Please escalate the issue to your Relationship Manager.
PY0037	400	Currency is not supported.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS If you encounter this error, it means that the currency used in the payment is not supported by the merchant account. Please note that Maya currently only supports one currency per account, and if you require support for multiple currencies, you will need to request multiple accounts. Please review your transaction request and ensure that you are using the correct currency.
PY0058	400	The merchant indicated does not have P2M services enabled.	You will encounter this error when P2M service is not activated in your merchant profile. ℹ️ Please escalate the issue to your Relationship Manager.
PY0065	400	This merchant has no customizations present.	This error may happen from Get or Delete Customizations API. When this is raised, it means that the merchant’s request to Get or Delete is invalid because page customizations are already disabled to begin with. No further action required.
PY0070	400	Scheme is unsupported by merchant	You will encounter this error when specific card scheme is not enabled in your merchant profile. ℹ️ Please escalate the issue to your Relationship Manager.
PY0100	200	Authentication failed.	Product/s: INVOICE CHECKOUTVAULTPLUGINS ⚠️ Applicable for Card payments only. You will encounter this error when user fails to authenticate the request in 3DS.
PY0146	200	Login cancelled by user.	Product/s: PAY WITH MAYA You will encounter this error when customer decides to cancel the request during user login.
PY0101	400	Acquirer decline due to high risk.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS You will encounter this error when the transaction was suspected to be fraud. ℹ️ Please escalate the issue to Support by providing the `paymentId`
PY0137	400	Decline due to high risk.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS You will encounter this error when the transaction was suspected to be fraud. ℹ️ Please escalate the issue to Support by providing the `paymentId`
PY0138	400	Acquirer decline.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS You will encounter this error when the transaction was suspected to be fraud. ℹ️ Please escalate the issue to Support by providing the `paymentId`
PY0116	400	Transaction could not be completed.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS The operation you are trying to do with the transaction has encountered error. ℹ️ If the error persists even after multiple retries, please escalate the issue to Support by providing any of the following: -`paymentId` -`transactionId`
PY0124	400	Transaction could not be verified.	Product/s: INVOICE CHECKOUTVAULTPLUGINS ⚠️ Applicable for Card payments only. Reason for this error may vary depends on the 3DS verification.
PY0104	400	Reference number is linked to multiple payments.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS You will encounter this error when the payment you are trying to process using Reference number is linked to a multiple payment records. If you intend to process specific payment, you can try calling the endpoints that will use `paymentId`.
PY0045 PY0055	400	Payment is not available for void.	Product/s: INVOICE CHECKOUTVAULTPLUGINS You will come across this error if the payment is not eligible for void. Similarly, attempting to void the transaction beyond `12am GMT+8` of the transaction date will also result in encountering this error. Validate the payment by getting the payment status via Retrieve Payment via ID endpoint. Kindly also refer to the Manual Capture document for the transition rules. You may execute and validate voids using the Maya Business Manager.
PY0063	404	Void does not exist.	Product/s: INVOICE CHECKOUTVAULTPLUGINS Will be encountered when no void requests existed for the `paymentId` provided. Make sure you have supplied the correct `paymentId` and retry again. You may execute and validate voids using the Maya Business Manager.
PY0073	400	Transaction cannot be processed. Cannot void a transaction after cut off time.	Product/s: INVOICE CHECKOUTVAULTPLUGINS Authorized payments can only be voided before the 12am cut-off time.
PY0046	404	Refund does not exist.	Product/s: INVOICE CHECKOUTVAULTPLUGINS You will encounter this error if refundId does not exist. Validate if you are using a correct refundId and it is not currently deleted, then retry the request. You may execute and validate refunds using the Maya Business Manager.
PY0047	400	Payment is ineligible for refund.	Product/s: INVOICE CHECKOUTVAULTPLUGINS This error can be caused by either of the following reasons: 1. The transaction being refunded is not yet eligible according to cut-off rules. Refunds can only be initiated after 12am GMT+8 of the transaction date, which means you may have to wait until the start of the next day. 2. The transaction being refunded is older than 180 days. You may execute and validate refunds using the Maya Business Manager.
PY0048	400	Requested refund amount is greater than the original amount.	Product/s: INVOICE CHECKOUTVAULTPLUGINS This error will occur when the requested amount to refund is greater that the original amount. Validate your request and make sure your requested refund amount is the same as the original. You may execute and validate refunds using the Maya Business Manager.
PY0072	400	Transaction cannot be processed. Cannot refund a transaction before cut off time.	Product/s: INVOICE CHECKOUTVAULTPLUGINS Capture payments can only be refunded after the 12am cut-off time.
PY0082	400	Refund already exists.	Product/s: INVOICE CHECKOUTVAULTPLUGINS Will be encountered when `paymentId` already has a refund request. You may execute and validate refunds using the Maya Business Manager.
PY0113	400	Partial refund is not allowed for this transaction.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS You will come across this error if the payment is not eligible for partial refunds. Validate the payment by calling Retrieve Payment via ID endpoint. Kindly also refer to the Manual Capture document for the transition of status and refund rules. You may execute and validate refunds using the Maya Business Manager.

Webhook Errors

Error Code (`code`)	HTTP Status	Description (`message`)	What to do?
PY0038	404	Webhook does not exist.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS If you encounter this error, it means that the registration of the webhook was unsuccessful. Additionally, this error may also occur if the webhook endpoint is incorrect for a particular environment. Please note that the webhook endpoint differs between the sandbox environment and the production environment. You may want to check if the registered webhook exist via Maya Manager or by calling the Get Webhooks endpoint.
PY0039	400	Webhook already exists.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS This error happens if webhook has already been created. You may want to check if the registered webhook exist via Maya Manager or by calling the Get Webhooks endpoint. To retry the request, you may delete the existing webhook and define a new one.
PY0091	400	Payment state is invalid for sending webhooks.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS Review and expand your understanding on Maya’s webhooks by following this guide: Webhooks for Payment Solutions.
PY0092	400	Merchant's registered webhook is unreachable.	Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS Make sure you have registered the correct webhook URL that is up and running. For more details, see Webhooks for Payment Solutions.

Subscription related Errors

Error Code (`code`)	HTTP Status	Description (`message`)	What to do?
PY0042	400	Charging of subscription is not applicable.
PY0049	404	Subscription does not exist.	Will be encountered when subscription does not exist. Make sure you have supplied a correct subscription and retry again.
PY0051	400	Failed to update subscription details.	This is a systematic error in updating subscription details. Kindly retry transaction. ℹ️ If the error persists even after multiple retries, please escalate the issue to Support by providing the `subscriptionId`.
PY0052	400	Failed to cancel subscription.	This error will arise when there are errors in cancelling the subscription. Kindly retry transaction. ℹ️ If the error persists even after multiple retries, please escalate the issue to Support by providing the `subscriptionId`.
PY0054	400	Subscription already charged.	You will encounter this error when subscription your are trying to process has already been charged. To validate the status of the subscription, get the status via retrieve endpoint.