Pay with Stored Card Details

With MoneyHash, your customers can store card information and use it in the future to perform different transactions.

In MoneyHash, a transaction may be initiated in two different ways:

• Merchant Initiated Transaction (MIT): The merchant submits a transaction using previously stored details without the cardholder's participation.
• Cardholder Initiated Transaction (CIT): The cardholder actively selects the card to use and completes the transaction using previously stored details.

On this page, we provide guidelines on using stored payment information with different transaction categories:

• Regular payment initiated by the customer
• Recurring payments with stored card details
• Unscheduled payments
• Using MoneyHash subscriptions

Creating the intent

Regular customer initiated payment

To accelerate the payment process when a customer pays with a saved card or uses a one-click payment option, you can use the card_token with the customer ID. In this case, the customer doesn't need to select a payment method or provide their full card detail when making the payment request. However, in case you don't inform the card_token, providing only the customer ID, your customer will be given the option to select one of their existing saved payment methods during the payment process.

To create the payment request, you need to include a payment_type field set to regular. In addition, you can use this approach for Authorize or Purchase operations, as long you provide merchant_initiated = false. The table below shows all the necessary fields of the payload you need to provide:

{
  "amount": 50,
  "amount_currency": "USD",
  "operation": "purchase",
  "merchant_initiated": false,
  "payment_type":"regular",
  "customer": "ea84cb76-50a5-4ac2-ba61-f2e17dcdbf54",
  "card_token": "10fbf790-bb27-4afa-87d9-4b57b2d3fb2b",
  "webhook_url": "https://example.com/webhook"
}

Recurring payments with stored card details

Stored cards can be used to pay for recurring transactions, such as a subscription service. Customers need to store their card details during the initial transaction to use this option. The stored card details can be used for future MITs. It's important to notice that the processes for the initial and subsequent transactions differ.

Initial transaction

The initial transaction will store the card details. It's initiated by the cardholder (CIT) and must include the following fields in the request when setting up the agreement:

• "payment_type": "RECURRING"
• "merchant_initiated": false

You need to inform the details of the recurring payment agreement in the recurring_data object. The is composed of the following parameters:

• agreement_id: Specify the ID for the agreement. You may define this ID according to your preference.
• number_of_payments: Number of recurring payments to be paid by your customer.
• days_between_payments: Number of days between each payment.
• expiry_date: The date that the agreement will expire.

The following JSON exemplifies the payload for this intent:

{
  "amount": 50,
  "amount_currency": "USD",
  "operation": "purchase",
  "customer": "8c1a11c0-6ec6-4888-9e5c-8d07d7b5fed0",
  "merchant_initiated": false,
  "tokenize_card": true,
  "payment_type":"RECURRING",
  "recurring_data": {
    "agreement_id": "subscriptionX",
    "number_of_payments": 10,
    "days_between_payments": 30,
    "expiry_date": "2024-01-01"
  },
  "webhook_url": "https://example.com/webhook"
}

Request a payment in a subsequent MIT

After the customer has established a payment agreement, you can start subsequentMIT operations within the payment series. You will use this renewal operation when the customer has opted for automatic renewal after a subscription period.

For each successive MIT transaction, you need to inform the same agreement_id used in the initial transaction. In addition, the transaction amount must remain constant and mirror the amount specified in the initial transaction. It's important to note that the only acceptable operation in this context is a purchase transaction. Therefore, the MIT payment requests must include the following fields:

• "payment_type": "RECURRING"
• "merchant_initiated": true
• "agreement_id": <same as initial transaction>
• "amount: <same as initial transaction>"
• "operation: purchase"

The following JSON exemplifies the payload for this intent:

{
  "amount": 50,
  "amount_currency": "USD",
  "operation": "purchase",
  "customer": "8c1a11c0-6ec6-4888-9e5c-8d07d7b5fed0",
  "card_token": "10fbf790-bb27-4afa-87d9-4b57b2d3fb2b",
  "merchant_initiated": true,
  "payment_type":"RECURRING",
  "recurring_data": {
    "agreement_id": "subscriptionX",
  },
  "webhook_url": "https://example.com/webhook"
}

Unscheduled payments

Using an unscheduled payment agreement allows you to save a customer's card information during an initial transaction and then perform a transaction using the stored card information later. It differs from recurring payments because unscheduled payments don't consider a fixed number of days between each payment. The payments will depend on the product or service usage by the customer.

As an example of the usage of unscheduled payments, you can consider ride-hailing apps. In such a scenario, a customer may provide their card details to a ride-hailing app that automatically charges the card for rides taken without requiring the customer to authorize each transaction manually.

Initial transaction

To obtain permission for an unscheduled payment, the first transaction initiated by the cardholder (CIT), in which they establish the arrangement, must contain the following information in the request:

• "payment_type": "UNSCHEDULED"
• "merchant_initiated": false

You need to include the agreement_id of the payment agreement in the recurring_data object. It's used to identify the operation in future transactions. You may define this ID according to your preference.

The following JSON exemplifies the payload for this intent:

{
  "amount": 50,
  "amount_currency": "USD",
  "operation": "purchase",
  "customer": "8c1a11c0-6ec6-4888-9e5c-8d07d7b5fed0",
  "merchant_initiated": false,
  "tokenize_card": true,
  "payment_type":"UNSCHEDULED",
  "recurring_data": {
    "agreement_id": "UnscheduledX"
  },
  "webhook_url": "https://example.com/webhook"
}

The response to the request will create a normal intent, enabling your customer to perform the payment by providing their card details. The card details are saved for future subsequent transactions.

Request an unscheduled payment

After setting up an unscheduled payment agreement, you can request new payments later and perform MITs with your customer-stored card.

To create the MIT payment, you need to inform the same agreement_id of the Initial transaction in the recurring_data object. In addition, you need to inform the transaction as a purchase . In summary, the MIT payment requests must include:

• "payment_type": "UNSCHEDULED"
• "merchant_initiated": true
• "operation": "purchase"
• "agreement_id": <same as initial transaction>

The following JSON exemplifies the payload for this intent:

{
  "amount": 50,
  "amount_currency": "USD",
  "operation": "purchase",
  "customer": "8c1a11c0-6ec6-4888-9e5c-8d07d7b5fed0",
  "card_token": "10fbf790-bb27-4afa-87d9-4b57b2d3fb2b",
  "merchant_initiated": true,
  "payment_type":"UNSCHEDULED",
  "recurring_data": {
    "agreement_id": "UnscheduledX"
  },
  "webhook_url": "https://example.com/webhook"
}