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 nameRequiredDescriptionType
amountYesThe value of the paymentNumber
currencyYesThe currency of the paymentString
orderIdYesYour unique reference for this paymentString
paymentOptionYesBuyer's payment option details (Object)Object
consumer.emailYesBuyer's email addressString
consumer.countryYesBuyer's country code, ISO 2 lettersString
transactionTypeNoValues: 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 nameDescription
authorizationStatusThe status of the Authorization.
Learn more about Authorization Object
authorizationIdThe Authorization ID
transactionIdThe Transaction ID
paymentOptionPayment option Object (which contain mask card data)
sellerIdentityThe Vendor ID
orderIdYour Reference ID
amountThe amount of the payment
currencyThe currency of the payment
processorThe 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:

FieldValueType
amount0Number
currencyEURString
transactionTypeAuthString

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 nameRequiredDescriptionType
amountYesThe value of the paymentNumber
currencyYesThe currency of the paymentString
orderIdYesYour unique reference for this paymentString
paymentOptionIdYesThe token of the cardString
consumer.emailYesThe shopper email addressString
consumer.countryYesThe shopper's country code. ISO 2 lettersString
transactionTypeNoValues: 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 nameRequiredDescriptionType
terminalIdIdentifier for the terminal.
minLength: 1
maxLength: 8
string
trackDataInformation encoded on the magnetic stripe according to ISO 7813 standards or retrieved from the chip card.string
trackTypeIndicates 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
iccThe value of this field is the chip data taken directly from an EMV chip in encoded in Base64.string
pinDataThe PIN data provided by the cardholder encrypted according to the key received by TMS.string
entryModeIndicates the point of sale entry mode.
1: Manually entered
2: Magnetic stripe swiped
3: ICC Read (chip)
5: Contactless ICC
6: Contactless magstripe
integer
terminalCapabilityA bitmap that indicates the supported capabilities of the terminal.string
terminalAttendanceIndicates if the terminal is represented by the merchant.
0: Unattended
1: Attended
integer
cardSequenceNumNumber assigned to a specific card to distinguish between multiple cards linked to the same account.integer
offlineResCodeA response code generated by the terminal for offline transactions.string
localTimeThe time that the transaction occurred. HHmmss formatstring
localDateThe date that the transaction occurred. YYMMDD formatstring
cvMethodHow 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
cvEntityThe 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
outputCapabilityHow 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
suppressAuthDetermines 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
terminalCityThe city where the terminal is located.
minLength: 2
maxLength: 13
string
terminalAddressThe address where the terminal is located.
minLength: 3
maxLength: 20
string
terminalCountryThe country where the terminal is located.ISO code.
minLength: 2
maxLength: 2
string
terminalZipThe Zip code where the terminal is located.
minLength: 1
maxLength: 6
string
terminalStateThis field must contain a valid U.S. state code.
minLength: 3
maxLength: 3
string
terminalModelThe POS terminal model number.string
terminalManufacturerThe name of the POS terminal manufacture.string
terminalMacAddressThe POS terminal MAC address.string
terminalKernelstring
terminalImeiA 15-digit number assigned to a mobile phone during production under international standards.
minLength: 15
maxLength: 15
string
mobileTerminalThis 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"
  }
}'