API Guide#
Table of Contents#
- Introduction
- Payment Integration
- Split Integration
- Tuna Codes
- Webhooks Notifications
- Sandbox Environment
- Idempotent Requests
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 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 |
| 5 | ThreeDSCredit | 3DS 1.0 Credit Card |
| 6 | ThreeDSDebit | 3DS 1.0 Debit Card |
| 7 | ThreeDS20Credit | 3DS 2.0 Credit Card |
| 8 | ThreeDS20Debit | 3DS 2.0 Debit Card |
| 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 |
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 | PendingCancel | 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. |
Message Code List#
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 | Successful Payment. | The request has been successfully processed. |
| -101 | Request object is null. | Malformed request. Please check the message and fix it. |
| -102 | Invalid Payment. | Malformed request. Please check the message and fix it. |
| -103 | Invalid Payment Items. | Malformed request. Please check the message and fix it. |
| -104 | At least one card must be present for the type of payment | 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 | Custom External Key s invalid. | 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. | 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 | CVV not valid. | 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 | Invalid Partner. | Configuration issue. Please check your credentials. |
| -113 | Invalid Partner Credentials. | Configuration issue. Please check your credentials. |
| -114 | Invalid Partner Account. | 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 | Configuration error. | 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 can not be null. | Malformed request. Please check the message and fix it. |
| -119 | Operation failed. | Contact support and inform this code and data request. |
| -120 | Ivalid amount. | Malformed request. Please check the message and fix it. |
| -121 | Unexpected error. | Contact support and inform this code and data request. |
| -122 | Merchant does not exist. | Malformed request. Please check the message and fix it. |
| -123 | Merchant Percentage and amount, both 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 | Merchant status is invalid. Should be '1' for Active, '2' for Inactive or '3' for Suspended. | Malformed request. Please check the message and fix it. |
| -129 | Merchant Name 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. Valid values are 'C' for Checking, 'S' for Saving, 'P' for Payment or 'D' for Deposit. | Malformed request. Please check the message and fix it. |
| -133 | Date filters are invalid. | Malformed request. Please check the message and fix it. |
| -134 | Merchant Percentage invalid. | Malformed request. Please check the message and fix it. |
| -135 | Merchant amount invalid. | Malformed request. Please check the message and fix it. |
| -136 | Merchant shipping amount invalid | Malformed request. Please check the message and fix it. |
Resources#
API Guide: are you looking for a guide for our APIs? Check out the introduction to the API Guide.
Payment Integration: do you need to be able to perform secure credit card payments and/or also use other payment methods such as Debit Card, Boleto, PIX, Bitcoin? Checkout how to perform a Payment Integration with our Payment API and Token API.
Split Integration: are you looking to set up a marketplace, so your merchants will use split payment solutions in your marketplace? Check out how to perform a Split Integration with our Merchant API.
Tuna Codes: do you need to learn about your codes and status? Please, check out the Tuna Codes.
Webhooks Notifications: learn more about our notifications in the guide Webhooks Notifications.
Sandbox Environment: check out for information about test data and a full description of the Sandbox Environment.
Idempotent Requests: do you require idempotent requests? Take a look how to make Idempotent Requests.