Payment Notifications#
To receive a payment status notification (ie: payment settlement or cancellation confirmation), you need to first configure the webhook url in your Console.
See below the flow of a notification:
And here is an example of a notification payload:
| Property | Description |
|---|---|
| id | The id of the notification |
| paymentKey | The "Tuna id" of the transaction being notified |
| partnerUniqueId | The id used by the partner to identify the transaction |
| statusId | The new status of the transaction |
| amount | The full amount of the transaction |
| operationId | The id of the operation (informed, for example, in a cancellation request) |
| methods | The list of payment methods used for this transaction |
| items | The list of payment items |
Payment Status#
It can be considered a subset of payment method status.You should track the payment status to make decisions regarding the approval of your overall order.
Check payment method status only when you explicitly need to take action on a specific payment method's result. Most times just tracking the payment status will be enough.
See below all payment statuses.
| Status Code | Status | Description |
|---|---|---|
| 0 | Started | The payment has started, but no transactions have been executed at this point. |
| 2 | Captured | The payment has been captured, so the funds are secured. |
| 3 | Refunded | The payment has been refunded. |
| 4 | Denied | The payment has been denied by the issuing bank, acquirer or anti-fraud provider. |
| 5 | Cancelled | The payment has been cancelled after being previously authorized. |
| 6 | Abandoned | The payment has been abandoned. It's been started for too long and never evolved to another status. |
| 7 | Chargeback | The payment has been reported as chargeback. |
| 8 | MoneyReceived | Funds of the payment have been transferred to the partner. |
| 9 | PartialRefunded | The payment has been partially refunded. |
| P | Pending | The system is waiting for the result of another process, such as anti-fraud analysis, to complete the transaction. Whether the transaction has already been authorized or not depends on how your flows are configured. |
Payment Methods#
See below the types of payment and payment methods:
| 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.
See below the payment method statuses:
| Status Code | Status | Description |
|---|---|---|
| 0 | Started | The transaction of this method has started, but no transactions have been processed yet. |
| 1 | Authorized | The transaction of this method has been authorized, but noy yet captured. Credit limit has been reserved on the credit card. |
| 2 | Captured | The transaction of this payment method has been captured and funds are secured. |
| 3 | Refunded | The transaction of this payment method has been refunded. |
| 4 | Denied | The transaction of this payment method has been denied either by the issuing bank, acquirer or anti-fraud tool. |
| 5 | Cancelled | The transaction of this payment method has been cancelled after being previously authorized. |
| 6 | Abandoned | The transaction of this payment method has been abandoned. It remained with the Started status for too long, without changing to another status in the meantime. |
| 7 | Chargeback | The transaction of this payment method has been reported as chargeback. |
| 8 | MoneyReceived | The funds of the transaction of this payment method have been transferred to the store. |
| 9 | PartialRefunded | The transaction of this payment method 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 cancelled. 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 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#
See below the possible return codes of the message objects:
| Code | Message (it may vary according to custom settings) | Behavior |
|---|---|---|
| 1 | Successful Payment. | 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. | Repeated request, 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 our support with 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 data. |
| -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. |
Test Data#
See below the test data you can use and the expected result for each of them:
| Card Number | Result |
|---|---|
| 4111111111111111 | It varies according to the card holder name |
| 5555555555554444 | It varies according to the card holder name |
| Card Holder Name | Result |
|---|---|
| Authorized | Transaction Authorized |
| Captured | Transaction Captured |
| Not Authorized | Transaction Not Authorized |
| Error | Transaction Error |
| Invalid | Configuration Error |
| Pending | Transaction Capture Pending |
| Expired | Transaction Expired |
Idempotent Requests#
The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to submit a charge does not respond due to a network connection error, you can retry the request with the same idempotency key to ensure this charge request will not be duplicated..
To perform an idempotent request, provide an additional Idempotency-Key: [key] header to the request.
Tuna's idempotency works by saving the resulting status code and body of the first request submitted for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key will return the same result, including 500 errors.
An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions.
Keys are eligible to be removed from the system automatically after they're at least 24 hours old. A new request is generated if a key is reused after the original has been pruned. The idempotency layer compares incoming parameters to those of the original request and errors, unless they're the same, to prevent accidental misuse.
Results are saved only if an API endpoint has started to execute. If incoming parameters have failed the validation, or have the request conflicted with another that was executing concurrently, no idempotent result will be saved because no API endpoint has begun the execution. It is safe to retry these requests.
All POST requests accept idempotency keys. Sending idempotency keys in GET and DELETE requests has no effect and should be avoided, since they are idempotent by definition.