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"
  }
}'

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"
}

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

Required

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"
  }
}'