API initCheckout

New checkout generation request (Merchant Server > Tinaba): The response returns a valid payment code to make the payment.

Attribute explanation

Name of domainTypeMandatoryDescription
merchantIdStringYesIdentifier of the merchant assigned by TINABA
merchantDeviceIdStringNoTerminal linked to the transaction (Unique Cash ID)

The identifier of the pending payment on the merchant's server. It must be unique for each call

amountStringYesAmount in cents
currencyStringYesDivided (EUR)
descriptionStringNoThe description to associate with the payment
validToStringNoMaximum wait before timeout (numeric string that expresses minutes). If not specified, Tinaba's default will be used
creationDateStringYesThe date the payment was created on the merchant's server (yyyyMMdd date format). Used only for data integrity verification
creationTimeStringYesThe time the payment was created on the merchant's server (time hhmmss format). Used only for data integrity verification
paymentModeStringYesPossible values: ECOMMERCE, MEDIA, PREAUTH.

ECOMMERCE: Payment does not require confirmation from the merchant. The user completes the transfer directly from the Tinaba app;

PREAUTH: Payment requires confirmation from the merchant. At the confirmation of the user via Tinaba app, the funds will be scaled from their available balance, pending confirmation by the merchant;

MEDIA: The media mode designed for digital content obliges the user to pay only the first time for specific productCodeId. Attempts after the first payment will not require a new payment from the user
productCodeIdStringNoIf paymentMode = MEDIA, this field is required and is used as a unique product code. If you buy the same product multiple times, you will only be required to pay one payment
metadataStringNoFree JSON of the merchant with additional information that you can show in the app (to be agreed with Tinaba)
notificationCallbackStringYesURL of the merchant where the S2S notification will be sent
notificationHttpMethodStringYesThe http method to use to contact the S2S notification endpoint
sendReceiverAddressBooleanNoIf true, one-click mode is configured. The merchant will also receive the shipping and billing information of the user who completed the payment within the S2S notification
signatureStringYesAuthentication and data integrity signature

The data integrity signature, exchanged in the "signature" field, is based on a shared secret, exchanged offline, and is generated using the SHA256 protocol.

For more information on how to generate the integrity signature, see:

Data integrity >

Attribute explanation – response

Name of domain

statusStringYes000 = OK

001 = KO
paymentCodeStringNoValued only if status = 000

Checkout ID
errorCodeStringNoValued only if status = 001

Error code
paymentCodeURLStringNoNot used


  "data": {
    "request": {
      "initCheckoutRequest": {
        "merchantId": "12",
        "externalId": "TR_1",
        "amount": "100",
        "currency": "EUR",
        "description": "Pagamento e-commerce",
        "validTo": "2",
        "creationDate": "20170111",
        "creationTime": "141054",
        "paymentMode": "ECOMMERCE",
        "metadata": "{"articolo":"12345"}",
        "signature": "AAIF34576……943",
        "notificationCallback": "http://example.com/notify",
        "notificationHttpMethod": "POST"


200 Success

  "response": {
    "initCheckoutResponse": {
      "status": "000",
      "paymentCode": "AAAID7865"

400 Error Validation

    "response": {
        "initCheckoutResponse": {
            "status": "001",
            "errorCode": "XXXXX"

$initCheckoutRequest = new InitCheckoutRequest();
    ->setAmount(‘100’) // Expressed in cents
    ->setDescription(‘Customized Mug purchase’)
    ->setValidTo(’10’) // Expressed in minutes
// The API Client instantiated before
$response = $client->initCheckout($initCheckoutRequest);
echo "Payment code: " . $response->code;
// Available payment modes are

For the full PHP SDK visit this link

from sdk.objects import InitCheckoutRequest
from datetime import datetime
action = factory.make(‘init.checkout’)
action.body_params = InitCheckoutRequest(externalId=‘TR_01’,
                                         amount=‘100’,  # expressed in cents
                                         description=‘Customized Mug purchase’,
                                         validTo=’10’,  # expressed in minutes
response = action.run()
print(‘Payment code: {}’.format(response.paymentCode))
# Available payment modes are
from sdk.objects import InitCheckoutRequest

For the full PHP SDK visit this link