Set up the Agreement (CIT)

Use this request to create the agreement, store your customer's card, and send your customer to authenticate. Choose one of two options, depending on whether you take a payment at the same time.

Before you start

Ensure that you have:

Unscheduled card on file enabled for your outlet.
Your outlet reference from the N-Genius Portal.
An access token. See Request an access token.
A server endpoint at your return URL that can look up the order. You need it to receive the token — see Receive the stored-card token.
Your customer in session at checkout. They must be present to authenticate.

Request

Both options use POST. The resource and the media type depend on the option.

Option	Resource (sandbox)	Content-Type and Accept
A — verify and store the card	`https://api-gateway.sandbox.ngenius-payments.com/transactions/outlets/[your-outlet-reference]/orders`	`application/vnd.ni-payment.v2+json`
B — take a first payment and store the card	`https://api-gateway.sandbox.ngenius-payments.com/recurring-payment/outlets/[your-outlet-reference]/orders`	`application/vnd.ni-recurring-payment.v2+json`

Headers

Header	Value
Authorization	`Bearer [access-token]`
Content-Type	The media type for your option, from the table above
Accept	The same media type

Body attributes

Attribute	Required	Type	Description
`action`	Required	String	`VERIFY` stores the card without taking payment. `PURCHASE` takes a first payment at the same time
`type`	Required	String	Type of agreement. Send `UNSCHEDULED`
`channel`	Required	String	Payment channel. Send `Ecom`
`frequency`	Required	String	Interval between charges. Unscheduled agreements have none — send `ADHOC`
`amount.currencyCode`	Required	String	ISO 4217 currency code, for example `AED`
`amount.value`	Required	Integer	Amount in minor units. Send `0` when you only verify the card
`recurringDetails.recurringType`	Required	String	Whether charge amounts are fixed or vary. Send `VARIABLE`
`recurringDetails.startDate`	Conditional	String	ISO 8601 date and time the agreement starts. Appears in the `VERIFY` sample only
`recurringDetails.immediatePaymentAmount`	Conditional	Object	The amount to take now, with `currencyCode` and `value`. Send it when `action` is `PURCHASE`
`emailAddress`	Required	String	Your customer's email address
`merchantAttributes.redirectUrl`	Required	String	Where your customer returns after authenticating
`merchantAttributes.cancelUrl`	Required	String	Where your customer returns if they cancel

Option A — Verify and store the card

Use this when you save a card for later without charging anything now.

{
  "action": "VERIFY",
  "type": "UNSCHEDULED",
  "channel": "Ecom",
  "frequency": "ADHOC",
  "amount": {
    "currencyCode": "AED",
    "value": 0
  },
  "recurringDetails": {
    "recurringType": "VARIABLE",
    "startDate": "2026-09-07T11:00:00.000Z"
  },
  "emailAddress": "[email protected]",
  "merchantAttributes": {
    "redirectUrl": "https://merchant.example.com/checkout/complete",
    "cancelUrl": "https://merchant.example.com/checkout/cancel"
  }
}

Option B — Take a first payment and store the card

Use this when your customer pays for something now and agrees to future charges at the same time.

{
  "action": "PURCHASE",
  "type": "UNSCHEDULED",
  "channel": "Ecom",
  "frequency": "ADHOC",
  "amount": {
    "currencyCode": "AED",
    "value": 15000
  },
  "recurringDetails": {
    "recurringType": "VARIABLE",
    "immediatePaymentAmount": {
      "currencyCode": "AED",
      "value": 15000
    }
  },
  "emailAddress": "[email protected]",
  "merchantAttributes": {
    "redirectUrl": "https://merchant.example.com/checkout/complete",
    "cancelUrl": "https://merchant.example.com/checkout/cancel"
  }
}

Response

{
  "reference": "6338b5ac-26f1-4580-b736-7844f8315c3f",
  "action": "PURCHASE",
  "type": "UNSCHEDULED",
  "amount": {
    "currencyCode": "AED",
    "value": 15000
  },
  "paymentMethods": {
    "card": ["VISA", "MASTERCARD"]
  },
  "_links": {
    "payment": {
      "href": "https://paypage.ngenius-payments.com/?code=15d738dae5cd3dc0"
    },
    "self": {
      "href": "https://api-gateway.ngenius-payments.com/transactions/outlets/[your-outlet-reference]/orders/6338b5ac-26f1-4580-b736-7844f8315c3f"
    }
  },
  "_embedded": {
    "payment": [
      {
        "_id": "urn:payment:003843dc-a94a-4ff0-a151-d4414894f8d1",
        "reference": "003843dc-a94a-4ff0-a151-d4414894f8d1",
        "state": "STARTED"
      }
    ]
  }
}

Attribute	Description
`reference`	The order reference. Store it — you use it to look up the order and to charge against it later
`_links.payment.href`	The hosted payment page. Send your customer here to authenticate
`_embedded.payment[0].reference`	The payment reference, used for subsequent charges against this order
`_embedded.payment[0].state`	`STARTED` until your customer completes authentication

What to do next

Redirect your customer to _links.payment.href to complete 3-D Secure authentication. N-Genius Online then stores the card and returns the token — see Receive the stored-card token.

Common errors

What you see	What it usually means
The order stays in the `STARTED` state	Your customer has not finished authenticating, and no token is issued until they do. Treat an abandoned checkout as no agreement — do not charge the card later
An unsupported media type response	Your `Content-Type` or `Accept` header does not match the option you are using. Send both
The request is rejected before the payment page	Check that unscheduled card on file is enabled on the outlet, and that your access token was issued for the same outlet