Skip to main content

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:

{
"id": 21636,
"paymentKey": "134641C000053BB",
"partnerUniqueId": "22193",
"statusId": "P",
"amount": 65.97,
"operationId": "O0002134641C000063D3",
"methods": [
{
"methodType": "D",
"status": "C",
"methodId": 0,
"oprarionAmount": 65.97
}
],
"items": [
{
"paymentItemId": 0,
"productID": 11,
"productDescription": "Pizza",
"amount": 21.990000,
"quantity": 3,
"categoryID": 0,
"data": {
"ProductID": 11,
"CategoryID": 0
}
}
]
}
PropertyDescription
idThe id of the notification
paymentKeyThe "Tuna id" of the transaction being notified
partnerUniqueIdThe id used by the partner to identify the transaction
statusIdThe new status of the transaction
amountThe full amount of the transaction
operationIdThe id of the operation (informed, for example, in a cancellation request)
methodsThe list of payment methods used for this transaction
itemsThe 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 CodeStatusDescription
0StartedThe payment has started, but no transactions have been executed at this point.
1AuthorizedThe payment has been authorized, but noy yet captured. The balance has been reserved on the credit card.
2CapturedThe payment has been captured, so the funds are secured.
3RefundedThe payment has been refunded.
4DeniedThe payment has been denied by the issuing bank, acquirer or anti-fraud provider.
5CancelledThe payment has been cancelled after being previously authorized.
6AbandonedThe payment has been abandoned. It's been started for too long and never evolved to another status.
7ChargebackThe payment has been reported as chargeback.
8MoneyReceivedFunds of the payment have been transferred to the partner.
9PartialRefundedThe payment has been partially refunded.

Payment Methods#

See below the types of payment and payment methods:

Payment Method IDPayment MethodDescription
1CreditCardCredit Card
2DebitCardDebit Card
3BoletoBrazilian Bank Slip
4BankTransferBank Wire Transfer
5ThreeDSCredit3DS 1.0 Credit Card
6ThreeDSDebit3DS 1.0 Debit Card
7ThreeDS20Credit3DS 2.0 Credit Card
8ThreeDS20Debit3DS 2.0 Debit Card
9ExternalGeneric External Payment
AGiftCardGift Card Provider
BBalanceProprietary Credit System Balance
CCreditCardPrivateBrandPrivate Label Credit Card
DPIXBrazilian 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 CodeStatusDescription
0StartedThe transaction of this method has started, but no transactions have been processed yet.
1AuthorizedThe transaction of this method has been authorized, but noy yet captured. Credit limit has been reserved on the credit card.
2CapturedThe transaction of this payment method has been captured and funds are secured.
3RefundedThe transaction of this payment method has been refunded.
4DeniedThe transaction of this payment method has been denied either by the issuing bank, acquirer or anti-fraud tool.
5CancelledThe transaction of this payment method has been cancelled after being previously authorized.
6AbandonedThe 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.
7ChargebackThe transaction of this payment method has been reported as chargeback.
8MoneyReceivedThe funds of the transaction of this payment method have been transferred to the store.
9PartialRefundedThe transaction of this payment method 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.
DPendingCancelFor some reason the transaction of this payment method could not be cancelled. 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 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.

Message Code List#

See below the possible return codes of the message objects:

CodeMessage (it may vary according to custom settings)Behavior
1Successful Payment.Request has been successfully processed.
-101Request object is null.Malformed request. Please check the message and fix it.
-102Invalid Payment.Malformed request. Please check the message and fix it.
-103Invalid Payment Items.Malformed request. Please check the message and fix it.
-104At least one card must be present for the type of paymentMalformed request. Please check the message and fix it.
-105Partner id cannot be nullMalformed request. Please check the message and fix it.
-106Partner Unique id cannot be null.Malformed request. Please check the message and fix it.
-107Custom External Key s invalid.Malformed request. Please check the message and fix it.
-108Partner Unique id already used.Repeated request, it will not be processed.
-109Invalid 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.
-110CVV not valid.Malformed request. Please check the message and fix it.
-111Partner Token was not provided.Malformed request. Please check the message and fix it.
-112Invalid Partner.Configuration issue. Please check your credentials.
-113Invalid Partner Credentials.Configuration issue. Please check your credentials.
-114Invalid Partner Account.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.
-117Configuration 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.
-118Order Identifier can not be null.Malformed request. Please check the message and fix it.
-119Operation failed.Contact support and inform this code and data request data.
-120Ivalid amount.Malformed request. Please check the message and fix it.
-121Unexpected error.Contact support and inform this code and data request.
-122Merchant does not exist.Malformed request. Please check the message and fix it.
-123Merchant Percentage and amount, both 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.
-128Merchant status is invalid. Should be '1' for Active, '2' for Inactive or '3' for Suspended.Malformed request. Please check the message and fix it.
-129Merchant Name 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. 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.
-133Date filters are invalid.Malformed request. Please check the message and fix it.
-134Merchant Percentage invalid.Malformed request. Please check the message and fix it.
-135Merchant amount invalid.Malformed request. Please check the message and fix it.
-136Merchant shipping amount invalidMalformed 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 NumberResult
4111111111111111It varies according to the card holder name
5555555555554444It varies according to the card holder name
Card Holder NameResult
AuthorizedTransaction Authorized
CapturedTransaction Captured
Not AuthorizedTransaction Not Authorized
ErrorTransaction Error
InvalidConfiguration Error
PendingTransaction Capture Pending
ExpiredTransaction 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.