Process an Order with Settlement
By default, an order made through the Hosted Payments API is a purchase in which the authorization and settlement are combined in the same transaction. However, your business model might require you to first authorize a transaction and then to settle it at a later date, e.g., once you have shipped goods. In this case, you send two separate requests to the API.
Process an Authorize-only Order
To process an authorize-only order you use the standard /orders endpoint, but the request body contains an extendedOptions array specifying that the request is authorization-only.
POST /hosted/v1/orders
Request example
curl -X POST -H "Content-Type: application/json" \
-u jTxL2wsNysJ8Jzmpdwim:NAA043a7c53c66ac3826c5e \
https://api.test.netbanx.com/hosted/v1/orders \
-d '{
"merchantRefNum" : "ABCDE12345",
"currencyCode" : "GBP",
"totalAmount" : 1000,
"extendedOptions" : [
{
"key" : "authType",
"value" : "auth"
}]
}'
Response examples
A successful request will result in a response similar to the following:
{
"currencyCode" : "GBP",
"id" : "25TWPTLHRR81AIG1LF",
"link" : [
{
"rel" : "hosted_payment",
"uri" : "https://api.test.netbanx.com/hosted/v1/payment/53616c7465645f5fc96311a769ed171ce70fac1483fa7f6d9ecfb6d427c1e12c6fc573a35f13e0ea"
},
{
"rel" : "self",
"uri" : "https://jTxL2wsNysJ8Jzmpdwim:NAA043a7c53c66ac3826c5e@api.test.netbanx.com/hosted/v1/orders/25TWPTLHRR81AIG1LF"
}
],
"merchantRefNum" : "ABCDE12345",
"mode" : "live",
"totalAmount" : 1000,
"type" : "order"
}
Your system should take the hosted_payment URL from the order response and use it to redirect your customer to the hosted payment page, where they can enter payment details.
NOTE: The customer must complete and submit the payment details form before the order can be settled. You can use one of the test card numbers, such as 4530910000012345, to complete this step.
If you look up the order, you will get a response with the following structure, which indicates that it is an authorization-only transaction, as indicated by the transaction authType being auth:
{
"link" : [
{
"rel" : "hosted_payment",
"uri" : "https://api.test.netbanx.com/hosted/v1/payment/53616c7465645f5ffeb47c2287dbf903bbb4627b16929a27b8d09b37db190a0f6ce44f8ea1461be2"
},
{
"rel" : "self",
"uri" : "https://jTxL2wsNysJ8Jzmpdwim:NAA043a7c53c66ac3826c5e@api.test.netbanx.com/hosted/v1/orders/25TWPTLHRR81AIG1LF"
}
],
"currencyCode" : "GBP",
"transaction" : {
"status" : "pending",
"lastUpdate" : "2012-05-14T15:12:18",
"authType" : "auth",
"merchantRefNum" : "ABCDE12345",
"associatedTransactions" : [],
"currencyCode" : "GBP",
"refunded" : false,
"amount" : 1000,
"paymentType" : "card",
"settled" : false
},
"totalAmount" : 1000,
"id" : "25TWPTLHRR81AIG1LF",
"merchantRefNum" : "ABCDE12345"
}
See our API Reference section for a list of all the JSON attributes and types available for the order object. Request and response parameters are listed.
Settle an Authorize-only Order
POST /hosted/v1/orders/order_id/settlement
Once you have provided the goods or services, you can settle the authorization.
To settle an authorization, use the order ID received in the order response (25TWPTLHRR81AIG1LF in this example) and POST a settlement request to the endpoint described below.
- If you omit the amount parameter, the full amount of the authorization will be settled.
- If you include the amount parameter, you can specify how much of the authorization to settle.
Request example
curl -X POST \
-H "Content-Type: application/json" \
-u jTxL2wsNysJ8Jzmpdwim:NAA043a7c53c66ac3826c5e \
https://api.test.netbanx.com/hosted/v1/orders/25TWPTLHRR81AIG1LF/settlement \
-d '{ "amount": 500, "merchantRefNum": "ABCDE12345" }'
Assuming your settlement request is valid, you will get a response with the following structure, indicating that the settlement request has been successfully processed:
Response example
{
"currencyCode" : "GBP",
"id" : "25TWPTLHRR81AIG1LF",
"merchantRefNum" : "ABCDE12345",
"mode" : "live",
"totalAmount" : 500,
"authType" : "settlement"
}
Optional Order Features
You can optionally add the following features to an order using Order object parameters:
- Customer Email Notifications
- Merchant Email Notifications
- Localization
Customer email notifications
Customer email notifications offer full localization and customization; please contact Merchant Services for more details.
To send a notification email to the customer, pass a customerNotificationEmail parameter during the order creation step as follows:
{
"customerNotificationEmail" : "jane.smythe@emailhost.com"
}
To avoid sending a customer notification email, send the extendedOption field suppressCustomerEmail with the value true.
Merchant email notifications
To send a notification email to the merchant, pass a merchantNotificationEmail parameter during the order creation step as follows:
{
"merchantNotificationEmail" : "merchant@emailhost.com"
}
Localization
The Hosted Payments API supports the localization of pages and emails containing payment and receipt information. The system attempts a best-match to the information in the locale parameter.
NOTE: If the locale parameter is not passed, or an unsupported ISO 639-1 code is sent to the API, the default value in the merchant’s integration configuration is used.
To add localization information to the order, pass the locale parameter as follows:
{
"locale" : "en_GB"
}
The following locale parameter values are supported:
- en_US
- en_GB
- fr_FR
- fr_CA