Skip to main content
Tapi Cash is a cash payment method by Mattilda that allows buyers in Latin America to pay using cash vouchers. Tapi uses a redirect flow where the buyer receives payment instructions.
This connector is a custom integration for Mattilda and is only available to enrolled users. Contact Mattilda directly to begin the onboarding process.

​
Setup

Contact the Tapi account manager to obtain credentials.

​
Credentials

When setting up Tapi Cash in the dashboard, configure the following credentials:
  • Username - The Tapi username.
  • Password - The Tapi password.
  • Login API key - The API key for the /login endpoint.
  • References API key - The API key used to create and retrieve reference data via the /reference endpoint.
  • Approval URL - The custom frontend URL provided by Mattilda.
  • Tapi Modality ID - The identifier of the payment modality used in the transaction.
  • Tapi company code - The company code associated with the operation.
  • Tapi identifier name (optional) - The identifier name associated with the operation.

​
Features

Tapi Cash supports the following features:
  • Direct capture - Payments are captured immediately at the time of authorization
  • Refunds - Refund transactions in full

​
Supported countries

Tapi Cash supports transactions from buyers in the following countries:
Country codeCountry codeCountry codeCountry codeCountry codeCountry codeCountry codeCountry code
ARCOMXPE

​
Supported currencies

Tapi Cash supports processing payments in the following currencies:
Currency codeCurrency codeCurrency codeCurrency codeCurrency codeCurrency codeCurrency codeCurrency code
ARSCOPMXNPENUSD

​
Limitations

The following features are not supported by this connector:
  • Delayed capture - Authorizing a payment and capturing it later is not supported
  • Void - Canceling an authorized transaction before capture is not supported
  • Partial refunds - Partial refunds are not supported
  • Partial capture - Capturing a portion of the authorized amount is not supported
  • Over capture - Capturing more than the authorized amount is not supported
  • Partial authorization - Accepting a partial amount is not supported
  • Payment method tokenization - Storing payment methods for future use is not supported
  • Zero auth - Zero-dollar verification transactions are not supported
  • Transaction sync - Automatic transaction status synchronization is not supported
  • Settlement reporting - Automatic settlement reporting is not supported

​
Webhooks

Tapi requires manual webhook setup. Contact Mattilda to request the webhook URL and configure it for your account. Tapi sends the following webhook events:
  • confirmed - The payment was successfully captured.
  • failed - The payment could not be processed or was rejected.
  • reverse - A retraction of a previous capture event. This indicates the capture did not actually complete on Tapi’s side. Mattilda handles the reversal by triggering a full refund to align the transaction state.
A reversal is not a real refund at the PSP level. It marks the transaction as reversed in alignment with Tapi’s state.

​
Integration

The default integration for Tapi Cash uses a redirect flow. Start by creating a new transaction with the following required fields. 
var transaction = await client.Transactions.CreateAsync(
  transactionCreate: new TransactionCreate()
  {
    Amount = 1299,
    Currency = "MXN",
    Country = "MX",
    PaymentMethod =
      TransactionCreatePaymentMethod.CreateCheckoutSessionWithUrlPaymentMethodCreate(
        new RedirectPaymentMethodCreate()
        {
          Method = "tapi",
          RedirectUrl = "https://example.com/callback",
        }
      ),
  }
);
After the transaction is created, the status is set to processing. The payment reference expires after 7 days. 
{
  "type": "transaction",
  "id": "ea1efdd0-20f9-44d9-9b0b-0a3d71e9b625",
  "payment_method": {
    "type": "payment-method",
    "approval_url": "https://cdn.gr4vy.com/connectors/..."
  },
  "method": "tapi"
}
Redirect the buyer to the approval_url where they receive payment instructions. Once payment is confirmed through a webhook, the transaction progresses to a capture_succeeded state.

​
Connection options

The Tapi connector supports passing a payment expiration date when creating a transaction. 
var transaction = await client.Transactions.CreateAsync(
  transactionCreate: new TransactionCreate()
  {
    Amount = 1299,
    Currency = "MXN",
    ConnectionOptions = new TransactionCreateConnectionOptions()
    {
      MattildaTapi = new ConnectionOptionsMattildaTapi()
      {
        PaymentMethodExpiresAt = "2026-03-27",
      },
    },
    PaymentMethod =
      TransactionCreatePaymentMethod.CreateCheckoutSessionWithUrlPaymentMethodCreate(
        new RedirectPaymentMethodCreate()
        {
          Method = "tapi",
          RedirectUrl = "https://example.com/callback",
        }
      ),
  }
);
The payment_method_expires_at field must be in ISO 8601 format (YYYY-MM-DD). If not specified, it defaults to 7 days from the transaction creation date.