Payment ECR

Wonder Terminal API allows you to integrate the payment terminal devices provided by Wonder with your application, enabling payment, refunds, and other operations that interact with the terminal device.

Before proceeding with the actual integration work, it is important to understand the working principles and processes of Terminal API.

• Enable Terminal API. You need to log in to the merchant backend or contact a salesperson to enable Terminal API.
• Set Shared Key. To protect communication security, whether it is local communication or cloud communication, message encryption needs to be enabled for information exchange. Therefore, it is necessary to set a password that meets the specifications for encryption and decryption through the merchant backend.
• Use The Correct Endpoint. Terminal API provides two different communication methods for integration in different scenarios.
  • Local Communication. The feature of local communication is that it integrates with your application through the local area network, avoiding the impact of network quality caused by the Internet.
  • Cloud Communication. If your application cannot be deployed locally, consider using cloud communication to interact.

Communications

Local Communication

If you are using local communication integration, API Requests will be sent directly from your application to the IP address of the terminal device. The terminal listens for POST requests to /wonder-terminal on port 8443. For example, if your terminal has the IP address 198.168.0.100, you would make API requests to: https://182.168.0.100:8443/wonder-terminal.

You should either use DHCP for the terminal IP addresses, or manually configure static IP addresses. This helps to prevent connection issues when the terminal or your network reboots.

As the HTTPS certificate is self-signed in the terminal device, your device also needs to install the Wonder Root Certificate to enable normal HTTPS communication.

Cloud Communication

When you use cloud communication, you will use the Wonder cloud API to send commands to terminal devices, and the cloud will forward the commands to the terminal devices to complete the work.

Whether using local communication or cloud communication, the message format is exactly the same, so you can easily switch between different integration methods.

Encryption Method

Preparation of Encryption Materials:

In your application, you are generating encryption materials using a Shared Key with the PBKDF2-HMAC-SHA1 algorithm. The parameters for the PBKDF2-HMAC-SHA1 algorithm are as follows:

• Salt: WMSaltV1
• Salt Length: 8
• Rounds: 4000
• Key Length: 80

Using the PBKDF2-HMAC-SHA1 algorithm, you will eventually obtain three results for HMAC KEY / CIPHER KEY / IV for subsequent encryption, following these rules:

• Bytes 0-31: HMAC KEY (32 bytes)
• Bytes 32-63: CIPHER KEY (32 bytes)
• Bytes 64-83: IV (16 bytes)
• Generate a random 16-byte IV.

Encrypt the message body using the AES256-CBC algorithm:

• Perform XOR operation between the IV generated in step #2 and the IV generated in step #1 (resulting in 'a').
• Encrypt the message body using the CIPHER KEY generated in step #1 and the IV ('a') obtained in step 3.1, resulting in ciphertext.
• Calculate the HASH of the original message using the HMAC KEY generated in step #1 and the SHA256 algorithm.

Finally, generate an encrypted message body and transmit this message.

{
    "SaleToPOIRequest": {
        "MessageHeader": {}, // MessageHeader does not need to be encrypted
        "SecurityTrailer": {
            "KeyVersion": "",
            "KeyIdentifier": "",
            "Hmac": "", // HMAC KEY obtained by #1 is encoded in standard base64
            "Nonce": "", // #2 generates IV
            "WonderCryptoVersion": 1 // Encrypt
        },
        "WonderBlob": "" // Base64 encoding of the encrypted ciphertext
    }
}

API Endpoints

Env	Endpoint
Production	https://gateway.wonder.app/api/oms/b2b/open/terminal/async

API Structure

Our Terminal API communicates with the terminal using JSON messages. All requests and responses have the following message header-body structure:

• Message header: identifies the type of transaction, the terminal being used, and unique transaction identifiers.
• Body: a request or response object, depending on the type of transaction. For example, when you make a payment request this is a PaymentRequest object, and when you receive a payment response this is a PaymentResponse object.

Requests

Each Terminal API request you make is contained in a SaletoPOIRequest object. In this, you need to provide a:

• Message Header. The Message Header defines metadata that is unrelated to transaction behavior, such as terminal device and protocol version.
• Body. Different transaction types have different formats for the Body and Response. You need to use PaymentRequest when creating a Payment.

Field	Type	Comments
ProtocolVersion	String	Version number of the communication protocol. The latest version is 1.0
MessageClass	Enum	It should all be Services in your integration with no specific requirement
MessageCategory	Enum	Transaction Type
MessageType	Enum	Only Request is supported at present
ServiceID	UUID	The unique ID for this message.
SaleID	String	The unique ID for transactions in your application
POIID	String	The unique ID of the terminal. Format: [Device Model]-[Serial Number]
BusinessID	String	Merchant’s Business ID

{
  "ProtocolVersion" :  "1.0",
  "MessageClass" : "Service",
  "MessageCategory" : "Payment",
  "MessageType" : "Request",
  "ServiceID": "3d8294b3-012b-4c5c-bbae-fd53057f7733",
  "SaleID" : "ba68ab30-986b-4819-b65f-ef79ec5bb33e",
  "POIID" : "PAX920-123456789",
  "BusinessID": "7e942219-d95d-4a31-bbc1-13a7c3bc0796"
}

Responses

Similar to Request, Response also includes Message Header and Body structures. The Message Header is consistent with the header you passed in the Request, and the Body varies with different transaction behaviors.