Pre-Orders with QR Integration

Introduction

This document describes the TotalCoin API endpoints for managing pre-orders with QR code generation and processing.

Authentication

API access control is implemented using OAuth 2.0 with Bearer Tokens.

Endpoint

POST api/auth/login

Request

{
    "username": "",
    "password": ""
}

Field	Type	Description	Required
username	String	Username	Yes
password	String	Password	Yes

Response (HTTP 200)

{
    "token": "",
    "expires_in": 3600
}

Field	Type	Description
token	String	Authentication token
expires_in	Number	Token validity in seconds

Possible Errors

Code	Description
401	Invalid or non-existent credentials
403	Insufficient permissions to access the API

Credentials: Must be requested from the technical department.

Create Pre-Order

Creates a new pre-order and generates a QR code for payment.

Endpoint

POST https://apicobranzastest.totalcoin.com/api/iep/pre-order

Request

        {
            "concept": "test-jpgq",
            "expirationDate": "2025-03-26T17:23:14.099Z",
            "businessUnit": 348,
            "externalReference": "JPGQ_PAYMENT_001",
            "qrAmountType": "closed",
            "amount":10,
            "qrType": "static",
            "resetOnPayment": true,
            "operationId": "ca8964d1-b90b-4583-98da-bfc7f757d6e7",
            "dni": "27594189",
            "companyReferenceToConciliate": "OP:000001110001"
        }

Field	Type	Description	Required
concept	String	A description or identifier for the payment	Yes
expirationDate	String	When the QR code will expire and no longer be valid for payment	Yes
businessUnit	String	Identifier for the business unit receiving the payment	Yes
externalReference	String	External reference ID for tracking/reconciliation	Yes
qrAmountType	Object	Whether amount is fixed ("closed") or variable ("open")	Yes
amount	String	The payment amount in the default currency	Yes
qrType	String	"static" for fixed QR codes, "dynamic" for one-time use	Yes
resetOnPayment	String	If true, QR code can be reused after successful payment	Yes
operationId	String	Merchant Transaction Reference, this is a value provided by Arbet System and indicates the id of this payment in your system	Yes
dni	String	Document number of the payer	Yes
companyReferenceToConciliate	String	Reference used for payment reconciliation	Yes

Response (HTTP 201)

                    {
                        "id": 13010,
                        "qrCode": "00020101021143510033com.totalcoin.integracionesqrtest0210000001301050150011307180924815126002200002228000000000577235204490053030325802AR5905ARBET6012Buenos Aires62200116JPGQ_PAYMENT_0016304584D",
                        "expirationDate": "2025-03-26T17:23:14.099Z",
                        "amount": 10.0,
                        "concept": "test-jpgq", 
                        "businessUnitName": "ARBET",
                        "cashier": "ARBET ",
                        "externalReference": "JPGQ_PAYMENT_001",
                        "isEnabled": true
                    }

Field	Type	Description
id	String	Unique identifier assigned to the preorder
qrCode	String	The generated QR code string that can be rendered for payment
expirationDate	String	When the QR code will expire and become invalid
amount	String	The payment amount in the default currency
concept	String	Description or identifier for the payment
businessUnitName	String	Name of the business unit receiving payment
cashier	String	Name of the cashier/point of sale
externalReference	String	External reference ID for tracking
isEnabled	String	Whether the QR code is currently active and usable

Possible Errors

Code	Description
400	Invalid request parameters
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions

Webhook Notifications

The notification webhook is called when a payment is received either through a transfer, QR payment, or card payment.

It is also called when automatic reconciliation of the pre-order occurs.

Webhook Payload

                    {
                        "Concepto": "1234567890",
                        "Referencia": "0000004053",
                        "Monto": 1000,
                        "MontoNeto": 937.2,
                        "Tarifas": 51.9,
                        "Impuestos": 10.9,
                        "FechaCreacion": "11/19/2020 16:40:20",
                        "FechaConfirmacion": "11/19/2020 16:40:23",
                        "FechaAcreditacion": "04/21/2021 14:34:53", 
                        "Estado": "APROBADO",
                        "MetodoPago": "TARJETA", 
                        "Operacion": "COBRANZA TARJETA",
                        "NombreCompletoEmisor": "TOTAL COIN", 
                        "EmailEmisor":"@totalcoin.com", 
                        "NombreCompletoReceptor": "TOTAL COIN", 
                        "EmailReceptor": "@totalcoin.com", 
                        "CuilCuitEmisor": "11111111",
                        "CuilCuitReceptor": "11111111", 
                        "BarCode": null,
                        "CbuOrigen": "", 
                        "CvuOrigen": null, 
                        "Tarjeta": "VISA",
                        "Cuotas": "02", 
                        "ReferenciaMerchant": null
                    }

The most important fields in this body are:

Field	Description
Referencia	Internal and unique reference number for the Totalcoin transaction
Monto	Amount
Estado	Latest operation status
ReferenciaMerchant	Merchant's Operation ID

Webhook Configuration: Contact the technical department to configure webhook endpoints and define their security.