Unscheduled merchant-initiated transactions

An unscheduled merchant-initiated transaction (MIT) lets you charge a saved card when the customer is not actively completing checkout. Use this flow when the timing or final amount cannot be determined in advance.

For example, you might collect an estimated amount when the customer places an order, perform additional checks, and later charge the difference if the final cost is higher.

The flow has two stages:

1. While the customer is present, create a managed order and save their card. You can verify the card without charging it or save it during the first payment.
2. After the amount is confirmed, initiate a charge against the active managed order with PATCH /order-rebill/{orderId}.

The initial customer-present transaction establishes the saved-card agreement. Each later charge uses the card associated with that managed order and does not require the card number or CVV again.

Tell the customer that their payment method will be saved and may be charged later without their active participation. Present this notice before they submit their card.

Your notice should clearly explain:

• Why the payment method is being saved.
• What may cause an additional charge.
• How the additional amount will be calculated.
• When and how the customer will be informed.
• How the customer can cancel the agreement or contact you about a charge.

For example:

By continuing, you authorize Example Merchant to securely save this payment method with xMoney and charge it for additional amounts identified during the checks described above. We will notify you of the final amount and any additional charge.

Set saveCard: true in the server-generated order payload to make the storage requirement explicit.

Use cardTransactionMode: verifyCard when no initial payment is required. The verification uses an amount of 0 and creates the managed order that you will charge later.

{
  "siteId": 10077,
  "customer": {
    "identifier": "customer-123",
    "email": "customer@example.com"
  },
  "order": {
    "orderId": "inspection-123",
    "type": "managed",
    "amount": 0,
    "currency": "EUR",
    "description": "Payment method verification"
  },
  "cardTransactionMode": "verifyCard",
  "saveCard": true,
  "backUrl": "https://merchant.example.com/payment-result"
}

The customer enters their card and completes any required 3D Secure authentication. Wait for a trusted server-side confirmation with transactionStatus: complete-ok before using the saved card.

{
  "transactionStatus": "complete-ok",
  "orderId": 1234,
  "transactionId": 5678,
  "cardId": 98765,
  "customerId": 1001
}

Store the returned orderId and cardId against the same customer. The order remains active so that you can initiate later charges.

For general tokenization details, see Save card without payment.

Use cardTransactionMode: authAndCapture when you collect an initial amount while the customer is present. The order must still use type: managed so that later merchant-triggered charges are classified correctly.

The following example charges an initial estimate of EUR 50:

{
  "siteId": 10077,
  "customer": {
    "identifier": "customer-123",
    "email": "customer@example.com"
  },
  "order": {
    "orderId": "inspection-124",
    "type": "managed",
    "amount": 50,
    "currency": "EUR",
    "description": "Initial estimated charge"
  },
  "cardTransactionMode": "authAndCapture",
  "saveCard": true,
  "backUrl": "https://merchant.example.com/payment-result"
}

After the initial transaction reaches complete-ok, retain the returned orderId and cardId. If the checks establish a final cost of EUR 65, charge only the EUR 15 difference in the later MIT.

For more information about tokenization during a payment, see Save card on payment.

Initiate the later charge from your backend:

curl -X PATCH "https://api.xmoney.com/order-rebill/1234" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "customerId=1001" \
  --data-urlencode "amount=15.00"

The order must:

• Have type: managed.
• Be active with an in-progress status.
• Belong to the supplied customer.
• Have a successfully saved card.

A successful response identifies the managed order and the new transaction:

{
  "code": 200,
  "message": "Success",
  "data": {
    "id": 1234,
    "transactionId": 6789,
    "cardId": 98765
  }
}

Confirm the final transaction state through the API response and your webhook processing before treating the additional amount as collected.

You can also create a new order with type: managed and the saved cardId. This creates a separate order and xMoney processes its saved-card charge as an unscheduled MIT.

Use PATCH /order-rebill/{orderId} when you want to keep the initial agreement and its later charges on one managed order. Use a new managed order only when each charge must have a separate order lifecycle.

A saved-card purchase is treated as a customer-initiated transaction. It does not become an MIT merely because the card was saved previously.

Use:

• managed for merchant-triggered charges with no fixed schedule.
• recurring for charges that xMoney automatically initiates on a defined schedule.
• purchase when the customer is actively initiating a one-off payment.

The initial verification or payment may require 3D Secure. Complete that customer-present flow before relying on the saved card.

A later MIT can still be declined or require action under issuer or regulatory rules. Do not automatically convert a failed MIT into a customer-initiated payment. Notify the customer and ask them to return to checkout when new authentication or a different payment method is required.

• Obtain clear customer agreement to save the card and make later variable charges.
• Create a managed order with saveCard: true.
• Use either verifyCard or authAndCapture while the customer is present.
• Activate the agreement only after a trusted complete-ok confirmation.
• Store the orderId, cardId, and customer association securely.
• Calculate and record the exact additional amount.
• Initiate the charge with PATCH /order-rebill/{orderId}.
• Reconcile the response and webhook before retrying or fulfilling the additional amount.