API Only (Server to Server)

With API Only, platforms/merchants can access the UNIPaaS Pay-in functionalities to enable single payments, create tokens, create 3DS payments, recurring payments, and more. All these calls require the caller to have a secret key (Private_Key).

You can find instructions on how to get the private key here.

Use this API to build your own payment form and have complete control over your checkout page's look and feel.

🚧
In the API Only implementation you collect and pass raw card data.
This requires you to assess your PCI compliance according to SAQ D, the most extensive form of self-certification.

Before you begin

📘
Please note: If you send a transaction without any vendor ID - the transaction will be entered to the platform e-wallet and will be listed as a platform transaction

Create a simple payment

To create a simple payment you need the card and the shopper's information (email and country). After the shopper submits their payment details on your checkout page, you need to make a payment request to UNIPaaS.

From your server make an POST /pay-ins request specifying:

Parameter name	Required	Description	Type
`amount`	Yes	The value of the payment	Number
`currency`	Yes	The currency of the payment	String
`orderId`	Yes	Your unique reference for this payment	String
`paymentOption`	Yes	Buyer's payment option details (Object)	Object
`consumer.email`	Yes	Buyer's email address	String
`consumer.country`	Yes	Buyer's country code, ISO 2 letters	String
`transactionType`	No	Values: `Auth` or `Sale`. The default is `Sale`. Use `Auth` in cases where you want to separate between the Authorization step and capture (read more here)	String

curl --location --request POST 'https://sandbox.unipaas.com/platform/pay-ins' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer --YOUR_PRIVATE_KEY--' \
--data-raw '{
  "amount": 50,
  "currency": "EUR",
  "platformOrderId": "13323",
  "paymentOption": {
    "paymentOptionType": "Card",
    "cardAccount": {
      "nameOnCard": "test shopper",
      "expYear": "23",
      "expMonth": "10",
      "number": "4000023104662535",
      "securityCode": "132",
      "externalMpi": {
        "eci": "2",
        "cavv": "ejJRWG9SWWRpU2I1M21DelozSXU="
      }
    }
  },
  "consumer": {
    "email": "[email protected]",
    "country": "GB"
  },
   "metadata": {
    "CustomerID": "457349"
  }
}'

The following example shows the POST /pay-ins response:

{
    "status": "Approved",
    "authorizationId": "608682347e445aaa7ccd7a61",
    "authorizationStatus": "Captured",
    "transactionId": "608682347e445aaa7ccd7a64",
    "paymentOption": {
        "paymentOptionId": "608682367e445aaa7ccd7a65",
        "bin": "400002",
        "brand": "VISA",
        "last4digits": "2535",
        "cardType": "Credit",
        "expMonth": "10",
        "expYear": "23"
    },
    "sellerIdentity": "6076ebff0f11f7d98514c4da",
    "currency": "EUR",
    "transactionAmount": 50,
    "declineCode": "0",
    "threeD": {
        "result": "",
        "challengePreferenceReason": "12",
        "whiteListStatus": "",
        "threeDreasonId": "",
        "eci": "2",
        "xid": ""
    },
    "processor": {
        "processorAuthCode": "111216",
        "processorTransactionId": "1110000000013512555",
        "processorErrorCode": 0
    },
    "items": [],
    "orderId": "13323",
    "metadata": {
      "CustomerID": "457349"
    }
}

Parameter name	Description
`authorizationStatus`	The status of the Authorization. Learn more about Authorization Object
`authorizationId`	The Authorization ID
`transactionId`	The Transaction ID
`paymentOption`	Payment option Object (which contain mask card data)
`sellerIdentity`	The Vendor ID
`orderId`	Your Reference ID
`amount`	The amount of the payment
`currency`	The currency of the payment
`processor`	The processor Object. This Object contains the information from the acquirer for the specific payment

Store credit card details

You can use this functionality when you want to store the shopper's card details for future use or as part of a Recurring Payment flow.

Card schemes often insist on sending a zero-authorization transaction (amount=0) before allowing card credentials to be stored for future use.

In Europe the card schemes require the completion of Strong Authentication Validation (3D SECURE 2) for each zero-authorization request. As 3D secure flow implementation involves both client, and server side, we thoroughly recommend you to use our Web SDK Store Card flow Store Card instead of implementing it on your own.

If you still want to use the API Only flow, you should follow the 3D Secure guide with the following changes in the request:

Field	Value	Type
`amount`	0	Number
`currency`	EUR	String
`transactionType`	Auth	String

The response includes the PaymentOptionId field - this is the token of the card and you should keep it for future use.

Create a simple payment with token

As described in the previous section, the paymentOptionId is the token of the card. You should send it instead of the paymentOption object.

Parameter name	Required	Description	Type
`amount`	Yes	The value of the payment	Number
`currency`	Yes	The currency of the payment	String
`orderId`	Yes	Your unique reference for this payment	String
`paymentOptionId`	Yes	The token of the card	String
`consumer.email`	Yes	The shopper email address	String
`consumer.country`	Yes	The shopper's country code. ISO 2 letters	String
`transactionType`	No	Values: `Auth` or `Sale`. The default is `Sale`. Use `Auth` in cases where you want to separate between the Authorization step and capture (read more here)	String

Create card present payment

This section explains how to integrate credit card processing with card-present data, and describes the additional parameters you should send and receive from the API.

The main object is the 'pos' which includes all the relevant data. you should add the pos object to simple payment creation call in order to send card present transaction.

The POS object description

Parameter name	Description	Type
terminalId	Identifier for the terminal. minLength: 1 maxLength: 8	string
trackData	Information encoded on the magnetic stripe according to ISO 7813 standards or retrieved from the chip card.	string
trackType	Indicates which track was recorded in the transaction. 1 -Track 1 2- Track 2 Mandatory when POSEntryMode = 3 or 5 and tags 56 and 57 are present.	integer
icc	The value of this field is the chip data taken directly from an EMV chip in encoded in Base64.	string
pinData	The PIN data provided by the cardholder encrypted according to the key received by TMS.	string
entryMode	Indicates the point of sale entry mode. 1: Manually entered 2: Magnetic stripe swiped 3: ICC Read (chip) 5: Contactless ICC 6: Contactless magstripe	integer
terminalCapability	A bitmap that indicates the supported capabilities of the terminal.	string
terminalAttendance	Indicates if the terminal is represented by the merchant. 0: Unattended 1: Attended	integer
cardSequenceNum	Number assigned to a specific card to distinguish between multiple cards linked to the same account.	integer
offlineResCode	A response code generated by the terminal for offline transactions.	string
localTime	The time that the transaction occurred. HHmmss format	string
localDate	The date that the transaction occurred. YYMMDD format	string
cvMethod	How the customer was authenticated for a card-present transaction. Mandatory when channel=3. The possible values are: 0: Not authenticated 1: PIN 2: Electronic signature 5: Manual signature verification 6: Other verification 9: Unknown S: Other systematic verification	integer
cvEntity	The type of authentication entity The possible values are: 0: Not authenticated 1: Offline chip 2: Card acceptance device 3: Authorizing agent Online PIN 4: Merchant/card acceptor—signature 5: Other 9: Unknown	integer
outputCapability	How the response of the transaction is to be returned to the customer: 0: Unknown 1: None 2: Printing capability only 3: Display capability 4: Printing and display capability	integer
suppressAuth	Determines if the transaction should be authorized or settled. The possible values include: 0: Sent online for an authorization and then settled offline. 1: Settle without authorization.	integer
terminalCity	The city where the terminal is located. minLength: 2 maxLength: 13	string
terminalAddress	The address where the terminal is located. minLength: 3 maxLength: 20	string
terminalCountry	The country where the terminal is located.ISO code. minLength: 2 maxLength: 2	string
terminalZip	The Zip code where the terminal is located. minLength: 1 maxLength: 6	string
terminalState	This field must contain a valid U.S. state code. minLength: 3 maxLength: 3	string
terminalModel	The POS terminal model number.	string
terminalManufacturer	The name of the POS terminal manufacture.	string
terminalMacAddress	The POS terminal MAC address.	string
terminalKernel		string
terminalImei	A 15-digit number assigned to a mobile phone during production under international standards. minLength: 15 maxLength: 15	string
mobileTerminal	This parameter shows whether or not the POS is a mobile POS terminal. ‘1’ indicates that it is mobile. In the event that the POS is not mobile, there is no need to send any value.	integer

curl --location --request POST 'https://sandbox.unipaas.com/platform/pay-ins' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer --YOUR_PRIVATE_KEY--' \
--data-raw '{
  "amount": 50,
  "currency": "EUR",
  "platformOrderId": "13323",
  "paymentOption": {
    "cardAccount": {
      "nameOnCard": "test shopper",
      "expYear": "23",
      "expMonth": "10",
      "number": "4000023104662535",
      "securityCode": "132",
    }
  },
  "consumer": {
    "email": "[email protected]",
    "country": "GB"
  },
    "pos":
  {
    "terminalId": "3",
    "trackData": "4300040000701248D221210100000887",
    "entryMode": "2",
    "trackType" : "2",
    "terminalCapability": "11111",
    "terminalAttendance": 1,
    "suppressAuth": 0,
    "localTime": "103000",
    "localDate": "190224",
    "cvMethod": 5,
    "cvEntity": 4,
    "outputCapability": 0,
    "terminalCity": "New York",
    "terminalAddress": "100 Main St.",
    "terminalCountry": "se",
    "terminalZip": "123",
    "posCardSequenceNum" : "00",
    "posTerminalManufacture" : "LVNX LTD",
    "posTerminalModel" : "VPOS V1.4"
  }
}'