The single stage payment integration type allows you to create an order and submit card payment information to N-Genius Online, at the same time, without mandating multiple calls to the transaction APIs for the initial payment request.
This method of collecting payment is the most common variant of this integration type. However, should you wish to collect payment _after _first creating an order, or if you are providing token data instead of card data to make payment, please refer to the Two stage payments section instead.
HTTP Request Method: POST
Resource (URI): https://api-gateway.sandbox.ngenius-payments.com/transactions/outlets/[your-outlet-reference]/payment/card
Headers:
| Header | Value |
|---|---|
| Authorization | Bearer [access_token] |
| Content-Type | application/vnd.ni-payment.v2+json |
| Accept | application/vnd.ni-payment.v2+json |
Body:
| Attribute | Description | Example value(s) |
|---|---|---|
| order { } | Order data block | N/A |
| order.action | Order type (see “AUTH OR PURCHASE”) | “AUTH”, “SALE”, "PURCHASE" |
| order.amount { } | Order amount data block | N/A |
| order.amount.currencyCode | Order currency | “AED”, “USD”, “EUR”, etc. |
| order.amount.value | Order amount in minor units | 10.00 = “1000” (minor units) |
| payment { } | Payment data block | N/A |
| payment.pan | Card PAN | 4111111111111111 |
| payment.expiry | Card expiry date | 2025-04 |
| payment.cvv | Card security code | 123 |
| payment.cardholderName | Cardholder name | John Brown |
Note: the mandatory/minimum input parameters for successful creation of an order are detailed in the table above, but far more parameters are available. For more information on these, see the List of order input attributes section.
AUTH or PURCHASE?
Orders created with the ‘PURCHASE’ action will, if successfully authorized, automatically and immediately attempt to capture/settle the full order amount, whereas orders created with the ‘AUTH’ action will await some further action from instructing N-Genius Online to capture/settle the funds.
Unless you are ready to ship your goods/services immediately, or you are selling digital content, we recommend you use the ‘AUTH’ action and capture your customers’ successful authorizations when you are ready to ship the goods to your customer.
Example request (body):
{
"order": {
"action":"PURCHASE",
"amount":{ "currencyCode":"AED", "value":100 }
},
"payment":{
"pan":"4111111111111111",
"expiry":"2025-04",
"cvv":"123",
"cardholderName":"John Brown"
}
}
Example response (body):
{
"_id": "urn:payment:39427d1d-2ddf-4e58-a96d-2d91313cde22",
"_links": {
"cnp:3ds2-challenge-response": {
"href": "https://api-gateway.sandbox.ngenius-payments.com/transactions/outlets/670bfc06-63d6-472b-af75-ad0207ac44f5/orders/f414949b-933c-4d3d-ab83-f654855f4b04/payments/39427d1d-2ddf-4e58-a96d-2d91313cde22/card/3ds2/challenge-response"
},
"self": {
"href": "https://api-gateway.sandbox.ngenius-payments.com/transactions/outlets/670bfc06-63d6-472b-af75-ad0207ac44f5/orders/f414949b-933c-4d3d-ab83-f654855f4b04/payments/39427d1d-2ddf-4e58-a96d-2d91313cde22"
},
"cnp:3ds2-authentication": {
"href": "https://api-gateway.sandbox.ngenius-payments.com/transactions/outlets/670bfc06-63d6-472b-af75-ad0207ac44f5/orders/f414949b-933c-4d3d-ab83-f654855f4b04/payments/39427d1d-2ddf-4e58-a96d-2d91313cde22/card/3ds2/authentications"
},
"cnp:3ds": {
"href": "https://api-gateway.sandbox.ngenius-payments.com/transactions/outlets/670bfc06-63d6-472b-af75-ad0207ac44f5/orders/f414949b-933c-4d3d-ab83-f654855f4b04/payments/39427d1d-2ddf-4e58-a96d-2d91313cde22/card/3ds"
},
"curies": [
{
"name": "cnp",
"href": "https://api-gateway.sandbox.ngenius-payments.com/docs/rels/{rel}",
"templated": true
}
]
},
"reference": "39427d1d-2ddf-4e58-a96d-2d91313cde22",
"paymentMethod": {
"expiry": "2029-01",
"cardholderName": "Marna Ross",
"name": "VISA",
"pan": "411111******1111",
"cvv": "***"
},
"state": "AWAIT_3DS",
"amount": {
"currencyCode": "AED",
"value": 329
},
"updateDateTime": "2025-04-11T10:10:44.626581219Z",
"outletId": "670bfc06-63d6-472b-af75-ad0207ac44f5",
"orderReference": "f414949b-933c-4d3d-ab83-f654855f4b04",
"authenticationCode": "c04c123b38406056",
"originIp": "41.114.148.56",
"3ds2": {
"messageVersion": "2.1.0",
"threeDSMethodURL": "https://paypage-uat.ngenius-payments.com/fake/3ds2/method",
"threeDSServerTransID": "d220570f-def0-4a59-9888-e7479c49d4a7",
"directoryServerID": "M000000004"
},
"mid": "10089865858"
}
🔐 3DS2 Authentication for One-Stage Payments
When your integration triggers a 3-D Secure (3DS2) challenge, the process closely mirrors what’s used for Two-Stage Payments. To streamline your implementation, we’ve created a dedicated recipe that guides you through each step—from authentication to challenge response—using our One-Stage Payments flow.
Use the steps below to complete the 3DS2 authentication with ease, and ensure your transactions remain secure, seamless, and EMV-compliant.