# Codes and Formats source: https://developer.mastercard.com/payment-currency-conversion/documentation/codes-and-formats/index.md ## ISO Currency Codes {#iso-currency-codes} Currencies are identified using the 3-character [ISO 4217 alpha-3 currency codes](https://www.iso.org/iso-4217-currency-codes.html) defined by ISO. For example, US Dollars is `USD`. This applies to: * Transaction Currency = `transaction_currency` * OI Settlement Currency = `oi_settlement_currency` For a list of codes, refer to the [Quick Reference Booklet](https://trc-techresource.mastercard.com/r/bundle/m_qrb_en-us/page/d/en-US), which is available in the [Technical Resource Center](https://trc-techresource.mastercard.com/) on Mastercard Connect. ## Date Formats {#date-formats} Date values are 10 characters, specified in the format YYYY-MM-DD. For example, March 27th 2024 is `2024-03-27`. This applies to: * Rate Date = `rate_date` * Transaction Date = `transaction_date` The date is in GMT. For `transaction_date`, you can provide '0000-00-00' to indicate the current date. ## HTTP Response Codes {#http-response-codes} The following table shows the common codes that may be returned for API requests. In the event of network or infrastructure issues, other codes may be returned by the infrastructure. The next section provides more information about 4xx and 5xx error responses. | HTTP Response Code | Description | |-----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 200 (OK) | The request was completed successfully. | | 400 (BAD REQUEST) | The request could not be fulfilled due to general errors such as validation errors or missing required data. | | 401 (UNAUTHORIZED) | Missing or invalid authentication token. | | 403 (FORBIDDEN) | You are not authorized to perform the operation, or the resource is unavailable for some reason. | | 404 (NOT FOUND) | The request was unsuccessful, possibly due to an invalid date value. | | 500 (INTERNAL SERVER ERROR) | The server encountered an unexpected condition which prevented it from fulfilling the request. It indicates an error that the caller cannot address from their end. Requests resulting in a 500 response code will generally include the Mastercard API error structure in the response. | | 5xx (SERVER ERROR) | Typically indicates an error in the network infrastructure between the client and Mastercard API server. Such errors will never contain the Mastercard API error structure in the response. | ## Error Codes (Reason Codes) {#error-codes-reason-codes} If your API request is unsuccessful, you should receive a service error response or a gateway error response, which have the following structure (example values shown). The `Error` array may contain multiple error items. * JSON ```JSON { "Errors": { "Error": [ { "Source": "Payment Transaction API", "ReasonCode": "BAD_REQUEST", "Description": "Invalid rate_date.", "Recoverable": false, "Details": "Required parameter 'rate_date' is not valid. Valid format is YYYY-MM-DD." } ] } } ``` The `Recoverable` value (true or false) indicates whether your API request might be successful if you re-send the API request with the **same** parameters and data. For example, an unsuccessful API request caused by a server error might be successful when re-sent. ### Service error codes {#service-error-codes} Service error response messages (4xx status code) have `Source` as "Payment Transaction API". The following table shows the `ReasonCode`, `Description`, and `Details` values that can be returned. Other values might also exist or be introduced periodically. Do not code to the `Details` values because they may change. | Reason Code | Description | Details | How to Resolve | |--------------------|------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **HTTP Code 400:** | | | | | BAD_REQUEST | Invalid rate_date. | Required parameter 'rate_date' is not valid. Valid format is YYYY-MM-DD. | Change `rate_date` to current date in format YYYY-MM-DD. | | BAD_REQUEST | Invalid transaction_date. | Required parameter 'transaction_date' is not valid. Valid format is YYYY-MM-DD. | Change `transaction_date` value to current date in format YYYY-MM-DD. | | BAD_REQUEST | Invalid transaction_date. | Required request parameter 'transaction_date' for method parameter type String is not present | Provide `transaction_date` with current date in format YYYY-MM-DD. | | BAD_REQUEST | Missing transaction_date. | Required parameter 'transaction_date' is not provided. | **Conversion Rates Status** API call: `rate_date` provided but has no value. Remove parameter or change value to current date in format YYYY-MM-DD. **Conversion Rate Details** API call: `transaction_date` has no value. Provide current date in format YYYY-MM-DD. | | BAD_REQUEST | Invalid transaction_currency. | Transaction Currency is invalid (Expected value is an ISO currency alpha code) | Change `transaction_currency` value to a valid value. | | BAD_REQUEST | Invalid transaction_currency. | Required request parameter 'transaction_currency' for method parameter type String is not present | Provide `transaction_currency` with a valid value. | | BAD_REQUEST | Invalid transaction_amount. | Invalid Transaction Amount, Only 2 precision allowed in right side | Change `transaction_amount` value to have no more than two precision digits to the right of the decimal point. If the transaction currency has a 3-digit exponent, see [3-Place Exponent Currencies](https://developer.mastercard.com/payment-currency-conversion/documentation/use-cases/conv-details/index.md#3-place-exponent-currencies). | | BAD_REQUEST | Invalid transaction_amount. | Transaction Amount must be greater than zero and should be less than 999999999.99 | `transaction_amount` value too large. Change to a value in the range 0.01 - 999999999.99 inclusive. Only two precision digits allowed to the right of the decimal point. | | BAD_REQUEST | Invalid transaction_amount. | Invalid Transaction Amount, It must be greater than zero | `transaction_amount` value is 0 (zero). Change to a value in the range 0.01 - 999999999.99 inclusive. Only two precision digits allowed to the right of the decimal point. | | BAD_REQUEST | Invalid transaction_amount. | Required parameter 'transaction_amount' is not valid. Please provide a numeric value. | Change `transaction_amount` value to a valid numeric value. | | BAD_REQUEST | Invalid transaction_amount. | Required request parameter 'transaction_amount' for method parameter type BigDecimal is present but converted to null | Change `transaction_amount` value to a valid numeric value. | | BAD_REQUEST | Invalid transaction_amount. | Required request parameter 'transaction_amount' for method parameter type BigDecimal is not present | Provide `transaction_amount` with a valid numeric value. | | BAD_REQUEST | Invalid oi_settlement_currency. | Originator Settlement Currency is invalid (Expected value is an ISO currency alpha code) | Change `oi_settlement_currency` value to a valid value. | | BAD_REQUEST | Invalid oi_settlement_currency. | Required request parameter 'oi_settlement_currency' for method parameter type String is not present | Provide `oi_settlement_currency` with a valid value. | | BAD_REQUEST | Unrecognized Clearing System value | Unrecognized parameter 'clearing_system' with value 'Singl'. Allowed values include SINGLE and DUAL. Please contact support team at https://developer.mastercard.com/support for additional assistance. | Change `clearing_system` value to SINGLE or DUAL. | | **HTTP Code 401:** | | | | | UNAUTHORIZED | Invalid client id. | You do not have access to this service. Please visit the Payment Transaction Currency Conversion Calculator page for details. | For production API calls, this error can occur when a Mastercard Developers production access request has been approved, as reflected in your project page 'Summary' panel, but the Mastercard SAM Application Support team has not completed production setup. Ensure you have notified your Mastercard Implementation Manager or Mastercard representative about your production request and allow 5-7 business days for setup. Mastercard will notify you when you can start making API calls to that environment. | | **HTTP Code 403:** | | | | | FORBIDDEN | Data is not accessible | You do not have access to this data under your current subscription service. Please use current date. | Depending on API, `rate_date` or `transaction_date` value is an invalid past date. Change value to current date. | | FORBIDDEN | Data is not accessible | You do not have access to this data under your current subscription service. Please use a date within the last 365 days, inclusive of current day. | Depending on API, `rate_date` or `transaction_date` value is an invalid past date. Change value to valid date. | | **HTTP Code 404:** | | | | | NOT_FOUND | Data not available | No active Currencies found | Retry with a backoff algorithm. If the issue persists, contact [API support](https://developer.mastercard.com/support). | | NOT_FOUND | Data not available | Rate issuance for future date not supported. Resubmit for a date within the last 365 days inclusive of current day. | You attempted to retrieve a future date. Change `rate_date` value to current date. | | NOT_FOUND | Data not available | Mastercard rates are not available for this date. Resubmit for a date within the last 365 days inclusive of current day | You attempted to retrieve a future date. Change `transaction_date` value to current date. | ### Gateway error codes {#gateway-error-codes} Gateway error response messages (4xx/5xx status code) can also be returned by Mastercard's gateway, which is used to verify your request's signature and route the request to the correct location. These errors typically have `Source` as "Gateway". The following table shows the `ReasonCode` and `Description` values for some common gateway errors when attempting calls to this API. For a larger list of the errors returned by our gateway, as well as resolutions to each, see [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/errors-troubleshooting/gateway-error-codes/). | HTTP Code | Reason Code | Description | How to Resolve | |-----------|----------------------------|--------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 400 | INVALID_OAUTH_CONSUMER_KEY | Consumer key must be 97 characters long, split by an exclamation mark symbol. Received: 98 | Missing consumer key or incorrect length. Copy the appropriate consumer key from your Mastercard Developers project page. | | 401 | DECLINED | Unauthorized - Access Not Granted | Possible reasons: * Incorrect consumer key, or client ID part, for the API environment. * Incorrect key or key credentials for the API environment, such as trying to use the sandbox key for the production environment. * Sandbox environment: The sandbox instance is still being provisioned\*. This activity can sometimes take a short while when the API is added to an existing Mastercard Developers project. * Production environment: The production access request has not yet been approved\*. \*This status is indicated by "Under Review" for 'Sandbox status' or 'Production status' in your Mastercard Developers project page 'Summary' panel. Check your Mastercard Developers [account profile](https://developer.mastercard.com/account/profile) shows that it is verified. If it isn't, follow the guidance to have it verified. In your project page 'Summary' panel, ensure the status indicator is "Ready" for the relevant environment. If it is, check your consumer key, key file, and credentials are correct for the environment. | | 403 | AUTHENTICATION_FAILED | OAuth Signature parameter failed verification. Acceptable signature base string: GET... | Possible reasons: * Consumer key does not match the key file * A request parameter value includes ! (exclamation mark) or other invalid characters If previous API calls to the API environment worked, check the request parameter values. Otherwise, check your consumer key, key file, and credentials are correct for the environment. | | 404 | NOT_FOUND | Not Found | Incorrect endpoint path. Check the path is correct for the API environment. |