Skip to main content

Tuna Codes#

Summary of assets to download:

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 CodeStatusDescription
0StartedThe payment transaction has started, but no transactions have been executed yet.
2CapturedThe payment transaction has been captured, so the funds are secured.
3RefundedThe payment transaction has been refunded.
4DeniedThe payment transaction has been denied by the issuing bank, acquirer, or anti-fraud provider.
5CancelledThe payment transaction has been canceled after being previously authorized.
6AbandonedThe payment transaction has been abandoned. It's been started for too long and never evolved to another status.
7ChargebackThe payment transaction has been reported as a chargeback.
8MoneyReceivedFunds of the payment transaction have been transferred to the partner.
9PartialRefundedThe payment transaction has been partially refunded.
PPendingThe 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 IDPayment MethodDescription
1CreditCardCredit Card
2DebitCardDebit Card
3BoletoBrazilian Bank Slip
4BankTransferBank Wire Transfer
9ExternalGeneric External Payment
AGiftCardGift Card Provider
BBalanceProprietary Credit System Balance
CCreditCardPrivateBrandPrivate Label Credit Card
DPIXBrazilian Central Bank's instant payment
ECryptoBitcoin and other crypto currencies
FVoucherVoucher Card Provider
7ThreeDS20Credit3DS 2.0 Credit Card
8ThreeDS20Debit3DS 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 CodeStatusDescription
0StartedThe payment transaction has started, but no transactions have been executed yet.
1AuthorizedThe payment transaction of this method has been authorized but not yet captured. The credit limit has been reserved on the credit card.
2CapturedThe payment transaction has been captured, so the funds are secured.
3RefundedThe payment transaction has been refunded.
4DeniedThe payment transaction has been denied by the issuing bank, acquirer, or anti-fraud provider.
5CancelledThe payment transaction has been canceled after being previously authorized.
6AbandonedThe payment transaction has been abandoned. It's been started for too long and never evolved to another status.
7ChargebackThe payment transaction has been reported as a chargeback.
8MoneyReceivedFunds of the payment transaction have been transferred to the partner.
9PartialRefundedThe payment transaction has been partially refunded.
AErrorThere was an error while processing the transaction of this payment method. This status is followed by a message with more details about the error.
BRedFlagThe 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.
CPendingCaptureFor some reason, the transaction of this payment method could not be captured. The system will automatically retry to capture it later.
DPendingRefundFor some reason, the transaction of this payment method could not be canceled. The system will automatically retry to cancel it later.
PPendingThe 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.
NNotProcessedThis payment method will not be processed. This status is final.
GPendingCancelFor 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:

{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "00-f0a2717fb3fc5d1622bde7ceb5fa52f1-3f0ac2b867514dac-00",
"errors": {
"request": [
"The request field is required."
],
"$.PaymentItems.Items[0].Amount": [
"The JSON value could not be converted to System.Decimal. Path: $.PaymentItems.Items[0].Amount | LineNumber: 30 | BytePositionInLine: 23."
]
}
}

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:

CodeMessage (it may vary according to custom settings)Behavior
1Operation OK........................................................
-1Error please get in touch with Tuna.Contact support and inform this code and data request.
-101The request object is null.Malformed request. Please check the message and fix it.
-102Payment not found.Malformed request. Please check the message and fix it.
-103Invalid items.Malformed request. Please check the message and fix it.
-104At least one payment method must be present.Malformed request. Please check the message and fix it.
-105Partner ID cannot be null.Malformed request. Please check the message and fix it.
-106Partner Unique ID cannot be null.Malformed request. Please check the message and fix it.
-107Missing customer external key.Malformed request. Please check the message and fix it.
-108Partner Unique ID already used.The request is repeated. It will not be processed.
-109Invalid 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.
-110Invalid CVV.Malformed request. Please check the message and fix it.
-111Partner Token was not provided.Malformed request. Please check the message and fix it.
-112Partner ID does not exist.Configuration issue. Please check your credentials.
-113Partner ID does not exist.Configuration issue. Please check your credentials.
-114Partner Account does not exist.Configuration issue. Please check your credentials.
-115Cancel operation failed.Contact support and inform this code and data request.
-116Capture operation failed.Contact support and inform this code and data request.
-117Capture 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.
-118Order Identifier cannot be null.Malformed request. Please check the message and fix it.
-119Operation failed.Contact support and inform this code and data request.
-120Method amount can not be null or 0.Malformed request. Please check the message and fix it.
-121Unexpected error.Contact support and inform this code and data request.
-122The merchant does not exist.Malformed request. Please check the message and fix it.
-123Merchant Percentage cannot be null.Malformed request. Please check the message and fix it.
-124Merchant External Id cannot be null.Malformed request. Please check the message and fix it.
-125Merchant Name cannot be null.Malformed request. Please check the message and fix it.
-126Merchant Fantasy Name cannot be null.Malformed request. Please check the message and fix it.
-127Merchant Status cannot be null.Malformed request. Please check the message and fix it.
-128Invalid Merchant status.Malformed request. Please check the message and fix it.
-129Bank Account ExternalId cannot be null.Malformed request. Please check the message and fix it.
-130Agency of bank account cannot be null.Malformed request. Please check the message and fix it.
-131Bank Account number cannot be null.Malformed request. Please check the message and fix it.
-132Bank account type is invalid. The valid values are 'C' for Checking 'S' for Saving 'P' for Payment or 'D' for DepMalformed request. Please check the message and fix it.
-133Dates filter is invalid.Malformed request. Please check the message and fix it.
-134Invalid Merchant Percentage.Malformed request. Please check the message and fix it.
-135Invalid Merchant amount.Malformed request. Please check the message and fix it.
-136Invalid Merchant shipping amount.Malformed request. Please check the message and fix it.
-137The status of the payment method is not allowed for cancel.Malformed request. Please check the message and fix it.
-138The merchant document cannot be null.Malformed request. Please check the message and fix it.
-139Invalid Merchant document.Malformed request. Please check the message and fix it.
-140Merchant Contact cannot be null.Malformed request. Please check the message and fix it.
-141Merchant Contact Name cannot be null.Malformed request. Please check the message and fix it.
-142Merchant Contact Cellphone cannot be null.Malformed request. Please check the message and fix it.
-143Invalid Merchant Contact Cellphone.Malformed request. Please check the message and fix it.
-144Invalid Merchant Contact Phone.Malformed request. Please check the message and fix it.
-145Merchant Contact Email cannot be null.Malformed request. Please check the message and fix it.
-146Invalid Merchant Contact Email.Malformed request. Please check the message and fix it.
-147Merchant Address cannot be null.Malformed request. Please check the message and fix it.
-148Merchant Street cannot be null.Malformed request. Please check the message and fix it.
-149Merchant Street Number cannot be null.Malformed request. Please check the message and fix it.
-150Merchant City cannot be null.Malformed request. Please check the message and fix it.
-151Merchant Neighborhood cannot be null.Malformed request. Please check the message and fix it.
-152Merchant State cannot be null.Malformed request. Please check the message and fix it.
-153Merchant PostalCode cannot be null.Malformed request. Please check the message and fix it.
-154Invalid Address State.Malformed request. Please check the message and fix it.
-155Invalid Merchant Address Number.Malformed request. Please check the message and fix it.
-156Invalid Merchant Postal Code.Malformed request. Please check the message and fix it.
-157Bank Account Code cannot be null.Malformed request. Please check the message and fix it.
-158Invalid Bank Account Code.Malformed request. Please check the message and fix it.
-159Invalid Bank Account Agency. The agency number can contain up to 6 digits.Malformed request. Please check the message and fix it.
-160Bank Account document cannot be null.Malformed request. Please check the message and fix it.
-161Invalid Bank Account Document.Malformed request. Please check the message and fix it.
-162Merchant Document doest not correspond to Document Type.Malformed request. Please check the message and fix it.
-163Bank Account Document does not correspond to Document Type.Malformed request. Please check the message and fix it.
-164Merchant Document type cannot be null.Malformed request. Please check the message and fix it.
-165Merchant Document already exists.Malformed request. Please check the message and fix it.
-166Birthday cannot be null.Malformed request. Please check the message and fix it.
-167Invalid Payment Condition.Malformed request. Please check the message and fix it.
-168Invalid Legal Representative Document.Malformed request. Please check the message and fix it.
-169Occupation cannot be null.Malformed request. Please check the message and fix it.
-170Invalid Occupation max 50 characters allowed.Malformed request. Please check the message and fix it.
-171Invalid PixKeyType.Malformed request. Please check the message and fix it.
-172Invalid PixKey.Malformed request. Please check the message and fix it.
-173PixKeyType must be specified.Malformed request. Please check the message and fix it.
-174PixKey must be specified.Malformed request. Please check the message and fix it.
-175Service notfound.Malformed request. Please check the message and fix it.
-176Merchant can be disabled only when it is Active.Malformed request. Please check the message and fix it.
-177Missing card information.Malformed request. Please check the message and fix it.
-178PixKey must belong to an account registered with the same registration document.Malformed request. Please check the message and fix it.
-179BankAccount document must be the same Document as your account.Malformed request. Please check the message and fix it.
-180Item amount can not be null or 0.Malformed request. Please check the message and fix it.
-181Installments can not be null or 0.Malformed request. Please check the message and fix it.
-182Flow not found.Malformed request. Please check the message and fix it.
-183Invalid or not found PixKeyMalformed request. Please check the message and fix it.
-184Invalid politically exposed person.Malformed request. Please check the message and fix it.
-185Spanshots not found.Malformed request. Please check the message and fix it.
-186Birthday cannot be less then 18 years ago.Malformed request. Please check the message and fix it.
-187Invalid Mother name.Malformed request. Please check the message and fix it.
-188Must supply phone or cellphone number.Malformed request. Please check the message and fix it.
-189Duplicated Legal DocumentMalformed request. Please check the message and fix it.
-190Inactive merchant.Malformed request. Please check the message and fix it.
-191Missing plan for payment type.Malformed request. Please check the message and fix it.
-192The merchant is invalid.Malformed request. Please check the message and fix it.
-193The merchant contract does not exist.Malformed request. Please check the message and fix it.
-194Force capture not allowed.Malformed request. Please check the message and fix it.
-195Payment has more than one methods. The operation is not allowed.Malformed request. Please check the message and fix it.
-196Partner 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.

CodeMessage (it may vary according to custom settings)Behavior
1Operation OK........................................................
-1Request object is nullContact support and inform this code and data request.
-1Session object is invalidContact support and inform this code and data request.
-1Session has expiredContact support and inform this code and data request.
-1Card data missingContact support and inform this code and data request.
-1Card already tokenizedContact support and inform this code and data request.
-1Expiration date is invalidContact support and inform this code and data request.
-1Card number is invalidContact support and inform this code and data request.
-1Invalid TokenContact support and inform this code and data request.
-1Token can not be removedContact support and inform this code and data request.
-1Card can not be removedContact support and inform this code and data request.
-1AppToken is requiredContact support and inform this code and data request.
-1Partner Not ExistsContact support and inform this code and data request.
-1AppToken is invalidContact support and inform this code and data request.
-1Customer data missingContact support and inform this code and data request.
-1Token data missingContact support and inform this code and data request.
-1Card token is invalidContact support and inform this code and data request.
-1Card holder name is invalidContact support and inform this code and data request.
-1User has reached maximum number of cards allowedContact support and inform this code and data request.
-1User has reached maximum number of sessions allowedContact support and inform this code and data request.
-1Invalid UserDataContact support and inform this code and data request.
-1Card.Data size exceeded. Must be up to 4 kbytesContact support and inform this code and data request.
-1Empty configurationContact support and inform this code and data request.
-1An 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 categoriesIndicator to be send (credentialId)Corresponding Sub-Category
card holder initiated (CIT)01Card on File (Credencial armazenada)
card holder initiated (CIT)02Ordem Permanente
card holder initiated (CIT)03Assinatura
card holder initiated (CIT)04Parcelado
merhant initiated (MIT) recurring or installment payments05Card on File (Credencial armazenada) – não programada
merhant initiated (MIT) recurring or installment payments06Ordem Permanente
merhant initiated (MIT) recurring or installment payments07Assinatura
merhant initiated (MIT) recurring or installment payments08Parcelado
merhant initiated (MIT) business practices09Remessa Parcial
merhant initiated (MIT) business practices10Cobrança atrasada
merhant initiated (MIT) business practices11No show (Multa)
merhant initiated (MIT) business practices12Reenvio

Delivery Types#

Items delivery types and descriptions are listed in the file deliveryTypes.json. They are also listed in the table below:

DeliveryType IdDelivery Type
1PickUp
2Delivery
3UltraFast
4ClickCollect