Transaction Flow

This guide walks you through the complete flow of creating and verifying a transaction using Propaga’s API. The process consists of two main steps:

Creating a new transaction (which generates a verification code)
Validating the transaction with the verification code

Step 1: Create a Transaction

First, you’ll need to create a new transaction. This will generate a verification code that will be sent to the customer.

curl --location --request POST 'https://staging-api.propaga.io/v1/transaction' \
--header 'Authorization: <your_awesome_token>' \
--header 'Content-Type: application/json' \
--data '{
    "cornerStoreId": "57b9d911-1c6e-45c0-be98-bfaeec8d9cf8",
    "totalAmount": 1234,
    "wholesalerTransactionId": "123413123123",
    "deliveryDate": "2024-12-31",
    "products": [
        {
            "externalSKU": "7501018310103",
            "name": "Pasta Spaghetti La Moderna - Moderna - Paquete 200 g",
            "quantity": 5
        }
    ],
    "metadata": {}
}'

import requests
import json

url = "https://staging-api.propaga.io/v1/transaction"

headers = {
    "Authorization": "<your_awesome_token>",
    "Content-Type": "application/json"
}

payload = {
    "cornerStoreId": "57b9d911-1c6e-45c0-be98-bfaeec8d9cf8",
    "totalAmount": 1234,
    "wholesalerTransactionId": "123413123123",
    "deliveryDate": "2024-12-31",
    "products": [
        {
            "externalSKU": "7501018310103",
            "name": "Pasta Spaghetti La Moderna - Moderna - Paquete 200 g",
            "quantity": 5
        }
    ],
    "metadata": {}
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

const axios = require('axios');

const createTransaction = async () => {
  try {
    const response = await axios.post('https://staging-api.propaga.io/v1/transaction', {
      cornerStoreId: '57b9d911-1c6e-45c0-be98-bfaeec8d9cf8',
      totalAmount: 1234,
      wholesalerTransactionId: '123413123123',
      deliveryDate: '2024-12-31',
      products: [
        {
          externalSKU: '7501018310103',
          name: 'Pasta Spaghetti La Moderna - Moderna - Paquete 200 g',
          quantity: 5
        }
      ],
      metadata: {}
    }, {
      headers: {
        'Authorization': '<your_awesome_token>',
        'Content-Type': 'application/json'
      }
    });
    
    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response.data);
  }
};

createTransaction();

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class CreateTransaction {
    public static void main(String[] args) {
        String requestBody = "{"
            + "\"cornerStoreId\": \"57b9d911-1c6e-45c0-be98-bfaeec8d9cf8\","
            + "\"totalAmount\": 1234,"
            + "\"wholesalerTransactionId\": \"123413123123\","
            + "\"deliveryDate\": \"2024-12-31\","
            + "\"products\": [{"
            + "    \"externalSKU\": \"7501018310103\","
            + "    \"name\": \"Pasta Spaghetti La Moderna - Moderna - Paquete 200 g\","
            + "    \"quantity\": 5"
            + "}],"
            + "\"metadata\": {}"
            + "}";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://staging-api.propaga.io/v1/transaction"))
            .header("Authorization", "<your_awesome_token>")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(requestBody))
            .build();

        try {
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
            System.out.println(response.body());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Request Body

The request body should contain the following parameters:

Parameter	Type	Description
`cornerStoreId`	String	The ID of the corner store where the transaction will be created.
`totalAmount`	Number	The total amount of the transaction.
`wholesalerTransactionId`	String	The ID of the transaction in the wholesaler’s system.
`deliveryDate`	String	The expected delivery date of the transaction.
`metadata`	Object	An object containing any additional metadata for the transaction.
`products`	Array of Objects	An array of products in the transaction. Each product object should contain the following parameters:
Parameter	Type	Description
`externalSKU`	String	The SKU of the product.
`name`	String	The name of the product.
`quantity`	Number	The quantity of the product.

If the request is successful, you’ll receive a response like this:

{
    "incrementalID": 999,
    "transactionId": "13e8b9f0-b73f-4498-a245-05aaae7893dc",
    "verificationId": "561f8ed5-8e90-4b32-9637-4f36a0c66286",
    "userPhoneNumber": "****1207"
}

Make sure to store the transactionId and verificationId as you’ll need them for the next step.

Create transaction use-case

Get more information about the create transaction use-case.

Step 2: Validate the Transaction

Once the customer receives the verification code, you’ll need to validate the transaction using both the transactionId and verificationId from the previous step.

curl --location --request PUT 'https://staging-api.propaga.io/v1/transaction/{transactionId}/verification/{verificationId}' \
--header 'Authorization: <your_awesome_token>' \
--header 'Content-Type: application/json' \
--data '{
    "errorCode": "1234"
}'

import requests

url = f"https://staging-api.propaga.io/v1/transaction/{transaction_id}/verification/{verification_id}"

headers = {
    "Authorization": "<your_awesome_token>",
    "Content-Type": "application/json"
}

payload = {
    "errorCode": "1234"
}

response = requests.put(url, headers=headers, json=payload)
print(response.json())

const axios = require('axios');

const validateTransaction = async (transactionId, verificationId) => {
  try {
    const response = await axios.put(
      `https://staging-api.propaga.io/v1/transaction/${transactionId}/verification/${verificationId}`,
      {
        code: '1234'
      },
      {
        headers: {
          'Authorization': '<your_awesome_token>',
          'Content-Type': 'application/json'
        }
      }
    );
    
    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response.data);
  }
};

validateTransaction('transaction-id', 'verification-id');

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class ValidateTransaction {
    public static void main(String[] args) {
        String transactionId = "your-transaction-id";
        String verificationId = "your-verification-id";
        String requestBody = "{\"code\": \"1234\"}";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(String.format(
                "https://staging-api.propaga.io/v1/transaction/%s/verification/%s",
                transactionId, verificationId)))
            .header("Authorization", "<your_awesome_token>")
            .header("Content-Type", "application/json")
            .PUT(HttpRequest.BodyPublishers.ofString(requestBody))
            .build();

        try {
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
            System.out.println(response.body());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

If the verification is successful, you’ll receive a response like this:

{
    "verificationId": "561f8ed5-8e90-4b32-9637-4f36a0c66286",
    "verificationStatus": "Transaction verified successfull"
}

Validate transaction use-case

Get more information about the validate transaction use-case.

Error Handling

Both endpoints may return various error responses that you should handle in your implementation:

Create Transaction Errors

Corner store not found (404)
Amount exceeded the limit credit available (422)
User is in default (422)
Transaction amount below the minimum required (422)
User not verified (422)
Invalid delivery date (422)

Validate Transaction Errors

Transaction not found (404)
Transaction is already verified (422)
Verification not found (404)
Verification not valid (422)

Make sure to implement proper error handling in your code to manage these potential error responses.

Get Started

About

Flows

Integrations

Webhooks

Step 1: Create a Transaction

Request Body

Create transaction use-case

Step 2: Validate the Transaction

Validate transaction use-case

Error Handling

Create Transaction Errors

Validate Transaction Errors

​Step 1: Create a Transaction

​Request Body

Create transaction use-case

​Step 2: Validate the Transaction

Validate transaction use-case

​Error Handling

​Create Transaction Errors

​Validate Transaction Errors

Step 1: Create a Transaction

Request Body

Step 2: Validate the Transaction

Error Handling

Create Transaction Errors

Validate Transaction Errors