Overview

The Terminal API is designed to revolutionize how businesses engage with payment solutions, offering a robust cloud REST interface that seamlessly initiates transactions on SmartPOS Terminals remotely. Our aim is to provide businesses with a versatile platform that effortlessly integrates into their existing systems, enhancing their payment capabilities and optimizing customer satisfaction.

Vision and Mission

Our vision and mission are intertwined with a singular goal: delivering an API that simplifies the integration process. We are committed to empowering businesses to quickly and efficiently implement advanced payment solutions with minimal friction. This commitment includes offering comprehensive documentation, exceptional support, and ongoing improvements, ensuring a seamless integration experience. As a result, our clients can focus on their core business operations and elevate customer satisfaction through enhanced payment capabilities.

Target Audience

The primary users of the Terminal API are ECR (Electronic Cash Register) integrators. These integrators can leverage our API to connect various point-of-sale systems seamlessly, enabling innovative and efficient payment handling capabilities.

Use Cases

The Terminal API is invaluable for initiating remote transactions on local SmartPOS Devices. This capability offers substantial flexibility for businesses, allowing for adaptive solutions such as mobile point-of-sale systems, unattended kiosks, and other advanced transaction setups that necessitate remote operation and control.

API Architecture

The Terminal API is built as a RESTful service designed to provide seamless interactions for initiating transactions on SmartPOS Terminals. This architecture ensures compatibility with a wide range of systems and programming languages, enabling straightforward integration and high flexibility.

Authentication and Authorization

The Terminal API employs an API key-based authentication mechanism to secure and manage access. Each API key is unique and must be requested for every Merchant intending to use the API. This key acts as a secure identifier that allows merchants to execute transactions through our services, ensuring that only authorized users can access and utilize the API.
To obtain an API key:

1. Request access to receive the dedicated API keys (one for integration and one for production environment).
2. Follow the instructions to confirm the merchant's identity and obtain the key.
3. Securely store and manage the API key, as it is crucial for accessing both the integration and production environments.

Environments

To facilitate development and deployment, the Terminal API provides two distinct environments:

• Integration Environment: This environment is intended for testing and development purposes. It allows developers to verify transaction processes without affecting real-world operations. In order to conduct meaningful tests, a development terminal is mandatory, as it enables the execution and validation of transaction flows accurately. The integration environment is accessible at:
  • https://api.terminal.iacc.global.worldline-solutions.com
• Production Environment: Once development and testing are complete, applications can be moved to the production environment for live operations. This environment is optimized for reliability and performance, ensuring smooth and secure transaction handling in a real-world setting. Access the production environment at:
  • https://api.terminal.global.worldline-solutions.com

Both environments are configured to ensure that transactions conducted in the integration stage do not affect actual business data, while the production stage is fine-tuned for handling transactional loads efficiently and securely.

Before diving into the implementation, it's crucial to have a comprehensive understanding of the API's functionality and transaction capabilities. To ensure a seamless integration experience with the Terminal API, please thoroughly review Chapter 4 and Chapter 5. These chapters provide critical insights into the REST implementation specifics and detail the supported transaction types.

Key Steps to Get Started

1. Understand the API Documentation:
   • Make sure to carefully read through Chapter 4, which presents detailed endpoint descriptions and REST implementation guidelines.
   • Familiarize yourself with Chapter 5 to understand the different transaction types supported by the Terminal API and their corresponding payload structures.
2. Request API Keys:
   • API keys are essential for accessing the Terminal API. These keys are currently distributed via email. To request an API key:
     • Contact our support team or designated email address provided in the Developer Portal.
     • Complete any verification steps required to confirm your merchant identity.
     • Upon approval, you will receive your API key via email. It is imperative to store this email securely or delete it after safely transferring the API key to your secure storage system. This precaution ensures that unauthorized parties cannot obtain or steal the API key.
3. Set Up Your Development Environment:
   • Use a development terminal to ensure accurate and reliable testing during your integration process.
   • Validate your setup by performing transactions in the integration environment to simulate real-world scenarios without impacting actual business data.

By following these steps, you'll be ready to proceed with the integration of the Terminal API into your existing systems. This groundwork will enable a smooth transition from testing to live operations, ensuring that your payment solutions are robust and efficient.

The Terminal API defines several endpoints intended to manage merchant information and terminal transactions. Below is the list of endpoints with their corresponding operations:

1. Merchant Management Endpoint:
   • GET /api/v1/merchants/{umid}/
     • Description: Retrieve merchant information and connected terminals
     • Parameters:
       • umid (string, path): Unique Merchant Identifier required to specify which merchant's information is to be retrieved.
2. Terminal Transaction Endpoint:
   • POST /api/v1/merchants/{umid}/terminals/{utid}/tapi/
     • Description: Start a transaction on a specified terminal.
     • Body: payload defined in Chapter 5
     • Parameters:
       • umid (string, path): Unique Merchant Identifier for the merchant initiating the transaction.
       • utid (string, path): Unique Terminal Identifier specifying which terminal to initiate the transaction on.

This chapter elaborates on the message types supported by the Terminal API, including their corresponding JSON payload structures. Each message type has its own unique set of fields required to conduct a successful transaction, although certain standard fields are common across all message exchanges. Understanding these fields is crucial for correctly integrating and utilizing the API.

Header

Environment

Environment of the transaction. It contains the sale environment as well.
Provides information about the Point of Interaction (POI) or terminal where the transaction is occurring

ServiceRequest

The ServiceRequest object resides within the SaleToPOIServiceRequest envelope and holds the transaction details based on the type of operation being performed. It includes mandatory sub-objects like Environment, ServiceContent, and depending on the type of transaction transaction-specific objects like PaymentRequest.

ServiceContent

General Sub-Objects

General sub-objects are repeated in all payment related requests

PaymentRequest Sub-Object

Notes:

1. Mandatory Fields: Fields such as TransactionType, TransactionIdentification, and TransactionDetails are mandatory for all transactions.
2. Optional Fields: The AdditionalService and DetailedAmount fields are optional and should only be included when specific services like tip or cashback are processed.
3. TotalAmount: The TotalAmount must reflect the sum of all applicable amounts, including the base transaction and any additional amounts like cashback or gratuity.

PaymentRequest Examples

Payment with Cashback

{
    "SaleToPOIServiceRequest": {
        "Header": {…},
        "ServiceRequest": {
            "Environment": {…},
            "ServiceContent": "FSPQ",
            "PaymentRequest": {
                "PaymentTransaction": {
                    "TransactionType": "CRDP",
                    "AdditionalService": ["GRTT", "CSHB"],
                    "TransactionIdentification": {
                        "TransactionDateTime": "2020-05-04T18:13:51.0+01:00",
                        "TransactionReference": "R26197055"
                    },
                    "TransactionDetails": {
                        "Currency": "EUR",
                        "TotalAmount": 18.00,
                        "DetailedAmount": {
                            "CashBack": 2.00
                        }
                    }
                }
            }
        }
    }
}

Refund

{
    "SaleToPOIServiceRequest": {
        "Header": {…},
        "ServiceRequest": {
            "Environment": {…},
            "ServiceContent": "FSPQ",
            "PaymentRequest": {
                "PaymentTransaction": {
                    "TransactionType": "RFND",
                    "TransactionIdentification": {
                        "TransactionDateTime": "2020-05-04T18:13:51.0+01:00",
                        "TransactionReference": "R26197055"
                    },
                    "TransactionDetails": {
                        "Currency": "EUR",
                        "TotalAmount": 104.11
                    }
                }
            }
        }
    }
}

Reservation

{
    "SaleToPOIServiceRequest": {
        "Header": {…},
        "ServiceRequest": {
            "Environment": {…},
            "ServiceContent": "FSPQ",
            "PaymentRequest": {
                "PaymentTransaction": {
                    "TransactionType": "RESA",
                    "ServiceAttribute": "IRES",
                    "TransactionIdentification": {
                        "TransactionDateTime": "2020-05-04T18:13:51.0+01:00",
                        "TransactionReference": "R26197055"
                    },
                    "TransactionDetails": {
                        "Currency": "EUR",
                        "TotalAmount": 15.00
                    }
                }
            }
        }
    }
}

Reservation incrementation

{
    "SaleToPOIServiceRequest": {
        "Header": {…},
        "ServiceRequest": {
            "Environment": {…},
            "ServiceContent": "FSPQ",
            "PaymentRequest": {
                "PaymentTransaction": {
                    "TransactionType": "RESA",
                    "ServiceAttribute": "URES",
                    "TransactionIdentification": {
                        "TransactionDateTime": "2020-05-08T18:13:51.0+01:00",
                        "TransactionReference": "R26197055"
                    },
                    "OriginalTransaction": {
                        "TransactionIdentification": {
                            "TransactionDateTime": "2020-05-04T18:13:51.0+01:00",
                            "TransactionReference": "2;00999100022;43350829991;79454;010099910002243350829991;"
                        }
                    },
                    "TransactionDetails": {
                        "Currency": "EUR",
                        "TotalAmount": 15.00,
                        "CumulativeAmount": 35.00,
                        "AmountQualifier": "INCR",
                        "ValidityDate": "2020-05-09T18:13:51.0+01:00"
                    }
                }
            }
        }
    }
}

Purchase Reservation

{
    "SaleToPOIServiceRequest": {
        "Header": {…},
        "ServiceRequest": {
            "Environment": {…},
            "ServiceContent": "FSPQ",
            "PaymentRequest": {
                "PaymentTransaction": {
                    "TransactionType": "RESA",
                    "ServiceAttribute": "PRES",
                    "TransactionIdentification": {
                        "TransactionDateTime": "2020-05-04T18:13:51.0+01:00",
                        "TransactionReference": "R26197055"
                    },
                    "OriginalTransaction": {
                        "TransactionIdentification": {
                            "TransactionDateTime": "2020-05-04T18:13:51.0+01:00",
                            "TransactionReference": "2;00999100022;43350829991;79454;010099910002243350829991;"
                        }
                    },
                    "TransactionDetails": {
                        "Currency": "EUR",
                        "TotalAmount": 15.00
                    }
                }
            }
        }
    }
}

ReversalRequest Sub-Object

Reversal Example

{
  "SaleToPOIServiceRequest": {
    "Header": {
      
    },
    "ServiceRequest": {
      "Environment": {
        
      },
      "ServiceContent": "FSRQ",
      "ReversalRequest": {
        "ReversalTransaction": {
          "TransactionType": "CRDP",
          "OriginalTransaction": {
            "TransactionIdentification": {
              "TransactionReference": "2;00000000002;61479390591;169868;010000000000261479390591;",
              "TransactionDateTime": "2020-05-04T18:13:51.0+01:00"
            }
          }
        },
        "ReversalReason": "MERC"
      }
    }
  }
}

CardAcquisitionRequest Sub-Object

A cardAcquisitionRequest is utilized to obtain a PAN from a payment card alone or to execute a particular transaction to obtain the payment response and a token.

SaleToPOIData Sub-Object Fields

SaleToPOIData is a JSON string and the following fields needs to be added.

CardAcquisitionRequest Example

{
    "SaleToPOIServiceRequest": {
        "Header": {…},
        "ServiceRequest": {
            "Environment": {…},
            "ServiceContent": "FSAQ",
            "CardAcquisitionRequest": {
                "TotalAmount": 15.00,
                "PaymentType": "CRDP",
                "SaleToPOIData": {
                    'tipAmount': 2.00,
                    'currency': "EUR",
                    'recognitionTimeout': 60000,
                    'recognitionOptions': [
                        'WPI_RECOGNITION_OPTION_RETURN_CUSTOMER_TOKEN'
                    ]
                }
            }
        }
    }
}

ServiceResponse

The ServiceResponse object resides within the SaleToPOIServiceResponse envelope and holds the transaction response details based on the type of operation being performed. It includes mandatory sub-objects like Environment, ServiceContent, and depending on the type of transaction transaction-specific objects like PaymentResponse.

PaymentResponse Sub-Object

RequestResponse Example

{
    "SaleToPOIServiceResponse": {
        "Header": {
            "MessageFunction": "SFSP",
            "ProtocolVersion": "5.0",
            "ExchangeIdentification": "642",
            "CreationDateTime": "2020-05-04T18:13:51.0+01:00",
            "InitiatingParty": {
                "Identification": "WL000D5T0000004",
                "Type": "MERC"
            }
        },
        "ServiceResponse": {
            "Environment": {
                "Acquirer": {
                    "Identification": {
                        "Identification": "00999100022"
                    }
                },
                "Merchant": {
                    "Identification": {
                        "Identification": "WL000D5T0000004"
                    }
                },
                "POI": {
                    "Identification": {
                        "Identification": "26197214"
                    }
                },
                "Card": {
                    "CardBrand": "VISA CREDIT",
                    "MaskedPin": "XXXXXXXXXXXX0119"
                },
                "CardHolder": {
                    "Language": "FR"
                }
            },
            "ServiceContent": "FSPP",
            "PaymentResponse": {
                "SaleTransactionIdentification": {
                    "TransactionDateTime": "2020-05-04T18:13:51.0+01:00",
                    "TransactionReference": "R26197055"
                },
                "POITransactionIdentification": {
                    "TransactionDateTime": "2020-05-04T18:13:51.0+01:00",
                    "TransactionReference": "2;00999100022;19940829991;79429;010099910002219940829991;"
                },
                "RequestedTransaction": {
                    "TransactionType": "CRDP",
                    "AdditionalService": ["GRTT", "CSHB"],
                    "RequestedTransaction": {
                        "TransactionType": "CRDP",
                        "TransactionIdentification": {
                            "TransactionDateTime": "2020-05-04T18:13:51.0+01:00",
                            "TransactionReference": "579"
                        },
                        "TransactionDetails": {
                            "TotalAmount": 18.00,
                            "Currency": "EUR",
                            "DetailedAmount": {
                                "CashBack": 2.00,
                                "Gratuity": 3.00
                            }
                        }
                    },
                    "TransactionResponse": {
                        "AuthorisationResult": {
                            "ResponseToAuthorisation": {
                                "Response": "APPR"
                            },
                            "AuthorisationCode": "00"
                        }
                    },
                    "CustomerLanguage": "FR"
                },
                "PaymentReceipt": [
                    {
                        "DocumentQualifier": "CRCP",
                        "OutputContent": {
                            "MessageDestination": "CRCP",
                            "Format": "SimpleText",
                            "MessageContent": "--------------------------------\n
                            QA NIEXP\n
                            Chau. de Haecht 1442\n
                            1130 Brussels\n
                            --------------------------------\n
                            \n
                            ***Cardholder Receipt***\n
                            \n
                            Purchase\n
                            VISA CREDIT contactless\n
                            XXXXXXXXXXXX0119\n
                            Account Type: Credit\n
                            \n
                            03.07.2024 14:16:23\n
                            Trm-Id: 26197214\n
                            AID: A0000000031010\n
                            Trx. Seq-Cnt: 79429\n
                            Trx. Ref-No: 19940829991\n
                            Auth. Code: 057737\n
                            Acq-Id: 999100022\n
                            \n
                            \n
                            Total-EFT EUR: 18.00\n
                            \n
                            Transaction OK"
                        }
                    },
                    {
                        "DocumentQualifier": "HRCP",
                        "OutputContent": {
                            "MessageDestination": "MRCP",
                            "Format": "SimpleText",
                            "MessageContent": "--------------------------------\n
                            QA NIEXP\n
                            Chau. de Haecht 1442\n
                            1130 Brussels\n
                            --------------------------------\n
                            \n
                            Purchase\n
                            VISA CREDIT contactless\n
                            XXXXXXXXXXXX0119\n
                            Account Type: Credit\n
                            \n
                            03.07.2024 14:16:23\n
                            Trm-Id: 26197214\n
                            Act-Id: 40\n
                            AID: A0000000031010\n
                            Trx. Seq-Cnt: 79429\n
                            Trx. Ref-No: 19940829991\n
                            Auth. Code: 057737\n
                            Acq-Id: 999100022\n
                            E4B00E9F1B979BCEF016662BF9C201D5\n
                            02/10\n
                            \n
                            \n
                            Total-EFT EUR: 18.00\n
                            \n
                            Transaction OK"
                        }
                    }
                ]
            },
            "Response": {
                "Response": "SUCC"
            }
        }
    }
}

Reversal Response

ReversalResponse Example

{
    "SaleToPOIServiceResponse": {
        "Header": {
            "MessageFunction": "SFSP",
            "ProtocolVersion": "5.0",
            "ExchangeIdentification": "642",
            "CreationDateTime": "2020-05-04T18:13:51.0+01:00",
            "InitiatingParty": {
                "Identification": "SaleTermA",
                "Type": "MERC"
            }
        },
        "ServiceResponse": {
            "Environment": {
                "Acquirer": {
                    "Identification": {
                        "Identification": "00999100022"
                    }
                },
                "Merchant": {
                    "Identification": {
                        "Identification": "WL000D5T0000004"
                    }
                },
                "POI": {
                    "Identification": {
                        "Identification": "26197214"
                    }
                },
                "Card": {
                    "MaskedPAN": "XXXXXXXXXXXX0119"
                },
                "CardHolder": {
                    "Authentication": [
                        {
                            "AuthenticationMethod": "BYPS"
                        }
                    ]
                }
            },
            "ServiceContent": "FSRP",
            "ReversalResponse": {
                "SaleTransactionIdentification": {
                    "TransactionDateTime": "2020-05-08T18:13:51.0+01:00",
                    "TransactionReference": "651"
                },
                "POITransactionIdentification": {
                    "TransactionDateTime": "2020-05-08T18:13:51.0+01:00",
                    "TransactionReference": "2;00999100022;80450829991;79490;010099910002280450829991;"
                },
                "ReversalTransactionResult": {
                    "OriginalPaymentTransaction": {
                        "TransactionType": "RESA",
                        "ServiceAttribute": "IRES",
                        "TransactionIdentification": {
                            "TransactionDateTime": "2020-05-08T18:13:51.0+01:00",
                            "TransactionReference": "2;00000000002;56514186991;210702;010000000000256514186991;"
                        },
                        "TransactionDetails": {
                            "Currency": "EUR",
                            "TotalAmount": 15.00
                        }
                    }
                },
                "ReversedAmount": "1000",
                "Receipt": [
                    {
                        "DocumentQualifier": "CRCP",
                        "OutputContent": "SimpleText",
                        "MessageDestination": "CRCP",
                        "MessageContent": "--------------------------------\n
                        QA NIEXP\n
                        Chau. de Haecht 1442\n
                        1130 Brussels\n
                        --------------------------------\n
                        \n
                        ***Cardholder Receipt***\n
                        \n
                        Reversal\n
                        VISA CREDIT\n
                        Account Type: Credit\n
                        \n
                        04.07.2024 10:22:17\n
                        Trm-Id: 26197214\n
                        AID: A0000000031010\n
                        Trx. Seq-Cnt: 79490\n
                        Rev. Seq-Cnt: 79489\n
                        Trx. Ref-No: 80450829991\n
                        Acq-Id: 999100022\n
                        \n
                        Total-EFT EUR: 15.00\n
                        \n
                        Transaction OK"
                    },
                    {
                        "DocumentQualifier": "HRCP",
                        "OutputContent": "SimpleText",
                        "MessageDestination": "MRCP",
                        "MessageContent": "--------------------------------\n
                        QA NIEXP\n
                        Chau. de Haecht 1442\n
                        1130 Brussels\n
                        --------------------------------\n
                        \n
                        Reversal\n
                        VISA CREDIT\n
                        Account Type: Credit\n
                        \n
                        04.07.2024 10:22:17\n
                        Trm-Id: 26197214\n
                        Act-Id: 40\n
                        AID: A0000000031010\n
                        Trx. Seq-Cnt: 79490\n
                        Rev. Seq-Cnt: 79489\n
                        Trx. Ref-No: 80450829991\n
                        Acq-Id: 999100022\n
                        \n
                        Total-EFT EUR: 15.00\n
                        \n
                        Transaction OK"
                    }
                ]
            },
            "Response": {
                "Response": "SUCC"
            }
        }
    }
}

CardAcquisitionResponse Sub-Object

CardAcquisitionResponse Example

{
    "SaleToPOIServiceResponse": {
        "Header": {…},
        "ServiceResponse": {
            "Environment": {
                "Acquirer": {
                    "Identification": {
                        "Identification": "00999100022"
                    }
                },
                "Merchant": {
                    "Identification": {
                        "Identification": "WL000D5T0000004"
                    }
                },
                "POI": {
                    "Identification": {
                        "Identification": "26197214"
                    }
                },
                "Card": {
                    "PlainCardData": {
                        "Track1": "…",
                        "Track2": "…",
                        "Track3": "…"
                    },
                    "MaskedPin": "XXXXXXXXXXXX0119"
                },
                "PaymentToken": {
                    "PaymentToken": "…"
                },
                "CardHolder": {
                    "Language": "FR"
                },
                "ServiceContent": "FSAP",
                "CardAcquisitionResponse": {
                    "SaleTransactionIdentification": {
                        "TransactionDateTime": "2020-05-04T18:13:51.0+01:00",
                        "TransactionReference": "R26197055"
                    },
                    "POITransactionIdentification": {
                        "TransactionDateTime": "2020-05-04T18:13:51.0+01:00",
                        "TransactionReference": "2;00999100022;19940829991;79429;010099910002219940829991;"
                    }
                },
                "Response": {
                    "Response": "SUCC"
                }
            }
        }
    }
    

Reject

The Reject object resides within the SaleToPOIMessageRejection envelope and is sent by one of the parties when it detects a technical or functional error in a previously received message.

Reject Sub-Object

SystemAbort Example

{
    "SaleToPOIMessageRejection": {
        "Header": {
            "MessageFunction": "SSRJ",
            "ProtocolVersion": "5.0",
            "ExchangeIdentification": "675",
            "CreationDateTime": "2020-05-04T18:13:51.0+01:00",
            "InitiatingParty": {
                "Identification": "WL000D5T0000004",
                "Type": "MERC"
            }
        },
        "Reject": {
            "RejectReason": "UNPR"
        }
    }
}

StatusRequest

The StatusRequest object resides within the SaleToPOIMessageStatusRequest envelope and is sent by a sale system when the sale system wants to know the status of previous message that has not been answered.

General Sub-Objects

General sub-objects are repeated in all payment related requests.

MessageStatusRequestData Sub-Object

MessageStatusRequestData example

{
    "SaleToPOIMessageStatusRequest": {
        "Header": {
            "MessageFunction": "SFSQ",
            "ProtocolVersion": "5.0",
            "ExchangeIdentification": "642",
            "CreationDateTime": "2020-05-04T18:13:51.0+01:00",
            "InitiatingParty": {
                "Identification": "SaleTermA",
                "Type": "MERC"
            }
        },
        "StatusRequest": {
            "Environment": {
                "POI": {
                    "Identification": {
                        "Identification": "POITerm1"
                    }
                }
            },
            "MessageStatusRequestData": {
                "ExchangeIdentification": "642",
                "InitiatingParty": {
                    "Identification": "SaleTermA",
                    "Type": "MERC"
                }
            }
        }
    }
}

StatusResponse

The StatusResponse object resides within the SaleToPOIMessageStatusResponse envelope and is sent by a POI System to respond to the sale system at a previous message status request.

General Sub-Objects

General sub-objects are repeated in all payment related requests

MessageStatusRequestData Sub-Object

MessageStatusRequestData example

{
    "SaleToPOIMessageStatusRequest": {
        "Header": {
            "MessageFunction": "SFSQ",
            "ProtocolVersion": "5.0",
            "ExchangeIdentification": "642",
            "CreationDateTime": "2020-05-04T18:13:51.0+01:00",
            "InitiatingParty": {
                "Identification": "SaleTermA",
                "Type": "MERC"
            }
        },
        "StatusRequest": {
            "Environment": {
                "POI": {
                    "Identification": {
                        "Identification": "POITerm1"
                    }
                }
            },
            "MessageStatusRequestData": {
                "ExchangeIdentification": "642",
                "InitiatingParty": {
                    "Identification": "SaleTermA",
                    "Type": "MERC"
                }
            }
        }
    }
}

• TLS/SSL is used by default for all communications involving the Terminal API. This ensures that data exchanged between clients and the server is encrypted, helping prevent eavesdropping and tampering.
• HSTS (HTTP Strict Transport Security) is also active. This protocol enforces the use of secure connections, ensuring that all interactions with the API are conducted over HTTPS.
• PCI Compliance
  • The Terminal API is designed to comply with PCI DSS (Payment Card Industry Data Security Standard) requirements by default.
  • No PCI-related data, such as full card numbers or other unmasked sensitive information, is available through the API. This minimizes risk and ensures compliance with industry standards for handling payment information securely.