Payment Components

In this section, you will learn about the three components of a payment operation when using MoneyHash. These three components are:

Intent

Transaction

Operation

Each component has its own distinct set of possible statuses and related concepts. You can find detailed explanations for each one in the following sections. This page also presents an example describing the relation between these components and how their status changes over time when a payment is created.

Intents

A Payment Intent is an entity that holds all the information needed to process a customer payment successfully through a payment provider. It'll store information related to the following:

The operation to be executed, such as pay-ins or pay-outs.
Currency selected for the operation.
Selected payment method.
Transaction amount.
Billing data.

Each intent can be associated with one or more transactions. As transactions fail, new ones can be created and associated with the intent to try to perform the payment operation successfully.

Intents have a set of possible statuses that indicate their current state:

Status	Description
UNPROCESSED	This is the default status for created intents. The intent waits for the next customer action, such as selecting or changing the payment method. The intent will change from the UNPROCESSED state only when it completes its cycle.
TIME_EXPIRED	An intent expires based on the expiring time configuration, defined by the `expires_after_seconds` parameter. When the intent changes to the TIME_EXPIRED state, users can't take any new action with the intent and any pending transaction will transition to failed.
CLOSED	The intent gets closed when `/close` endpoint is called for a specific intent, or the intent has too many failed transactions. When the intent changes to the `CLOSED` state, users can't take any new action with the intent and any pending transaction will transition to failed.
PROCESSED	The intent is processed and reaches the final state. When the intent changes to the PROCESSED state, users can't take any new action with the intent.

Whenever the intent status changes, MoneyHash will notify you through webhooks.

Transactions

A transaction refers to a financial activity, and as mentioned above, one or more transactions may be related to the same intent. When you create an intent, you automatically create a transaction. If the transaction fails and the customer tries to perform the payment again using the same or a different payment method, a new transaction will be created.

In the MoneyHash Dashboard, transaction statuses are not related to the stage of the current transaction. Instead, the transaction status informs the type of the last operation executed in this transaction. The possible transaction status and description are in the table below.

Status	Description	Possible Following Operations
PURCHASE	Represents a payment transaction where the funds are immediately transferred from the customer's payment source.	`CAPTURE` `VOID` `REFUND` `INCREASE_PURCHASE_AMOUNT` `DECREASE_PURCHASE_AMOUNT`
AUTHORIZE	A preliminary check on a customer's payment method to ensure that the funds are available and the transaction can proceed	`AUTHORIZE` `CAPTURE` `VOID` `INCREASE_AUTHORIZATION`
CAPTURE	After authorization has been made, a capture operation is used to confirm and complete the payment.	`CAPTURE` `VOID` `REFUND`
REFUND	Used when the merchant needs to return funds to the customer after a successful purchase.	`REFUND`
Void	Used to cancel an authorization that was previously made but hasn't been captured yet.	`VOID` `CAPTURE`
BLOCKED	The transaction is blocked, and no further action can be taken.	-
INCREASE_AUTHORIZATION	The transaction is requesting an increase in authorization for a transaction.	`INCREASE_AUTHORIZATION` `CAPTURE` `VOID`
INCREASE_PURCHASE_AMOUNT	The transaction is requesting an increase in the purchase amount.	`INCREASE_PURCHASE_AMOUNT` `DECREASE_PURCHASE_AMOUNT` `PURCHASE`
DECREASE_PURCHASE_AMOUNT	The transaction is requesting a decrease in the purchase amount.	`INCREASE_PURCHASE_AMOUNT` `DECREASE_PURCHASE_AMOUNT` `PURCHASE`

Operations

Operations are any financial operation executed with the provider. As mentioned above, a transaction may be associated with one or more operations. When a transaction is created, it is automatically associated with a pending status by default. The possible status and description of each possible operation are below:

Blocked

Status	Allowed Following Status	Sends a webhook
SUCCESSFUL	-	✅

Purchase

Status	Allowed Following Status	Sends a webhook
PENDING	`PENDING_AUTHENTICATION` `PENDING_EXTERNAL_ACTION` `PENDING_ONLINE_EXTERNAL_ACTION` `PENDING_AUTHORIZATION` `FAILED` `SUCCESSFUL`	❌
PENDING_AUTHENTICATION	`FAILED` `SUCCESSFUL`	✅
PENDING_EXTERNAL_ACTION	`FAILED` `SUCCESSFUL`	✅
PENDING_ONLINE_EXTERNAL_ACTION	`FAILED` `SUCCESSFUL`	✅
PENDING_AUTHORIZATION	`FAILED` `SUCCESSFUL`	✅
FAILED	-	✅
SUCCESSFUL	-	✅

Authorize

Status	Allowed Following Status	Sends a webhook
PENDING	`PENDING_AUTHENTICATION` `FAILED` `SUCCESSFUL`	❌
PENDING_AUTHENTICATION	`FAILED` `SUCCESSFUL`	✅
FAILED	-	✅
SUCCESSFUL	-	✅

Increase Authorization

Status	Allowed Following Status	Sends a webhook
PENDING	`PENDING_AUTHENTICATION` `FAILED` `SUCCESSFUL`	❌
PENDING_AUTHENTICATION	`FAILED` `SUCCESSFUL`	✅
FAILED	-	✅
SUCCESSFUL	-	✅

Capture

Status	Allowed Following Status	Sends a webhook
PENDING	`PENDING_AUTHENTICATION` `FAILED` `SUCCESSFUL`	❌
PENDING_AUTHENTICATION	`FAILED` `SUCCESSFUL`	✅
FAILED	-	✅
SUCCESSFUL	-	✅

Void

Status	Allowed Following Status	Sends a webhook
PENDING	`FAILED` `SUCCESSFUL`	❌
FAILED	-	✅
SUCCESSFUL	-	✅

Refund

Status	Allowed Following Status	Sends a webhook
PENDING	`FAILED` `SUCCESSFUL`	❌
FAILED	-	✅
SUCCESSFUL	-	✅

Increase purchase amount

Status	Allowed Following Status	Sends a webhook
FAILED	-	✅
SUCCESSFUL	-	✅

Decrease purchase amount

Status	Allowed Following Status	Sends a webhook
FAILED	-	✅
SUCCESSFUL	-	✅

Pay-in example

Here, you can follow an overview of the full process, considering all the above components. This example covers creating a new intent, making multiple transactions, and making a transaction outside an intent.

Step 1: Creating a new intent

The process begins when the customer starts the payment process. A new intent is created with an UNPROCESSED status at this stage.

Step 2: First transaction attempt

When the customer chooses his payment method, the first transaction is created already with its first operation of Purchase with a PENDING status. It will remain with this status while waiting for the customer to proceed.

If the customer tries to execute a payment with a method that fails, the operation will reach a FAILED status. As it fails, the transaction ends.

With the first transaction completed with failure, the intent remains UNPROCESSED. Therefore, new transactions associated with the intent can be executed.

Step 3: Second transaction attempt

As a new transaction begins, it will again start with an operation with PENDING status.

Considering that the payment execution succeeds, the operation inside the second transaction changes to a SUCCESSFUL status.

As a transaction succeeds, the intent changes its status to PROCESSED. As a result, no further transaction can be created and associated with this intent.

Step 4: Refund operation

As mentioned above, when the intent changes to the PROCESSED status, no more transactions can be created and associated with it. However, new operations, such as Void, Refund, and Capture, can be executed to an existing transaction.

As the last step of this example, we will perform a refund operation. The refund must be associated with the successful transaction from Step 3 once it's impossible to perform a refund with a failed transaction.

To start the refund, a new operation is created in the transaction. As you progress and execute a full or partial refund, the operation associated with the refund will change its status to SUCCESSFUL, and the transaction will also change from PURCHASE to REFUND. As a result, the transaction now has two distinct associated operations, first the purchase operation and then the second showing your refund.