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 | 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"
}
}'
Updated over 2 years ago