Tuna Codes#
Summary of assets to download:
- list of payment status: paymentStatus.json
- list of payment methods: paymentMethods.json
- list with all payment method status: paymentMethodStatus.json
- list with all Tuna error codes: srvTunaCodes.json
- list of banks: banks.json
- list of merchant category codes: mccCodes.json
- list of occupations: occupations.json
- list of card on file: cardOnFile.json
- list of delivery types: deliveryTypes.json
Payment Status#
You should track the payment status to make decisions regarding the approval of your overall order.
The payment status can be considered a subset of payment method status. Therefore, check them only when you explicitly need to act on a specific payment method's result. Most times, just tracking the payment status will be enough.
Check out all payment statuses in the file paymentStatus.json. And in the table below, all payment statuses are described:
| Status Code | Status | Description |
|---|---|---|
| 0 | Started | The payment transaction has started, but no transactions have been executed yet. |
| 2 | Captured | The payment transaction has been captured, so the funds are secured. |
| 3 | Refunded | The payment transaction has been refunded. |
| 4 | Denied | The payment transaction has been denied by the issuing bank, acquirer, or anti-fraud provider. |
| 5 | Cancelled | The payment transaction has been canceled after being previously authorized. |
| 6 | Abandoned | The payment transaction has been abandoned. It's been started for too long and never evolved to another status. |
| 7 | Chargeback | The payment transaction has been reported as a chargeback. |
| 8 | MoneyReceived | Funds of the payment transaction have been transferred to the partner. |
| 9 | PartialRefunded | The payment transaction has been partially refunded. |
| P | Pending | The system is waiting for the result of another process, such as anti-fraud analysis, to complete the payment transaction. Whether the transaction has already been authorized or not depends on how your flows are configured. |
Payment Methods#
Payment methods identifiers (ID) and descriptions are listed in the file paymentMethods.json. They are also listed in the table below:
| Payment Method ID | Payment Method | Description |
|---|---|---|
| 1 | CreditCard | Credit Card |
| 2 | DebitCard | Debit Card |
| 3 | Boleto | Brazilian Bank Slip |
| 4 | BankTransfer | Bank Wire Transfer |
| 9 | External | Generic External Payment |
| A | GiftCard | Gift Card Provider |
| B | Balance | Proprietary Credit System Balance |
| C | CreditCardPrivateBrand | Private Label Credit Card |
| D | PIX | Brazilian Central Bank's instant payment |
| E | Crypto | Bitcoin and other crypto currencies |
| F | Voucher | Voucher Card Provider |
| 7 | ThreeDS20Credit | 3DS 2.0 Credit Card |
| 8 | ThreeDS20Debit | 3DS 2.0 Debit Card |
Payment Method Status#
It can be more specific than the status of the entire payment, as shown in the file paymentMethodStatus.json.
All payment method statuses are described in the table below:
| Status Code | Status | Description |
|---|---|---|
| 0 | Started | The payment transaction has started, but no transactions have been executed yet. |
| 1 | Authorized | The payment transaction of this method has been authorized but not yet captured. The credit limit has been reserved on the credit card. |
| 2 | Captured | The payment transaction has been captured, so the funds are secured. |
| 3 | Refunded | The payment transaction has been refunded. |
| 4 | Denied | The payment transaction has been denied by the issuing bank, acquirer, or anti-fraud provider. |
| 5 | Cancelled | The payment transaction has been canceled after being previously authorized. |
| 6 | Abandoned | The payment transaction has been abandoned. It's been started for too long and never evolved to another status. |
| 7 | Chargeback | The payment transaction has been reported as a chargeback. |
| 8 | MoneyReceived | Funds of the payment transaction have been transferred to the partner. |
| 9 | PartialRefunded | The payment transaction has been partially refunded. |
| A | Error | There was an error while processing the transaction of this payment method. This status is followed by a message with more details about the error. |
| B | RedFlag | The system explicitly marked this transaction as a major issue that should be investigated. This is a rare status. You don't need to worry about it while integrating with Tuna. |
| C | PendingCapture | For some reason, the transaction of this payment method could not be captured. The system will automatically retry to capture it later. |
| D | PendingRefund | For some reason, the transaction of this payment method could not be canceled. The system will automatically retry to cancel it later. |
| P | Pending | The system is waiting for the result of another process, such as anti-fraud analysis, to complete the payment transaction. Whether the transaction has already been authorized or not depends on how your flows are configured. |
| N | NotProcessed | This payment method will not be processed. This status is final. |
| G | PendingCancel | For some reason, the transaction of this payment method could not be canceled. The system will automatically retry to cancel it later. |
Message Code List#
Due to Tuna's orchestration nature, everytime we're able to sucessfully process a request, we'll return a 200 OK response, even if the request results in and error. The tables below show what each error code mean, when things don't go as expected.
Our APIs will only return a non 200 status code when Tuna is not able to process the request. For the 400 error(Bad Request), we'll attempt to give tips of what went wrong such as the example below:
Here's what each field means:
type: This is a URL that points to a specific section of the HTTP/1.1 Status Code Definitions. In this case, it points to the section that defines the 400 Bad Request status code.title: This is a brief description of the error. In this case, it indicates that one or more validation errors occurred.status: This is the HTTP status code. In this case, it's 400, which means Bad Request. This status code is often sent when the server could not understand the request due to invalid syntax.traceId: This is a unique identifier for this specific instance of the error. It can be used for logging and debugging purposes.errors: This is an object that contains more detailed information about the errors that occurred. Each key in this object is a field that had a validation error, and the value is an array of error messages for that field.
In this case, there are two errors:
request: The error message indicates that the request field is required. This means that the request field was missing from the request.$.PaymentItems.Items[0].Amount: The error message indicates that the JSON value could not be converted to a decimal number. This means that the value provided for the Amount field in the first item of the PaymentItems array was not a valid decimal number.
In the case of other HTTP status codes, particularly those in the 4xx and 5xx ranges, the details of the response body may not hold significant importance. The primary focus should be on understanding and addressing the error indicated by the status code itself. These codes represent client-side errors (4xx) and server-side errors (5xx), and each code has a specific meaning.
Payment API#
All possible return codes of the message objects are given in the file messageCodeList.json and described in the table below:
| Code | Message (it may vary according to custom settings) | Behavior |
|---|---|---|
| 1 | Operation OK. | ....................................................... |
| -1 | Error please get in touch with Tuna. | Contact support and inform this code and data request. |
| -101 | The request object is null. | Malformed request. Please check the message and fix it. |
| -102 | Payment not found. | Malformed request. Please check the message and fix it. |
| -103 | Invalid items. | Malformed request. Please check the message and fix it. |
| -104 | At least one payment method must be present. | Malformed request. Please check the message and fix it. |
| -105 | Partner ID cannot be null. | Malformed request. Please check the message and fix it. |
| -106 | Partner Unique ID cannot be null. | Malformed request. Please check the message and fix it. |
| -107 | Missing customer external key. | Malformed request. Please check the message and fix it. |
| -108 | Partner Unique ID already used. | The request is repeated. It will not be processed. |
| -109 | Invalid Configuration. Abort message. | Configuration issue. Please check your account and look for callouts. If you can't fix it, contact support and inform this code and data request. |
| -110 | Invalid CVV. | Malformed request. Please check the message and fix it. |
| -111 | Partner Token was not provided. | Malformed request. Please check the message and fix it. |
| -112 | Partner ID does not exist. | Configuration issue. Please check your credentials. |
| -113 | Partner ID does not exist. | Configuration issue. Please check your credentials. |
| -114 | Partner Account does not exist. | Configuration issue. Please check your credentials. |
| -115 | Cancel operation failed. | Contact support and inform this code and data request. |
| -116 | Capture operation failed. | Contact support and inform this code and data request. |
| -117 | Capture operation failed. | Configuration issue. Please check your account and look for callouts. If you can't fix it, contact support and inform this code and data request. |
| -118 | Order Identifier cannot be null. | Malformed request. Please check the message and fix it. |
| -119 | Operation failed. | Contact support and inform this code and data request. |
| -120 | Method amount can not be null or 0. | Malformed request. Please check the message and fix it. |
| -121 | Unexpected error. | Contact support and inform this code and data request. |
| -122 | The merchant does not exist. | Malformed request. Please check the message and fix it. |
| -123 | Merchant Percentage cannot be null. | Malformed request. Please check the message and fix it. |
| -124 | Merchant External Id cannot be null. | Malformed request. Please check the message and fix it. |
| -125 | Merchant Name cannot be null. | Malformed request. Please check the message and fix it. |
| -126 | Merchant Fantasy Name cannot be null. | Malformed request. Please check the message and fix it. |
| -127 | Merchant Status cannot be null. | Malformed request. Please check the message and fix it. |
| -128 | Invalid Merchant status. | Malformed request. Please check the message and fix it. |
| -129 | Bank Account ExternalId cannot be null. | Malformed request. Please check the message and fix it. |
| -130 | Agency of bank account cannot be null. | Malformed request. Please check the message and fix it. |
| -131 | Bank Account number cannot be null. | Malformed request. Please check the message and fix it. |
| -132 | Bank account type is invalid. The valid values are 'C' for Checking 'S' for Saving 'P' for Payment or 'D' for Dep | Malformed request. Please check the message and fix it. |
| -133 | Dates filter is invalid. | Malformed request. Please check the message and fix it. |
| -134 | Invalid Merchant Percentage. | Malformed request. Please check the message and fix it. |
| -135 | Invalid Merchant amount. | Malformed request. Please check the message and fix it. |
| -136 | Invalid Merchant shipping amount. | Malformed request. Please check the message and fix it. |
| -137 | The status of the payment method is not allowed for cancel. | Malformed request. Please check the message and fix it. |
| -138 | The merchant document cannot be null. | Malformed request. Please check the message and fix it. |
| -139 | Invalid Merchant document. | Malformed request. Please check the message and fix it. |
| -140 | Merchant Contact cannot be null. | Malformed request. Please check the message and fix it. |
| -141 | Merchant Contact Name cannot be null. | Malformed request. Please check the message and fix it. |
| -142 | Merchant Contact Cellphone cannot be null. | Malformed request. Please check the message and fix it. |
| -143 | Invalid Merchant Contact Cellphone. | Malformed request. Please check the message and fix it. |
| -144 | Invalid Merchant Contact Phone. | Malformed request. Please check the message and fix it. |
| -145 | Merchant Contact Email cannot be null. | Malformed request. Please check the message and fix it. |
| -146 | Invalid Merchant Contact Email. | Malformed request. Please check the message and fix it. |
| -147 | Merchant Address cannot be null. | Malformed request. Please check the message and fix it. |
| -148 | Merchant Street cannot be null. | Malformed request. Please check the message and fix it. |
| -149 | Merchant Street Number cannot be null. | Malformed request. Please check the message and fix it. |
| -150 | Merchant City cannot be null. | Malformed request. Please check the message and fix it. |
| -151 | Merchant Neighborhood cannot be null. | Malformed request. Please check the message and fix it. |
| -152 | Merchant State cannot be null. | Malformed request. Please check the message and fix it. |
| -153 | Merchant PostalCode cannot be null. | Malformed request. Please check the message and fix it. |
| -154 | Invalid Address State. | Malformed request. Please check the message and fix it. |
| -155 | Invalid Merchant Address Number. | Malformed request. Please check the message and fix it. |
| -156 | Invalid Merchant Postal Code. | Malformed request. Please check the message and fix it. |
| -157 | Bank Account Code cannot be null. | Malformed request. Please check the message and fix it. |
| -158 | Invalid Bank Account Code. | Malformed request. Please check the message and fix it. |
| -159 | Invalid Bank Account Agency. The agency number can contain up to 6 digits. | Malformed request. Please check the message and fix it. |
| -160 | Bank Account document cannot be null. | Malformed request. Please check the message and fix it. |
| -161 | Invalid Bank Account Document. | Malformed request. Please check the message and fix it. |
| -162 | Merchant Document doest not correspond to Document Type. | Malformed request. Please check the message and fix it. |
| -163 | Bank Account Document does not correspond to Document Type. | Malformed request. Please check the message and fix it. |
| -164 | Merchant Document type cannot be null. | Malformed request. Please check the message and fix it. |
| -165 | Merchant Document already exists. | Malformed request. Please check the message and fix it. |
| -166 | Birthday cannot be null. | Malformed request. Please check the message and fix it. |
| -167 | Invalid Payment Condition. | Malformed request. Please check the message and fix it. |
| -168 | Invalid Legal Representative Document. | Malformed request. Please check the message and fix it. |
| -169 | Occupation cannot be null. | Malformed request. Please check the message and fix it. |
| -170 | Invalid Occupation max 50 characters allowed. | Malformed request. Please check the message and fix it. |
| -171 | Invalid PixKeyType. | Malformed request. Please check the message and fix it. |
| -172 | Invalid PixKey. | Malformed request. Please check the message and fix it. |
| -173 | PixKeyType must be specified. | Malformed request. Please check the message and fix it. |
| -174 | PixKey must be specified. | Malformed request. Please check the message and fix it. |
| -175 | Service notfound. | Malformed request. Please check the message and fix it. |
| -176 | Merchant can be disabled only when it is Active. | Malformed request. Please check the message and fix it. |
| -177 | Missing card information. | Malformed request. Please check the message and fix it. |
| -178 | PixKey must belong to an account registered with the same registration document. | Malformed request. Please check the message and fix it. |
| -179 | BankAccount document must be the same Document as your account. | Malformed request. Please check the message and fix it. |
| -180 | Item amount can not be null or 0. | Malformed request. Please check the message and fix it. |
| -181 | Installments can not be null or 0. | Malformed request. Please check the message and fix it. |
| -182 | Flow not found. | Malformed request. Please check the message and fix it. |
| -183 | Invalid or not found PixKey | Malformed request. Please check the message and fix it. |
| -184 | Invalid politically exposed person. | Malformed request. Please check the message and fix it. |
| -185 | Spanshots not found. | Malformed request. Please check the message and fix it. |
| -186 | Birthday cannot be less then 18 years ago. | Malformed request. Please check the message and fix it. |
| -187 | Invalid Mother name. | Malformed request. Please check the message and fix it. |
| -188 | Must supply phone or cellphone number. | Malformed request. Please check the message and fix it. |
| -189 | Duplicated Legal Document | Malformed request. Please check the message and fix it. |
| -190 | Inactive merchant. | Malformed request. Please check the message and fix it. |
| -191 | Missing plan for payment type. | Malformed request. Please check the message and fix it. |
| -192 | The merchant is invalid. | Malformed request. Please check the message and fix it. |
| -193 | The merchant contract does not exist. | Malformed request. Please check the message and fix it. |
| -194 | Force capture not allowed. | Malformed request. Please check the message and fix it. |
| -195 | Payment has more than one methods. The operation is not allowed. | Malformed request. Please check the message and fix it. |
| -196 | Partner disabled. | Contact support and inform this code and data request. |
Token API#
Token API response codes are either 1 or -1, 1 meaning the request was successful and -1 meaning an error has occurred. When the response code is -1, the message needs to be checked to determine which error occurred.
| Code | Message (it may vary according to custom settings) | Behavior |
|---|---|---|
| 1 | Operation OK. | ....................................................... |
| -1 | Request object is null | Contact support and inform this code and data request. |
| -1 | Session object is invalid | Contact support and inform this code and data request. |
| -1 | Session has expired | Contact support and inform this code and data request. |
| -1 | Card data missing | Contact support and inform this code and data request. |
| -1 | Card already tokenized | Contact support and inform this code and data request. |
| -1 | Expiration date is invalid | Contact support and inform this code and data request. |
| -1 | Card number is invalid | Contact support and inform this code and data request. |
| -1 | Invalid Token | Contact support and inform this code and data request. |
| -1 | Token can not be removed | Contact support and inform this code and data request. |
| -1 | Card can not be removed | Contact support and inform this code and data request. |
| -1 | AppToken is required | Contact support and inform this code and data request. |
| -1 | Partner Not Exists | Contact support and inform this code and data request. |
| -1 | AppToken is invalid | Contact support and inform this code and data request. |
| -1 | Customer data missing | Contact support and inform this code and data request. |
| -1 | Token data missing | Contact support and inform this code and data request. |
| -1 | Card token is invalid | Contact support and inform this code and data request. |
| -1 | Card holder name is invalid | Contact support and inform this code and data request. |
| -1 | User has reached maximum number of cards allowed | Contact support and inform this code and data request. |
| -1 | User has reached maximum number of sessions allowed | Contact support and inform this code and data request. |
| -1 | Invalid UserData | Contact support and inform this code and data request. |
| -1 | Card.Data size exceeded. Must be up to 4 kbytes | Contact support and inform this code and data request. |
| -1 | Empty configuration | Contact support and inform this code and data request. |
| -1 | An exception has occurred while processing the request. | Contact support and inform this code and data request. |
Card On File#
Since October 2022, due to regulatory changes in brands, card-on-file transactions under the Mastercard brand will be categorized into 12 types of categories CIT (Initiated by the cardholder – Card Holder) and MIT (Initiated by the establishment – Merchant ). Since June 1, 2023, the brand has started to monitor field shipments, stay tuned as compliance actions may occur.
This field become mandatory for card that has network tokens.
Check out all card on files values in the file paymentStatus.json. And in the table below, all possible values are described:
| Main categories | Indicator to be send (credentialId) | Corresponding Sub-Category |
|---|---|---|
| card holder initiated (CIT) | 01 | Card on File (Credencial armazenada) |
| card holder initiated (CIT) | 02 | Ordem Permanente |
| card holder initiated (CIT) | 03 | Assinatura |
| card holder initiated (CIT) | 04 | Parcelado |
| merhant initiated (MIT) recurring or installment payments | 05 | Card on File (Credencial armazenada) – não programada |
| merhant initiated (MIT) recurring or installment payments | 06 | Ordem Permanente |
| merhant initiated (MIT) recurring or installment payments | 07 | Assinatura |
| merhant initiated (MIT) recurring or installment payments | 08 | Parcelado |
| merhant initiated (MIT) business practices | 09 | Remessa Parcial |
| merhant initiated (MIT) business practices | 10 | Cobrança atrasada |
| merhant initiated (MIT) business practices | 11 | No show (Multa) |
| merhant initiated (MIT) business practices | 12 | Reenvio |
Delivery Types#
Items delivery types and descriptions are listed in the file deliveryTypes.json. They are also listed in the table below:
| DeliveryType Id | Delivery Type |
|---|---|
| 1 | PickUp |
| 2 | Delivery |
| 3 | UltraFast |
| 4 | ClickCollect |