# Code and Formats source: https://developer.mastercard.com/cross-border-services/documentation/code-and-formats/index.md This section describes the HTTP status and reason codes, the error response structure, error and return message codes, timeout handling, and related resources for Mastercard Cross-Border Services. ## HTTP Status Codes and Reason Codes {#http-status-codes-and-reason-codes} Resource requests use HTTP response codes to provide a coarse grain indication of the result of each request. The following table lists the response codes that may be returned for requests. In the event of network or infrastructure issues, other response codes may be returned by the infrastructure. | HTTP status code | Reason Code | Response Description | Resolution Tips | |--------------------|-------------------|---------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------| | 200 (OK) | N/A | The request was completed successfully. | No action needed - request processed successfully. | | 201 (CREATED) | N/A | Successful creation occurred using a POST request. The Location header will contain a link to the newly-created resource. | No action needed - resource created successfully. Check Location header for new resource URL. | | 204 (NO CONTENT) | N/A | The server successfully processed the request and is not returning any content. | No action needed - resource updated/deleted successfully. | | 400 (BAD REQUEST) | BAD_REQUEST | General error when the request could not be fulfilled due to errors such as validation errors or missing required data. | Validate request parameters, check required fields, and ensure proper data formats before retrying. | | 401 (UNAUTHORIZED) | UNAUTHORIZED | Missing or invalid authentication token. | Verify authentication credentials, refresh tokens if expired, and ensure proper authorization headers are included. | | 403 (FORBIDDEN) | PERMISSION_DENIED | The user has insufficient permissions to a resource or action. | Contact administrator to verify user permissions or use an account with appropriate access rights. | | 404 (NOT FOUND) | NOT_FOUND | The requested resource was not found. | Verify the resource URL/ID is correct and the resource exists. Check for typos in the endpoint path. | ## Gateway Error Codes {#gateway-error-codes} For additional details on the HTTP errors returned by the gateway and possible resolutions, see [here](https://developer.mastercard.com/platform/documentation/gateway-error-codes). ## Error Structure {#error-structure} If a transaction cannot be processed, an error will occur. The error can be for a specific service format issue, network connection or overall message format issue. An error response will also be returned in the event the receiving entity returns a response code denoting a transaction is not authorized. In these cases, the response code and response description will also be returned in the details element of the error response. ### Field Descriptions: {#field-descriptions} * **RequestId** - A unique identifier for an API web service request. * **Source** - A unique identifier that attempts to define the field in error when available. In case of an error, when source ="Gateway" and the http status code = 4xx, transaction can be resubmitted using the same transaction reference Id. * **ReasonCode** - Identifies the reason for the error. * **Description** - Describes the reason for the problem. * **Recoverable** - A true/false response, intended for future use. * **Details** - A name/value pair for the error detail. ## Sample Errors {#sample-errors} ### Single Error Structure: {#single-error-structure} ```JSON { "Errors": { "Error": { "RequestId": "13559438", "Source": "proposal_id", "ReasonCode": "INVALID_INPUT_VALUE", "Description": "Invalid Input Value", "Recoverable": "false", "Details": { "Detail": { "Name": "ErrorDetailCode", "Value": "082000" } } } } } ``` ### Multiple Errors Structure: {#multiple-errors-structure} ```JSON { "Errors": { "Error": [ { "RequestId": "13559520", "Source": "sender_account_uri", "ReasonCode": "INVALID_INPUT_LENGTH", "Description": "Invalid length", "Recoverable": "false", "Details": { "Detail": { "Name": "ErrorDetailCode", "Value": "072000" } } }, { "RequestId": "13559520", "Source": "sender.government_ids.government_id_uri", "ReasonCode": "INVALID_INPUT_LENGTH", "Description": "Invalid length", "Recoverable": "false", "Details": { "Detail": { "Name": "ErrorDetailCode", "Value": "072000" } } }, { "RequestId": "13559520", "Source": "recipient.government_ids.government_id_uri", "ReasonCode": "INVALID_INPUT_LENGTH", "Description": "Invalid length", "Recoverable": "false", "Details": { "Detail": { "Name": "ErrorDetailCode", "Value": "072000" } } } ] } } ``` ## Error and Return Message Codes {#error-and-return-message-codes} For a complete list of transaction type specific error codes, refer [error-and-return_codes_information.xlsx](https://static.developer.mastercard.com/content/cross-border-services/uploads/error-and-return_codes_information.xlsx) (37KB) The above attached error code document provides detailed information about the errors supported with both V3 and V4 error codes. This document also provides the scenario(s) in which the errors are expected to occur and relevant actions to be taken to resolve the issues. Note: The document details if an error code is associated with v3 or v4 and or both. If any description changes are observed on a specific error between V3 and V4, the respective error code is displayed twice - each entity with explicit version and associated description. ### Column Descriptions: {#column-descriptions} * **Code Value** - The error code provided in the Error.Value field. * **Reason** - The error reason provided in the Error.ReasonCode field. * **Code Description** - The description provided in the Error.Description field. * **Scenario** - The scenario in which the error is likely to occur. * **Action to Take** - The steps to be followed to resolve the error. * **Relevant API** - The API/APIs that can trigger the error. * **Error Code V3** - Represents the error versioning that supports the error code. * **Error Code V4** - Represents the error versioning that supports the error code. * **V4 Error Update Additional Details** - Provides the reason for the update to version 4 Error. * **Return Message V3** - Indicates if the Code is possible for a Return as part of Version 3 Returns. Tip: It's recommended that the applications be written such that any new error codes introduced will be backward compatible, avoiding negative impact. ## Return Messages {#return-messages} Return messages will be provided via Status Change reporting (File or API based) and via Retrieve Payment APIs when a transaction is returned. The values provide an explanation of the reason the transaction is being returned. ### Return Messages Version 2 {#return-messages-version-2} The following table contains the list of return messages for Version 2. | | Return Message For Refund Return Reason Version 2 | |----|--------------------------------------------------------------| | 1 | Returned per sending service provider's request | | 2 | Beneficiary account is not valid or unable to locate account | | 3 | Beneficiary account is inactive | | 4 | Beneficiary name does not match account | | 5 | Invalid account type | | 6 | Credit refused by beneficiary | | 7 | Unspecified reason | | 8 | Beneficiary account is not authorized to receive deposits | | 9 | Beneficiary account currency does not match payout currency | | 10 | Beneficiary account is frozen​​​​​​ | * [Sample response](https://developer.mastercard.com/cross-border-services/documentation/testing/retrieve-payment-api/index.md) of Retrieve Payment API (Example #5) * [Sample notification](https://developer.mastercard.com/cross-border-services/documentation/testing/status-change-api/index.md) of Status Change Push (Example #3) When a local network does not provide a clear return reason, "Unspecified reason" will be provided in the Return Message. Take a look at the [API Conventions](https://developer.mastercard.com/cross-border-services/documentation/api-basics/index.md#api-conventions) for general guidelines. ### Return Messages Version 3 {#return-messages-version-3} Return Version 3 (V3) allows Mastercard to provide 1 of 53 different Return Messages compared to the 10 Return Messages available in Version 2. For a complete list of Return Version 3 (V3) messages, please refer to the [Error And Return Message Codes Information](https://static.developer.mastercard.com/content/cross-border-services/uploads/error-and-return_codes_information.xlsx) export filtered with a checkmark on column "J" When a local network does not provide a clear return reason, Code "150006 "and description "System Error" will be provided. * [Sample response](https://developer.mastercard.com/cross-border-services/documentation/testing/retrieve-payment-api/index.md) of Retrieve Payment API (Example #6) * [Sample notification](https://developer.mastercard.com/cross-border-services/documentation/testing/status-change-api/index.md) of Status Change Push (Example #4) #### Member Test Facility (MTF) Testing for Return Message Version 3 {#member-test-facility-mtf-testing-for-return-message-version-3} For a complete list of the Return Version 3 (V3) MTF test cases, please refer to tab 2, "Return V3 Test Scenarios" on the [Error And Return Message Codes Information](https://static.developer.mastercard.com/content/cross-border-services/uploads/error-and-return_codes_information.xlsx) export. Columns "D" through "H" list the Recipient URI and the additional data field, that must be provided to test Returns for the following receive channels: IBAN, BAN, Card, Tel, and E-Wallet. Please refer to the below table on how to format the Return V3 test cases for each channel: | Test Case | Action/Response | |---------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | "P2P" Payment with "iban" recipient uri is returned with specific error code | 1. Send a Payment where recipient currency is USD and Recipient account uri as iban:BR9700360305000010009795493P1. Also, provide additional data field name '999' and value in format '226NNNNNN', where NNNNNN is desired error code. For example: "additional_data": \[ { "name": "999", "value": "226130105" }, will return the payment with return message 130105 2. System would mark the payment successful initially and after 26 hrs return the payment with code 130105 | | "P2P" Payment with "ban" recipient uri is returned with specific error code | 1. Send a Payment where recipient currency is USD and Recipient account uri in format ban:1000000226NNNNNN;bic=SIMXXX, where NNNNNN is desired error code. For example: Recipient uri ban:1000000226130105;bic=SIMXXX, will return the payment with return message 130105 2. System would mark the payment successful initially and after 26 hrs return the payment with code 130105 | | "P2P" Payment with "ewallet" recipient uri is returned with specific error code | 1. Send a Payment where recipient currency is USD and Recipient account uri in format ewallet: EW226NNNNNN;sp=sim, where NNNNNN is desired error code. For example: Recipient uri ewallet: EW226130105;sp=sim , will return the payment with return message 130105 2. System would mark the payment successful initially and after 26 hrs return the payment with code 130105 | | "P2P" Payment with "tel" recipient uri is returned with specific error code | 1. Send a Payment where recipient currency is USD and Recipient account uri in format tel:+999226NNNNNN, where NNNNNN is desired error code. For example: Recipient uri tel:+999226130105 , will return the payment with return message 130105 2. System would mark the payment successful initially and after 26 hrs return the payment with code 130105 | | "P2P" Payment with "pan" recipient uri is returned with specific error code | 1. Send a Payment where recipient currency is USD and Recipient account uri as pan:5186002600000013. Also, provide additional data field name '999' and value in format '226NNNNNN', where NNNNNN is desired error code. For example: "additional_data": \[ { "name": "999", "value": "226130105" }, will return the payment with return message 130105 2. System would mark the payment successful initially and after 26 hrs return the payment with code 130105 |
Note: The above test case outcomes can also be tested in the Sandbox environment. Please refer to [Retrieve Payment For Return Reason Message Version 3](https://developer.mastercard.com/cross-border-services/documentation/api-ref/transaction-apis/retrieve-payment-api/index.md#sandbox-test-cases) to see Sandbox test case formatting. **Sample "P2P" payment requests:** **Recipient URI 'iban':** ```JSON { "paymentrequest": { "transaction_reference": "09-PYT-WCR-HDFsWERTYLKR-883166274207686", "sender_account_uri": "tel:+254108989", "recipient_account_uri": "iban:BR9700360305000010009795493P1", "payment_amount": { "amount": "11.50", "currency": "USD" }, "payment_origination_country": "USA", "bank_code": "NP021", "payment_type": "P2P", "sender": { "first_name": "John", "middle_name": "L", "last_name": "Doe", "nationality": "USA", "address": { "line1": "123MainStreet", "line2": "#5A", "city": "Arlington", "country_subdivision": "NA", "postal_code": "12345", "country": "USA" }, "date_of_birth": "1980-01-20" }, "recipient": { "first_name": "John", "middle_name": "L", "last_name": "Doe", "nationality": "USA", "address": { "line1": "123MainStreet", "line2": "#5A", "city": "Arlington", "country_subdivision": "NA", "postal_code": "12345", "country": "CAN" } }, "fx_type": { "forward": { "fees_included": "true", "receiver_currency": "USD" } }, "additional_data": { "data_field": [ { "name": "701", "value": "USA" }, { "name": "999", "value": "226130105" } ] } } } ``` **Recipient URI 'ban':** ```JSON { "paymentrequest": { "transaction_reference": "09-PYT-WCR-HDFsWERTYLKR-883166274207696", "sender_account_uri": "tel:+254108989", "recipient_account_uri": "ban:1000000226130105;bic=SIMXXX", "payment_amount": { "amount": "12.50", "currency": "USD" }, "payment_origination_country": "USA", "bank_code": "NP021", "payment_type": "P2P", "sender": { "first_name": "John", "middle_name": "L", "last_name": "Doe", "nationality": "USA", "address": { "line1": "123MainStreet", "line2": "#5A", "city": "Arlington", "country_subdivision": "NA", "postal_code": "12345", "country": "USA" }, "date_of_birth": "1980-01-20" }, "recipient": { "first_name": "John", "middle_name": "L", "last_name": "Doe", "nationality": "USA", "address": { "line1": "123MainStreet", "line2": "#5A", "city": "Arlington", "country_subdivision": "NA", "postal_code": "12345", "country": "CAN" } }, "fx_type": { "forward": { "fees_included": "true", "receiver_currency": "USD" } }, "additional_data": { "data_field": [ { "name": "701", "value": "USA" } ] } } } ``` **Recipient URI 'ewallet':** ```JSON { "paymentrequest": { "transaction_reference": "09-PYT-WCR-HDFsWERTYLKR-883166274207606", "sender_account_uri": "tel:+254108989", "recipient_account_uri": "ewallet:EW226130113;sp=sim", "payment_amount": { "amount": "13.50", "currency": "USD" }, "payment_origination_country": "USA", "bank_code": "NP021", "payment_type": "P2P", "sender": { "first_name": "John", "middle_name": "L", "last_name": "Doe", "nationality": "USA", "address": { "line1": "123MainStreet", "line2": "#5A", "city": "Arlington", "country_subdivision": "NA", "postal_code": "12345", "country": "USA" }, "date_of_birth": "1980-01-20" }, "recipient": { "first_name": "John", "middle_name": "L", "last_name": "Doe", "nationality": "USA", "address": { "line1": "123MainStreet", "line2": "#5A", "city": "Arlington", "country_subdivision": "NA", "postal_code": "12345", "country": "CAN" } }, "fx_type": { "forward": { "fees_included": "true", "receiver_currency": "USD" } }, "additional_data": { "data_field": [ { "name": "701", "value": "USA" }, { "name": "1200", "value": "test" } ] } } } ``` **Recipient URI 'tel':** ```JSON { "paymentrequest": { "transaction_reference": "09-PYT-WCR-HDFsWERTYLKR-883166274207676", "sender_account_uri": "tel:+254108989", "recipient_account_uri": "tel:+999226130105", "payment_amount": { "amount": "13.50", "currency": "USD" }, "payment_origination_country": "USA", "bank_code": "NP021", "payment_type": "P2P", "sender": { "first_name": "John", "middle_name": "L", "last_name": "Doe", "nationality": "USA", "address": { "line1": "123MainStreet", "line2": "#5A", "city": "Arlington", "country_subdivision": "NA", "postal_code": "12345", "country": "USA" }, "date_of_birth": "1980-01-20" }, "recipient": { "first_name": "John", "middle_name": "L", "last_name": "Doe", "nationality": "USA", "address": { "line1": "123MainStreet", "line2": "#5A", "city": "Arlington", "country_subdivision": "NA", "postal_code": "12345", "country": "CAN" } }, "fx_type": { "forward": { "fees_included": "true", "receiver_currency": "USD" } }, "additional_data": { "data_field": [ { "name": "701", "value": "USA" }, { "name": "1200", "value": "test" } ] } } } ``` **Recipient URI 'pan':** ```JSON { "paymentrequest": { "transaction_reference": "09-PYT-WCR-HDFsWERTYLKR-883166274207686", "sender_account_uri": "tel:+254108989", "recipient_account_uri": "pan:5186002600000013", "payment_amount": { "amount": "11.50", "currency": "USD" }, "payment_origination_country": "USA", "bank_code": "NP021", "payment_type": "P2P", "sender": { "first_name": "John", "middle_name": "L", "last_name": "Doe", "nationality": "USA", "address": { "line1": "123MainStreet", "line2": "#5A", "city": "Arlington", "country_subdivision": "NA", "postal_code": "12345", "country": "USA" }, "date_of_birth": "1980-01-20" }, "recipient": { "first_name": "John", "middle_name": "L", "last_name": "Doe", "nationality": "USA", "address": { "line1": "123MainStreet", "line2": "#5A", "city": "Arlington", "country_subdivision": "NA", "postal_code": "12345", "country": "CAN" } }, "fx_type": { "forward": { "fees_included": "true", "receiver_currency": "USD" } }, "additional_data":{ "data_field": [ { "name": "701", "value": "USA" }, { "name": "999", "value": "226130105" } ] } } } ``` Take a look at the [API Conventions](https://developer.mastercard.com/cross-border-services/documentation/api-basics/index.md#api-conventions) for general guidelines. ## Timeouts {#timeouts} As a consumer of our API(s), we recommend that you set your time out to be at least "40" seconds. The following are suggested actions for timeouts: ### Quote API Recommendations {#quote-api-recommendations} Re-submit the Quote request with same Transaction Reference. The following table lists the possible responses and the action required: | Response | Action | |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | A successful Quote | No further action required | | Responses indicating a connectivity issue, such as: * Another timeout (no response received within 40 seconds) * A gateway HTTP 500 error with a source value of "Gateway" or "Service" * A "System Error" (150001) | Retry the same transaction (including the same transaction reference number) with a back-off algorithm or retry every 10 minutes up to 30 minutes until a response is received. If no response after 30 minutes, please reach out to the [API Support team](https://developer.mastercard.com/support). | The following diagram reflects the sequence. ![http-500-quote-api-sequence-diagram](https://static.developer.mastercard.com/content/cross-border-services/uploads/Bpractices_scenarioone_updated.PNG) ### Payment API Recommendations {#payment-api-recommendations} Call the Retrieve Payment API to verify the status of the Payment. The following table lists the possible responses and the action required: | Response | Action | |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | A "Record Not Found" (110507) error. **Note:** In very rare instances, "Record not found" (110507) may be returned via the Retrieve call even if the transaction has reached the Cross-Border application. In such scenarios, a "duplicate"(082000) error will be returned via the Payment call if the transaction is resubmitted. | You may resubmit the same payment transaction (including the same transaction reference number). | | A successful response | No further action required. The payment was processed, and the Retrieve API replies with the current status. | | Responses indicating a connectivity issue, such as: * Another timeout (no response received within 40 seconds) * A gateway HTTP 500 error with a source value of "Gateway" or "Service" * A "System Error" (150001) | Retry the same transaction (including the same transaction reference number) with a back-off algorithm or retry every 10 minutes up to 30 minutes until a response is received. If no response after 30 minutes, please reach out to the [API Support team](https://developer.mastercard.com/support). | The following diagram reflects the sequence. ![http-500-payment-api-sequence-diagram](https://static.developer.mastercard.com/content/cross-border-services/uploads/Bpractices_scenariotwo.PNG) ### Quote Confirmation API Recommendations {#quote-confirmation-api-recommendations} Re-submit the Quote Confirmation request with same Transaction Reference. The following table lists the possible responses and the action required: | Response | Action | |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | A successful Quote Confirmation | No further action required | | Responses indicating a connectivity issue, such as: * Another timeout (no response received within 40 seconds) * A gateway HTTP 500 error with a source value of "Gateway" or "Service") * A "System Error" | Retry the same transaction (including the same transaction reference number) with a back-off algorithm or retry every 2 minutes up to 6 minutes until a response is received. If no response after 6 minutes, please reach out to the [API Support team](https://developer.mastercard.com/support). | The following diagram reflects the sequence. ![http-500-quote-confirmation-api-sequence-diagram](https://static.developer.mastercard.com/content/cross-border-services/uploads/Quote_confirmation.png) ### Cancel Confirmed Quote API Recommendations {#cancel-confirmed-quote-api-recommendations} Re-submit the Quote confirmation request with same Transaction Reference. The following table lists the possible responses and the action required: | Response | Action | |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | A successful Quote Cancellation | No further action required | | Responses indicating a connectivity issue, such as: * Another timeout (no response received within 40 seconds) * A gateway HTTP 500 error with a source value of "Gateway" or "Service") * A "System Error" | Retry the same transaction (including the same transaction reference number) with a back-off algorithm or retry every 2 minutes up to 6 minutes until a response is received. If no response after 6 minutes, please reach out to the [API Support team](https://developer.mastercard.com/support). | The following diagram reflects the sequence. ![http-500-cancel-confirmed-quote-api-sequence-diagram](https://static.developer.mastercard.com/content/cross-border-services/uploads/Quote_cancellation.png) ## Resources {#resources} ### Error scenarios {#error-scenarios} Use our pre-written error messages to communicate clearly to your users. [XBS_Error_Codes.xlsx](https://static.developer.mastercard.com/content/cross-border-services/uploads/XBS_Error_Codes.xlsx) (36KB)