Recurring Payments

With MoneyHash you can charge a customer's stored card without them being present - a subscription renewal, a ride fare, a usage-based top-up. These are merchant-initiated transactions (MIT), and there are two flavours: Recurring, for charges on a fixed schedule, and Unscheduled, for charges triggered by usage rather than a calendar.

Both follow the same two-step shape. The customer is present for exactly one transaction - the customer-initiated transaction (CIT) - where they enter their card and authorize you to store it under an agreement. Every charge after that is an MIT: you trigger it from your backend, the customer is not involved, and no 3D Secure challenge is shown. This page covers that flow end to end: which payment_type to send, how the CIT and MIT requests differ, what recurring_data carries, and what to check when a charge is rejected.

When to use it

Four options solve overlapping problems here, and picking the wrong one is the most common mistake teams make. Work down this before writing any code:

Before you start

Every agreement needs two things to exist first:

1. A Customer record. Create one via the Customer API and keep its customer_id - the same customer goes on the CIT and on every MIT in the agreement.
2. A tokenized card, produced by the CIT itself. You do not tokenize separately beforehand - the CIT tokenizes the card as part of the first charge. See Tokenize Cards for how tokenize_card, show_save_card_checkbox and show_mandatory_save_card_checkbox differ.

Provider support is the other prerequisite, and the one most likely to bite:

How the CIT to MIT flow works

One CIT, then any number of MITs, all tied together by an agreement_id you generate and control:

The requests and webhooks in full:

Every request below goes to the same endpoint:

The recurring_data object

Fields required on every request

Recurring or Unscheduled?

Same endpoint, same two-step shape. What differs is the trigger, whether the amount may move, and whether recurring_data carries a schedule:

Step by step: Recurring payments

Use this when the amount and cadence are fixed and known upfront - a membership fee, a fixed-term installment.

Step 1 - CIT: create the agreement

The customer is present, enters full card details, and authorizes the agreement. Include tokenize_card: true so the card is saved for the MITs that follow.

curl --request POST \
  --url https://web.moneyhash.io/api/v1.4/payments/intent/ \
  --header 'Authorization: Token <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 50,
    "amount_currency": "USD",
    "operation": "purchase",
    "customer": "<CUSTOMER_ID>",
    "merchant_initiated": false,
    "tokenize_card": true,
    "payment_type": "RECURRING",
    "recurring_data": {
      "agreement_id": "<YOUR_AGREEMENT_ID>",
      "number_of_payments": 10,
      "days_between_payments": 30,
      "expiry_date": "2027-01-01"
    },
    "webhook_url": "https://your-server.com/webhooks/moneyhash"
  }'

When transaction.purchase.successful fires, store the card_token, the customer_id and the agreement_id - you need all three for every MIT.

Step 2 - MIT: charge the agreement

Repeat this on your own schedule, for example a cron job on the 1st of each month. No customer interaction, no CVV, no 3DS.

curl --request POST \
  --url https://web.moneyhash.io/api/v1.4/payments/intent/ \
  --header 'Authorization: Token <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 50,
    "amount_currency": "USD",
    "operation": "purchase",
    "customer": "<CUSTOMER_ID>",
    "card_token": "<CARD_TOKEN_ID>",
    "merchant_initiated": true,
    "payment_type": "RECURRING",
    "recurring_data": {
      "agreement_id": "<YOUR_AGREEMENT_ID>"
    },
    "webhook_url": "https://your-server.com/webhooks/moneyhash"
  }'

Step by step: Unscheduled payments

Use this when charges are triggered by usage rather than a calendar - a ride-hailing app charging for a completed ride, a wallet that tops itself up when the balance runs low.

Step 1 - CIT: create the agreement

Functionally identical to the Recurring CIT, except payment_type is UNSCHEDULED and recurring_data needs only agreement_id - there is no schedule to describe.

curl --request POST \
  --url https://web.moneyhash.io/api/v1.4/payments/intent/ \
  --header 'Authorization: Token <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 12.50,
    "amount_currency": "USD",
    "operation": "purchase",
    "customer": "<CUSTOMER_ID>",
    "merchant_initiated": false,
    "tokenize_card": true,
    "payment_type": "UNSCHEDULED",
    "recurring_data": {
      "agreement_id": "<YOUR_AGREEMENT_ID>"
    },
    "webhook_url": "https://your-server.com/webhooks/moneyhash"
  }'

Step 2 - MIT: charge on usage

Trigger this whenever the billable event happens. The amount can differ from the CIT and from one MIT to the next.

curl --request POST \
  --url https://web.moneyhash.io/api/v1.4/payments/intent/ \
  --header 'Authorization: Token <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 18.75,
    "amount_currency": "USD",
    "operation": "purchase",
    "customer": "<CUSTOMER_ID>",
    "card_token": "<CARD_TOKEN_ID>",
    "merchant_initiated": true,
    "payment_type": "UNSCHEDULED",
    "recurring_data": {
      "agreement_id": "<YOUR_AGREEMENT_ID>"
    },
    "webhook_url": "https://your-server.com/webhooks/moneyhash"
  }'

Confirming the charge

Both flavours report status the same way - by webhook, not in the synchronous API response. Check type and intent.payment_status.status exactly as you would for any payment (see Create a Payment):

{
  "type": "transaction.purchase.successful",
  "intent": {
    "id": "<INTENT_ID>",
    "payment_status": { "status": "CAPTURED" }
  },
  "transaction": {
    "id": "<TRANSACTION_ID>",
    "status": "purchase.successful"
  }
}

Common errors and troubleshooting