Wallet Merchant-Initiated Transactions (MIT)

📘 Sandbox examples The examples on this page use the NGO sandbox environment. Switch to production hosts and production credentials only after your integration is certified.

Overview

A merchant-initiated transaction (MIT) charges a payment method the customer has already authorized, without the customer taking action at the time of payment. Common uses include subscriptions, scheduled billing, and one-click checkout for returning customers.

Every MIT flow has three parts:

Initial customer-initiated transaction (CIT). The customer enters or confirms a card or wallet. NGO returns a saved card token.
Token storage. Your server stores the cardToken and masked card details against the customer's account.
MIT charge. Your server charges the stored token later, referencing the original CIT order and payment.

Apple Pay and Google Pay follow the same pattern. The wallet is used for the initial CIT, and the resulting token is used for later MITs. See Apple Pay and Google Pay.

Prerequisites

An NGO sandbox account with Pay-by-Token enabled. Without it, NGO does not return a savedCard block.
A sandbox API key.
Your outlet ID.
A server-side environment. Never call NGO APIs from a browser or mobile app, because the API key must stay on your server.

Environment

Environment	Base URL
Sandbox	`https://api-gateway.sandbox.ngenius-payments.com`

Authentication

Request an access token before you call any other endpoint.

POST /identity/auth/access-token

Header	Value
`Authorization`	`Basic {API_KEY}`
`Content-Type`	`application/vnd.ni-identity.v1+json`

Send the returned access_token as Authorization: Bearer {access_token} on all subsequent requests.

curl -X POST "https://api-gateway.sandbox.ngenius-payments.com/identity/auth/access-token" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/vnd.ni-identity.v1+json"

🚧
To confirm before publishing
The access token lifetime is not stated in the source collection. Document the expiry and whether to refresh on a 401 response.

Step 1: Create the order and save the card (CIT)

POST /transactions/outlets/{OUTLET_ID}/orders

Header	Value
`Authorization`	`Bearer {access_token}`
`Content-Type`	`application/vnd.ni-payment.v2+json`
`Accept`	`application/vnd.ni-payment.v2+json`

{
   "action": "AUTH",
   "language": "en",
   "merchantOrderReference": "Order00112112121",
   "amount": {
      "currencyCode": "AED",
      "value": 100
   },
   "savedCard": {
      "maskedPan": "401200******1112",
      "expiry": "2029-02",
      "cardholderName": "Sanjeev",
      "scheme": "VISA",
      "cardToken": "NTcxYWJkNWItZGU3Zi00MDBhLWE4OGMtNGI3YjQ5ZWY0YzU3",
      "recaptureCsc": true
   },
   "merchantAttributes": {
      "skip3DS": false,
      "skipConfirmationPage": false,
      "redirectUrl": "https://www.google.com"
   },
   "emailAddress": "[email protected]",
   "billingAddress": {
      "firstname": "Sanjeev",
      "lastname": "KM",
      "countryCode": "US",
      "address1": "Dubai",
      "city": "Dubai"
   },
   "merchantDefinedData": {
      "merchantOrderReference_verify": "Order0011212",
      "Outlet location": "test",
      "Sub-order4": "002323-004",
      "PRO": "test0001"
   }
}

Response

The saved card token is returned at _embedded.payment.savedCard. Store these fields:

Field	Description
`cardToken`	Base64 token that represents the card (PAN alias). Use this for future MITs.
`maskedPan`	BIN and last four digits of the card. Safe to display.
`scheme`	Card scheme, such as `VISA`, `MASTERCARD`, `AMERICAN_EXPRESS`, or `DINERS_CLUB_INTERNATIONAL`.
`recaptureCsc`	If `true`, the security code must be captured again on the pay page for future payments.

Save the order ID (orderID) and payment ID (paymentID) from the response. You need both in the steps below.

📘
Never store the full card number
Store only cardToken, maskedPan, scheme, and expiry. Do not log or persist raw card data.

Step 2: Attach the saved card to the payment

PUT /transactions/outlets/{OUTLET_ID}/orders/{orderID}/payments/{paymentID}/saved-card

Header	Value
`Authorization`	`Bearer {access_token}`
`Content-Type`	`application/vnd.ni-payment.v2+json`
`Accept`	`application/vnd.ni-payment.v2+json`

{
   "maskedPan": "230377******0275",
   "expiry": "2029-01",
   "cardholderName": "Sanjeev",
   "scheme": "MASTERCARD",
   "cardToken": "ZjY2ZDZkYTEtZWUyMS00ZTUzLWJiMDgtYjllMDdkOGQwYmU1",
   "recaptureCsc": true
}

🚧
To confirm before publishing
The source collection does not include a response example for this call. Document the success response and whether the call is required for every saved-card flow.

Step 3: Charge the stored card (MIT)

PUT /transactions/outlets/{OUTLET_ID}/payment/card