API initCheckout
New checkout generation request (Merchant Server > Tinaba): The response returns a valid payment code to make the payment.
Attribute explanation
Name of domain | Type | Mandatory | Description |
---|---|---|---|
merchantId | String | Yes | Identifier of the merchant assigned by TINABA |
merchantDeviceId | String | No | Terminal linked to the transaction (Unique Cash ID) |
externalId | String | Yes | The identifier of the pending payment on the merchant's server. It must be unique for each call |
amount | String | Yes | Amount in cents |
currency | String | Yes | Divided (EUR) |
description | String | No | The description to associate with the payment |
validTo | String | No | Maximum wait before timeout (numeric string that expresses minutes). If not specified, Tinaba's default will be used |
creationDate | String | Yes | The date the payment was created on the merchant's server (yyyyMMdd date format). Used only for data integrity verification |
creationTime | String | Yes | The time the payment was created on the merchant's server (time hhmmss format). Used only for data integrity verification |
paymentMode | String | Yes | Possible 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 |
productCodeId | String | No | If 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 |
metadata | String | No | Free JSON of the merchant with additional information that you can show in the app (to be agreed with Tinaba) |
notificationCallback | String | Yes | URL of the merchant where the S2S notification will be sent |
notificationHttpMethod | String | Yes | The http method to use to contact the S2S notification endpoint |
sendReceiverAddress | Boolean | No | If 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 |
signature | String | Yes | Authentication 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:
Attribute explanation – response
Name of domain | Type | Mandatory | Description |
---|---|---|---|
status | String | Yes | 000 = OK 001 = KO |
paymentCode | String | No | Valued only if status = 000 Checkout ID |
errorCode | String | No | Valued only if status = 001 Error code |
paymentCodeURL | String | No | Not used |
Request
{
"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"
}
}
}
}
Answers
200 Success
{
"response": {
"initCheckoutResponse": {
"status": "000",
"paymentCode": "AAAID7865"
}
}
}
400 Error Validation
{
"response": {
"initCheckoutResponse": {
"status": "001",
"errorCode": "XXXXX"
}
}
}
$initCheckoutRequest = new InitCheckoutRequest();
$initCheckoutRequest->setExternalId(‘TR_01’)
->setAmount(‘100’) // Expressed in cents
->setCurrency(‘EUR’)
->setDescription(‘Customized Mug purchase’)
->setValidTo(’10’) // Expressed in minutes
->setCreationDateTime(Carbon::now())
->setPaymentMode(InitCheckoutRequest::MODE_ECOMMERCE)
->setNotificationUrl(‘https://example.com/TR_01/status’)
->setNotificationHttpMethod(‘POST’);
// The API Client instantiated before
$response = $client->initCheckout($initCheckoutRequest);
echo "Payment code: " . $response->code;
// Available payment modes are
InitCheckoutRequest::MODE_PREAUTH;
InitCheckoutRequest::MODE_ECOMMERCE;
InitCheckoutRequest::MODE_MEDIA;
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
currency=‘EUR’,
description=‘Customized Mug purchase’,
validTo=’10’, # expressed in minutes
creationDateTime=datetime.now(),
paymentMode=InitCheckoutRequest.MODE_ECOMMERCE,
notificationCallback=‘https://example.com/TR_01/status’,
notificationHttpMethod=‘POST’)
response = action.run()
print(‘Payment code: {}’.format(response.paymentCode))
# Available payment modes are
from sdk.objects import InitCheckoutRequest
InitCheckoutRequest.MODE_PREAUTH
InitCheckoutRequest.MODE_ECOMMERCE
InitCheckoutRequest.MODE_MEDIA
For the full PHP SDK visit this link