With two stage payments, orders are first created, then supplied with payment information in two separate steps. This approach can be useful when you have received an order for goods/services, but need to collect payment at a later time or date.
If you plan to collect payment at the same time as creating the order, please refer to the One stage payments section instead.
Create an order
Now that an access token has been provided, we are now able to create orders in the N-Genius Online gateway. To accept a payment from a customer, an order is always required so that we have something to interact with in all our API interactions with the gateway, and on the Portal user interface.
HTTP Request Method: POST
Resource (URI): https://api-gateway.sandbox.ksa.ngenius-payments.com/transactions/outlets/[your-outlet-reference/orders
Headers:
Add these headers to your request (note that you should replace 'access_token' with the access token value we received from the Obtain an access token step).
| Header | Value |
|---|---|
| Authorization | Bearer [access_token] |
| Content-Type | application/vnd.ni-payment.v2+json |
| Accept | application/vnd.ni-payment.v2+json |
Body:
Add the following mandatory JSON information to the form/body content of your request.
| Parameter | Description | Example value |
|---|---|---|
| action | Order type | "AUTH", "PURCHASE" |
| amount { } | Amount block | N/A |
| amount.currencyCode | Order currency | "SAR" |
| amount.value | Order amount | 1000 (minor units) |
| emailAddress | Payer's email address | [email protected] |
| billingAddress { } | Billing address block | N/A |
| billingAddress.firstName | Payer's first name | mandatory |
| billingAddress.lastName | Payer's last/second name | mandatory |
Note: these are the mandatory minimum input parameters for creating an order using the N-Genius Online gateway APIs - many more values are available. Please consult the List of order input attributes section for a complete list of these parameters.
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):
{
"action": "PURCHASE",
"amount": {
"currencyCode": "SAR",
"value": 100
}
}
Example response (body):
{
"_id": "urn:order:76fb9d52-a3ef-42d3-8b4e-90092f57534c",
"_links": {
"cnp:payment-link": {
"href": "https://<<apiSandboxDomain>>/transactions/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/orders/76fb9d52-a3ef-42d3-8b4e-90092f57534c/payment-link"
},
"payment-authorization": {
"href": "https://<<apiSandboxDomain>>/transactions/paymentAuthorization"
},
"self": {
"href": "https://<<apiSandboxDomain>>/transactions/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/orders/76fb9d52-a3ef-42d3-8b4e-90092f57534c"
},
"tenant-brand": {
"href": "http://config-service/config/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/configs/tenant-brand"
},
"payment": {
"href": "https://<<paypageSandboxDomain>>/?code=8ad2daf8bc86d0a9"
},
"merchant-brand": {
"href": "http://config-service/config/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/configs/merchant-brand"
}
},
"action": "PURCHASE",
"amount": {
"currencyCode": "SAR",
"value": 1000
},
"language": "en",
"merchantAttributes": {
"redirectUrl": "https://yoursite.com"
},
"emailAddress": "",
"reference": "76fb9d52-a3ef-42d3-8b4e-90092f57534c",
"outletId": "5edab6d7-5946-43f4-b8c7-06b29c272bdd",
"createDateTime": "2019-04-17T08:15:18.912Z",
"paymentMethods": {
"card": [
"DINERS_CLUB_INTERNATIONAL",
"AMERICAN_EXPRESS",
"MASTERCARD",
"MASTERCARD",
"VISA",
"VISA"
],
"wallet": [
"APPLE_PAY",
"SAMSUNG_PAY"
]
},
"referrer": "urn:Ecom:76fb9d52-a3ef-42d3-8b4e-90092f57534c",
"formattedAmount": "د.إ. 10",
"formattedOrderSummary": {},
"_embedded": {
"payment": [
{
"_id": "urn:payment:2fff837f-9a39-4a02-8435-9aaa7cb6b558",
"_links": {
"payment:apple_pay": {
"href": "https://<<apiSandboxDomain>>/transactions/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/orders/76fb9d52-a3ef-42d3-8b4e-90092f57534c/payments/2fff837f-9a39-4a02-8435-9aaa7cb6b558/apple-pay"
},
"self": {
"href": "https://<<apiSandboxDomain>>/transactions/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/orders/76fb9d52-a3ef-42d3-8b4e-90092f57534c/payments/2fff837f-9a39-4a02-8435-9aaa7cb6b558"
},
"payment:card": {
"href": "https://<<apiSandboxDomain>>/transactions/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/orders/76fb9d52-a3ef-42d3-8b4e-90092f57534c/payments/2fff837f-9a39-4a02-8435-9aaa7cb6b558/card"
},
"payment:samsung_pay": {
"href": "https://<<apiSandboxDomain>>/transactions/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/orders/76fb9d52-a3ef-42d3-8b4e-90092f57534c/payments/2fff837f-9a39-4a02-8435-9aaa7cb6b558/samsung-pay"
},
"payment:saved-card": {
"href": "https://<<apiSandboxDomain>>/transactions/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/orders/76fb9d52-a3ef-42d3-8b4e-90092f57534c/payments/2fff837f-9a39-4a02-8435-9aaa7cb6b558/saved-card"
},
"curies": [
{
"name": "cnp",
"href": "https://<<apiSandboxDomain>>/docs/rels/{rel}",
"templated": true
}
]
},
"state": "STARTED",
"amount": {
"currencyCode": "AED",
"value": 1000
},
"updateDateTime": "2019-04-17T08:15:18.912Z",
"outletId": "5edab6d7-5946-43f4-b8c7-06b29c272bdd",
"orderReference": "76fb9d52-a3ef-42d3-8b4e-90092f57534c"
}
]
}
}
Submit payment card information
At this stage, it is expected that you be capturing the PAN, expiry date, card security code (CVV/CSC) of the payer’s card on your site/service.
The following method describes how these details will be passed to the N-Genius Online transaction service for insertion into the order we just created.
HTTP Request Method: PUT
Resource (URI): https://api-gateway.sandbox.ksa.ngenius-payments.com/transactions/outlets/[your-outlet-reference]/orders/[your-order-reference]/payments/[your-payment-reference]/card *
Constructing the card payment URL
The resource above need not be constructed yourself. Instead, once an order has been created, you can extract this from the order response (above) from the attribute below:
_embedded.payment[0]._links.[payment:card].href
Headers:
Add these headers to your request:
| Header | Value |
|---|---|
| Authorization | Bearer [access_token] |
| Content-Type | application/vnd.ni-payment.v2+json |
| Accept | application/vnd.ni-payment.v2+json |
Body:
Add the following JSON information to the form/body content of your request.
| Attribute | Description | Possible value(s) |
|---|---|---|
| pan | The PAN (longest number) on the card | 4111111111111111 |
| expiry | Card expiry date (YYYY-MM) | 2025-04 |
| cvv | The payment card’s security code | 123 |
| cardholderName | The name of the card-holder | John Brown |
Example request (body):
{
"pan": "4111111111111111",
"expiry": "2029-03",
"cvv": "123",
"cardholderName": "John Brown"
}
Example response (body):
{
"_id": "urn:payment:b9040ddd-3b2c-4873-8099-889815b37352",
"_links": {
"self": {
"href": "[self-urn]"
},
"curies": [
{
"name": "cnp",
"href": "https://<<apiDomain>>/docs/rels/{rel}",
"templated": true
}
]
},
"paymentMethod": {
"expiry": "2021-06",
"cardholderName": "John Brown",
"name": "VISA",
"pan": "411111******1111",
"cvv": "***"
},
"outletId": "94223ab2-5bb9-467f-a6a7-fc4b22c435af",
"orderReference": "ceb2dad7-ec1e-4ab2-9a3a-75f99d17a166",
"state": "AWAIT_3DS",
"amount": {
"currencyCode": "SAR",
"value": 100
},
"updateDateTime": "2019-02-05T10:15:18.810Z",
"authResponse": {
"authorizationCode": "1234567",
"success": true
}
}
Code example (PHP + cURL):
$postData = new StdClass();
$postData->pan = $pan;
$postData->expiry = $expiry;
$postData->cvv = $cvv;
$postData->cardholderName = $name;
$json = json_encode($postData);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $cardpay_url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer ".$token, "Content-Type: application/vnd.ni-payment.v2+json", "Accept: application/vnd.ni-payment.v2+json"));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
$output = json_decode(curl_exec($ch));
$state = $output->state;
if ($state == "AWAIT_3DS") {
$cnp3ds_url = $output->_links->{'cnp:3ds'}->href;
$acsurl = $output->{'3ds'}->acsUrl;
$acspareq = $output->{'3ds'}->acsPaReq;
$acsmd = $output->{'3ds'}->acsMd;
$acsterm = "https://[your-post-3ds-script]";
}
curl_close ($ch);
The 'state' attribute
The primary attribute of the response received (above) we should concern ourselves with is the state attribute, which determines what your next action should be in the card payment processing journey using N-Genius Online.
The possible values of the 'state' attribute are as follows:
| State | Description and next steps |
|---|---|
| STARTED | Order has been created |
| AUTHORISED | Authorization of the payment has been successful but you will need to capture the payment before funds will be transferred. |
| PURCHASED | The payment has been purchased successfully. No further action is required. This is the typical ‘state’ outcome for a payment made using the ‘PURCHASE’ action (see the order creation step). |
| CAPTURED | The payment has been authorized and captured successfully. No further action is required. This is the typical ‘state’ outcome for a payment made using the ‘AUTH’ action (see the order creation step). |
| AWAIT_3DS | A further step, to invoke and manage the 3DS 2.X process is required before an authorization attempt will be made. |
| FAILED | The payment has not been successful. You should ask the customer to retry using either the same payment card, or a different one. |
Fraud Screening
Please visit https://docs.ngenius-payments.com/docs/fraud-screening to learn more about the N-Genius fraud screening capabilities.
It is important, if you are registered for enhanced screening, that when a transaction is Fraud Checked with a status of rejected, you do not deliver the goods or services. To avoid card-holder impact, the Ngenius platform will automatically initiate an Authorization Reversal, to remove the shadow from the cardholders account and release their funds.