Accept online payments with Hosted Payment Elements

http POST {{baseURL}}/v1.4/PaymentTransactionManagement/InitializeSession \
  Content-Type:application/json \
  X-CompanyNumber:{{Company Number}} \
  X-StoreNumber:{{Store Number}} \
  X-ReferenceId:{{$guid}} \
  X-Client-Application-Name:{{Client Application Name}} \
  X-Client-Application-Version:{{Client Application Name Version}} \
  X-Signature:{{GeneratedSignature}} \
  Amount:=59.99 \
  ReturnMethod=Redirect \
  ReturnURL=https://merchant.example.com/payment-return \
  FrameHostingURL=https://merchant.example.com \
  RequestExpirationUTC=2026-06-30T12:35:00.000Z \
  TokenRetrievalRequired:=true \
  AccountAddressCollectionMode=Full \
  ValidateAccountSecurityCode:=true \
  ValidateAccountAddress:=true

import requests

url = "{{baseURL}}/v1.4/PaymentTransactionManagement/InitializeSession"
headers = {
  "Content-Type": "application/json",
  "X-CompanyNumber": "{{Company Number}}",
  "X-StoreNumber": "{{Store Number}}",
  "X-ReferenceId": "{{$guid}}",
  "X-Client-Application-Name": "{{Client Application Name}}",
  "X-Client-Application-Version": "{{Client Application Name Version}}",
  "X-Signature": "{{GeneratedSignature}}"
}
payload = {
  "Amount": 59.99,
  "ReturnMethod": "Redirect",
  "ReturnURL": "https://merchant.example.com/payment-return",
  "FrameHostingURL": "https://merchant.example.com",
  "RequestExpirationUTC": "2026-06-30T12:35:00.000Z",
  "TokenRetrievalRequired": True,
  "AccountAddressCollectionMode": "Full",
  "ValidateAccountSecurityCode": True,
  "ValidateAccountAddress": True
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
print(response.status_code)
print(response.text)

using var client = new HttpClient();
using var req = new HttpRequestMessage(HttpMethod.Post,
    "{{baseURL}}/v1.4/PaymentTransactionManagement/InitializeSession");

req.Headers.TryAddWithoutValidation("X-CompanyNumber", "{{Company Number}}");
req.Headers.TryAddWithoutValidation("X-StoreNumber", "{{Store Number}}");
req.Headers.TryAddWithoutValidation("X-ReferenceId", "{{$guid}}");
req.Headers.TryAddWithoutValidation("X-Client-Application-Name", "{{Client Application Name}}");
req.Headers.TryAddWithoutValidation("X-Client-Application-Version", "{{Client Application Name Version}}");
req.Headers.TryAddWithoutValidation("X-Signature", "{{GeneratedSignature}}");

req.Content = new StringContent("{\"Amount\":59.99,\"ReturnMethod\":\"Redirect\",\"ReturnURL\":\"https://merchant.example.com/payment-return\",\"FrameHostingURL\":\"https://merchant.example.com\",\"RequestExpirationUTC\":\"2026-06-30T12:35:00.000Z\",\"TokenRetrievalRequired\":true,\"AccountAddressCollectionMode\":\"Full\",\"ValidateAccountSecurityCode\":true,\"ValidateAccountAddress\":true}", Encoding.UTF8, "application/json");

var res = await client.SendAsync(req);
Console.WriteLine((int)res.StatusCode);
Console.WriteLine(await res.Content.ReadAsStringAsync());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("{{baseURL}}/v1.4/PaymentTransactionManagement/InitializeSession"))
  .header("Content-Type", "application/json")
  .header("X-CompanyNumber", "{{Company Number}}")
  .header("X-StoreNumber", "{{Store Number}}")
  .header("X-ReferenceId", "{{$guid}}")
  .header("X-Client-Application-Name", "{{Client Application Name}}")
  .header("X-Client-Application-Version", "{{Client Application Name Version}}")
  .header("X-Signature", "{{GeneratedSignature}}")
  .POST(HttpRequest.BodyPublishers.ofString("{\"Amount\":59.99,\"ReturnMethod\":\"Redirect\",\"ReturnURL\":\"https://merchant.example.com/payment-return\",\"FrameHostingURL\":\"https://merchant.example.com\",\"RequestExpirationUTC\":\"2026-06-30T12:35:00.000Z\",\"TokenRetrievalRequired\":true,\"AccountAddressCollectionMode\":\"Full\",\"ValidateAccountSecurityCode\":true,\"ValidateAccountAddress\":true}"))
  .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());

<InitializeSessionRequest>
  <Amount>59.99</Amount>
  <ReturnMethod>Redirect</ReturnMethod>
  <ReturnURL>https://merchant.example.com/payment-return</ReturnURL>
  <FrameHostingURL>https://merchant.example.com</FrameHostingURL>
  <RequestExpirationUTC>2026-06-30T12:35:00.000Z</RequestExpirationUTC>
  <TokenRetrievalRequired>true</TokenRetrievalRequired>
  <AccountAddressCollectionMode>Full</AccountAddressCollectionMode>
  <ValidateAccountSecurityCode>true</ValidateAccountSecurityCode>
  <ValidateAccountAddress>true</ValidateAccountAddress>
</InitializeSessionRequest>

<Responses>
  <Status code="200">
    <InitializeSessionResponse>
      <SessionId>45016f4cce57e5ab4e308a1822b9b9fc3336</SessionId>
      <RequestURL>https://.../WebEPS/HPP?session=45016f4cce57e5ab4e308a1822b9b9fc3336</RequestURL>
    </InitializeSessionResponse>
  </Status>
  <Status code="400">
    <Error>
      <Code>INVALID_REQUEST</Code>
      <Message>Request body or headers are invalid.</Message>
      <Details>Verify required fields and signature payload.</Details>
    </Error>
  </Status>
  <Status code="401">
    <Error>
      <Code>UNAUTHORIZED</Code>
      <Message>Authentication failed.</Message>
      <Details>Invalid company/store credentials, signature, or allowed origin setup.</Details>
    </Error>
  </Status>
</Responses>

http POST {{baseURL}}/v1.4/PaymentTransactionManagement/CompleteSession \
  Content-Type:application/json \
  X-CompanyNumber:{{Company Number}} \
  X-StoreNumber:{{Store Number}} \
  X-ReferenceId:{{$guid}} \
  X-Signature:{{GeneratedSignature}} \
  SessionId={{CompleteSession}} \
  RequestExpirationUTC=2026-06-30T12:35:00.000Z

import requests

url = "{{baseURL}}/v1.4/PaymentTransactionManagement/CompleteSession"
headers = {
  "Content-Type": "application/json",
  "X-CompanyNumber": "{{Company Number}}",
  "X-StoreNumber": "{{Store Number}}",
  "X-ReferenceId": "{{$guid}}",
  "X-Signature": "{{GeneratedSignature}}"
}
payload = {
  "SessionId": "{{CompleteSession}}",
  "RequestExpirationUTC": "2026-06-30T12:35:00.000Z"
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
print(response.status_code)
print(response.text)

using var client = new HttpClient();
using var req = new HttpRequestMessage(HttpMethod.Post,
    "{{baseURL}}/v1.4/PaymentTransactionManagement/CompleteSession");

req.Headers.TryAddWithoutValidation("X-CompanyNumber", "{{Company Number}}");
req.Headers.TryAddWithoutValidation("X-StoreNumber", "{{Store Number}}");
req.Headers.TryAddWithoutValidation("X-ReferenceId", "{{$guid}}");
req.Headers.TryAddWithoutValidation("X-Signature", "{{GeneratedSignature}}");

req.Content = new StringContent("{\"SessionId\":\"{{CompleteSession}}\",\"RequestExpirationUTC\":\"2026-06-30T12:35:00.000Z\"}", Encoding.UTF8, "application/json");

var res = await client.SendAsync(req);
Console.WriteLine((int)res.StatusCode);
Console.WriteLine(await res.Content.ReadAsStringAsync());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("{{baseURL}}/v1.4/PaymentTransactionManagement/CompleteSession"))
  .header("Content-Type", "application/json")
  .header("X-CompanyNumber", "{{Company Number}}")
  .header("X-StoreNumber", "{{Store Number}}")
  .header("X-ReferenceId", "{{$guid}}")
  .header("X-Signature", "{{GeneratedSignature}}")
  .POST(HttpRequest.BodyPublishers.ofString("{\"SessionId\":\"{{CompleteSession}}\",\"RequestExpirationUTC\":\"2026-06-30T12:35:00.000Z\"}"))
  .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());

<CompleteSessionRequest>
  <SessionId>{{CompleteSession}}</SessionId>
  <RequestExpirationUTC>2026-06-30T12:35:00.000Z</RequestExpirationUTC>
</CompleteSessionRequest>

<Responses>
  <Status code="200">
    <CompleteSessionResponse>
      <TransactionStatus>Approved</TransactionStatus>
      <AuthorizationCode>A12345</AuthorizationCode>
      <ReferenceNumber>{{ReferenceNumber}}</ReferenceNumber>
    </CompleteSessionResponse>
  </Status>
  <Status code="400">
    <Error>
      <Code>INVALID_REQUEST</Code>
      <Message>SessionId is missing or invalid.</Message>
      <Details>Verify request payload and expiration timestamp.</Details>
    </Error>
  </Status>
  <Status code="401">
    <Error>
      <Code>UNAUTHORIZED</Code>
      <Message>Authentication failed.</Message>
      <Details>Invalid signature or merchant credentials.</Details>
    </Error>
  </Status>
</Responses>

// Node.js / Express — server-side
const https = require('https');
const fs    = require('fs');
const CERT  = fs.readFileSync('/certs/merchant_id.pem');
const KEY   = fs.readFileSync('/certs/merchant_id.key');

app.post('/your-backend/validate-apple-pay-merchant', (req, res) => {
  const { validationURL } = req.body;
  const payload = JSON.stringify({
    merchantIdentifier: 'merchant.com.your-company.shop',
    domainName:         req.hostname,    // must match the domain the shopper is on
    displayName:        'Your Store Name'
  });
  const url      = new URL(validationURL);
  const appleReq = https.request({
    hostname: url.hostname, path: url.pathname + url.search, method: 'POST',
    cert: CERT, key: KEY,
    headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) }
  }, r => { let b = ''; r.on('data', c => b += c); r.on('end', () => res.json(JSON.parse(b))); });
  appleReq.on('error', e => res.status(500).json({ error: e.message }));
  appleReq.end(payload);
});

# Python / Flask — server-side
import requests
from flask import request, jsonify

CERT = '/certs/merchant_id.pem'
KEY  = '/certs/merchant_id.key'

@app.route('/your-backend/validate-apple-pay-merchant', methods=['POST'])
def validate_merchant():
    validation_url = request.json['validationURL']
    payload = {
        'merchantIdentifier': 'merchant.com.your-company.shop',
        'domainName':         request.host,   # must match the shopper's domain
        'displayName':        'Your Store Name'
    }
    r = requests.post(validation_url, json=payload, cert=(CERT, KEY))  # mTLS
    r.raise_for_status()
    return jsonify(r.json())   # return Apple's session object unmodified

# Python / Flask — server-side
@app.route('/your-backend/process-apple-pay-payment', methods=['POST'])
def process_apple_pay():
    payment = request.json['payment']

    # POST to NCR Payment Capture API with session headers
    headers = {
        'Content-Type': 'application/json',
        'X-SessionId': session_id,                   # from InitializeExternalSession
        'X-Company': company_id,
        'X-UniqueTransactionIdentifier': unique_tx_id
    }
    payload = {
        'paymentType': { 'sourceType': 'APPLEPAY' },
        'sources': [{
            'sourceType': 'APPLEPAY',
            'encryptionData': {
                'encryptionType': 'RSA',
                'encryptionTarget': 'WEB',
                'encryptionBlock': json.dumps(payment)  # full payment object as string
            }
        }]
    }
    resp = requests.post(
        f'{NCR_BASE_URL}/Ecommerce/SecurePay/Payment/Capture',
        json=payload, headers=headers
    )
    resp.raise_for_status()
    result = resp.json()

    if result.get('success') and result.get('data', {}).get('statusCode') == 100:
        # Call CompleteSession to finalise the transaction
        complete_session(session_id)
        return jsonify({ 'success': True })
    return jsonify({ 'success': False, 'message': 'Capture failed' })

# Python / Flask — server-side
@app.route('/your-backend/process-google-pay-payment', methods=['POST'])
def process_google_pay():
    payment_data = request.json['paymentData']

    # Extract the encrypted token from the Google Pay payload
    token = payment_data['paymentMethodData']['tokenizationData']['token']

    # POST to NCR Payment Capture API with session headers
    headers = {
        'Content-Type': 'application/json',
        'X-SessionId': session_id,                   # from InitializeExternalSession
        'X-Company': company_id,
        'X-UniqueTransactionIdentifier': unique_tx_id
    }
    payload = {
        'paymentType': { 'sourceType': 'GOOGLEPAY' },
        'sources': [{
            'sourceType': 'GOOGLEPAY',
            'encryptionData': {
                'encryptionType': 'RSA',
                'encryptionTarget': 'WEB',
                'encryptionBlock': json.dumps(token)  # tokenizationData.token as string
            }
        }]
    }
    resp = requests.post(
        f'{NCR_BASE_URL}/Ecommerce/SecurePay/Payment/Capture',
        json=payload, headers=headers
    )
    resp.raise_for_status()
    result = resp.json()

    if result.get('success') and result.get('data', {}).get('statusCode') == 100:
        # Call CompleteSession to finalise the transaction
        complete_session(session_id)
        return jsonify({ 'success': True })
    return jsonify({ 'success': False, 'message': 'Capture failed' })

{
  "paymentType": {
    "sourceType": "GOOGLEPAY"
  },
  "sources": [{
    "sourceType": "GOOGLEPAY",
    "encryptionData": {
      "encryptionType": "RSA",
      "encryptionTarget": "WEB",
      "encryptionBlock": "<stringified Google Pay token>"
    }
  }]
}

// encryptionBlock: JSON.stringify(paymentData.paymentMethodData.tokenizationData.token)
// where 'paymentData' is the object from onGooglePayPaymentAuthorized

400 Invalid encryption data   — wallet token is missing or malformed
401 Session expired           — session is no longer valid; re-initialise
403 Merchant not authorised   — wallet not enabled or configured for this account
404 Session ID not found      — session or endpoint is invalid
500 Internal server error     — general error; contact NCR support

http POST {{baseURL}}/v1.4/ReversalAdministration/ReverseTransaction \
  Content-Type:application/json \
  X-CompanyNumber:{{Company Number}} \
  X-StoreNumber:{{Store Number}} \
  X-ReferenceId:{{$guid}} \
  X-Signature:{{GeneratedSignature}} \
  OriginalReferenceId={{OriginalReferenceId}} \
  ReversalType=timeout \
  RequestExpirationUTC=2026-06-30T12:35:00.000Z

import requests

url = "{{baseURL}}/v1.4/ReversalAdministration/ReverseTransaction"
headers = {
  "Content-Type": "application/json",
  "X-CompanyNumber": "{{Company Number}}",
  "X-StoreNumber": "{{Store Number}}",
  "X-ReferenceId": "{{$guid}}",
  "X-Signature": "{{GeneratedSignature}}"
}
payload = {
  "OriginalReferenceId": "{{OriginalReferenceId}}",
  "ReversalType": "timeout",
  "RequestExpirationUTC": "2026-06-30T12:35:00.000Z"
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
print(response.status_code)
print(response.text)

using var client = new HttpClient();
using var req = new HttpRequestMessage(HttpMethod.Post,
    "{{baseURL}}/v1.4/ReversalAdministration/ReverseTransaction");

req.Headers.TryAddWithoutValidation("X-CompanyNumber", "{{Company Number}}");
req.Headers.TryAddWithoutValidation("X-StoreNumber", "{{Store Number}}");
req.Headers.TryAddWithoutValidation("X-ReferenceId", "{{$guid}}");
req.Headers.TryAddWithoutValidation("X-Signature", "{{GeneratedSignature}}");

req.Content = new StringContent("{\"OriginalReferenceId\":\"{{OriginalReferenceId}}\",\"ReversalType\":\"timeout\",\"RequestExpirationUTC\":\"2026-06-30T12:35:00.000Z\"}", Encoding.UTF8, "application/json");

var res = await client.SendAsync(req);
Console.WriteLine((int)res.StatusCode);
Console.WriteLine(await res.Content.ReadAsStringAsync());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("{{baseURL}}/v1.4/ReversalAdministration/ReverseTransaction"))
  .header("Content-Type", "application/json")
  .header("X-CompanyNumber", "{{Company Number}}")
  .header("X-StoreNumber", "{{Store Number}}")
  .header("X-ReferenceId", "{{$guid}}")
  .header("X-Signature", "{{GeneratedSignature}}")
  .POST(HttpRequest.BodyPublishers.ofString("{\"OriginalReferenceId\":\"{{OriginalReferenceId}}\",\"ReversalType\":\"timeout\",\"RequestExpirationUTC\":\"2026-06-30T12:35:00.000Z\"}"))
  .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());

<ReverseTransactionRequest>
  <OriginalReferenceId>{{OriginalReferenceId}}</OriginalReferenceId>
  <ReversalType>timeout</ReversalType>
  <RequestExpirationUTC>2026-06-30T12:35:00.000Z</RequestExpirationUTC>
</ReverseTransactionRequest>

<Responses>
  <Status code="200">
    <ReverseTransactionResponse>
      <ReversalStatus>Completed</ReversalStatus>
      <OriginalReferenceId>{{OriginalReferenceId}}</OriginalReferenceId>
      <ReferenceNumber>RV-1001</ReferenceNumber>
    </ReverseTransactionResponse>
  </Status>
  <Status code="400">
    <Error>
      <Code>INVALID_REQUEST</Code>
      <Message>OriginalReferenceId is missing or invalid.</Message>
      <Details>Verify request payload and reversal type.</Details>
    </Error>
  </Status>
  <Status code="401">
    <Error>
      <Code>UNAUTHORIZED</Code>
      <Message>Authentication failed.</Message>
      <Details>Invalid signature or merchant credentials.</Details>
    </Error>
  </Status>
</Responses>