Logo

Peer To Peer Transaction Service (P2P)

Service provides logic for Peer To Peer transactions by Fenige API.

1. Methods in API

1.1. Calculate commission

1.1.1. Request

POST /api/calculate-commission HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Basic bG9naW46cGFzc3dwcmQ=
Content-Length: 279
Host: localhost:8080

{
  "amount" : 200078,
  "type" : "RECEIVER",
  "sender" : {
    "cardId" : "219834",
    "currency" : "PLN",
    "userId" : "613231"
  },
  "receiver" : {
    "userId" : 2345,
    "card" : "5495984179082645",
    "currency" : "PLN",
    "receiverType" : "BARE_CARD_NUMBER"
  }
}

1.1.2. Request body

.

Path Type Constraints Description

amount

Number

Required

The total transfer amount (in pennies)

type

String

Required

Value of (SENDER or RECEIVER)

sender.cardId

String

Required

Sender card id

sender.userId

String

Required

User id

sender.currency

String

Required

Sender currency

receiver.userId

Number

Required

Receiver card id

receiver.card

String

Required

Receiver card id

receiver.receiverType

String

Required

Receiver type. One of: [EMPTY, WALLET_CARD_ID, FRIEND_ID, BARE_CARD_NUMBER]

receiver.currency

String

Required

Receiver currency

1.1.3. Request headers

Type

Value

Constraints

Description

Authorization

Basic bG9naW46YWNrbWU=

Required

Authentication header. Product login & password. Provided while integrating to API.

1.1.4. Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 1041

{
  "commission" : 5,
  "transactionCommissions" : [ {
    "value" : 50,
    "bigDecimalValue" : 0.5,
    "currencyExponent" : 2,
    "currency" : "PLN",
    "commissionConfiguration" : {
      "currency" : "PLN",
      "commissionType" : "PROVISION",
      "reconciliationType" : "PLUS",
      "geographicScope" : "CROSSBORDER",
      "transactionType" : {
        "id" : "funding",
        "name" : "MoneySend Funding"
      }
    }
  } ],
  "revaluationResult" : {
    "revaluationFundingAmount" : 200,
    "bigDecimalRevaluationFundingAmount" : 2.0,
    "revaluationFundingTotalAmount" : 205,
    "bigDecimalRevaluationFundingTotalAmount" : 2.05,
    "fundingCurrency" : "PLN",
    "revaluationPaymentAmount" : 200,
    "bigDecimalRevaluationPaymentAmount" : 2.0,
    "revaluationPaymentTotalAmount" : 200,
    "bigDecimalRevaluationPaymentTotalAmount" : 2.0,
    "paymentCurrency" : "PLN",
    "determineCurrencyRate" : {
      "from" : "PLN",
      "to" : "PLN",
      "currencyRate" : "1"
    }
  },
  "isInternalTransaction" : true
}

1.1.5. Response body

Path Type Description

commission

Number

Commission value

transactionCommissions

Array

transaction commissions

transactionCommissions.[].value

Number

transactionCommissions.[].bigDecimalValue

Number

transactionCommissions.[].currencyExponent

Number

transactionCommissions.[].currency

String

transactionCommissions.[].commissionConfiguration

Object

transactionCommissions.[].commissionConfiguration.currency

String

transactionCommissions.[].commissionConfiguration.commissionType

String

transactionCommissions.[].commissionConfiguration.reconciliationType

String

transactionCommissions.[].commissionConfiguration.geographicScope

String

transactionCommissions.[].commissionConfiguration.transactionType

Object

transactionCommissions.[].commissionConfiguration.transactionType.id

String

transactionCommissions.[].commissionConfiguration.transactionType.name

String

revaluationResult

Object

revaluationResult.revaluationFundingAmount

Number

revaluationResult.bigDecimalRevaluationFundingAmount

Number

revaluationResult.revaluationFundingTotalAmount

Number

revaluationResult.bigDecimalRevaluationFundingTotalAmount

Number

revaluationResult.fundingCurrency

String

revaluationResult.revaluationPaymentAmount

Number

revaluationResult.bigDecimalRevaluationPaymentAmount

Number

revaluationResult.revaluationPaymentTotalAmount

Number

revaluationResult.bigDecimalRevaluationPaymentTotalAmount

Number

revaluationResult.paymentCurrency

String

revaluationResult.determineCurrencyRate

Object

revaluationResult.determineCurrencyRate.from

String

revaluationResult.determineCurrencyRate.to

String

revaluationResult.determineCurrencyRate.currencyRate

String

isInternalTransaction

Boolean

The isInternalTransaction indicates whether the transaction has been marked as internal

1.1.6. Examples

$ curl 'http://localhost:8080/api/calculate-commission' -i -u 'login:passwprd' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "amount" : 200078,
  "type" : "RECEIVER",
  "sender" : {
    "cardId" : "219834",
    "currency" : "PLN",
    "userId" : "613231"
  },
  "receiver" : {
    "userId" : 2345,
    "card" : "5495984179082645",
    "currency" : "PLN",
    "receiverType" : "BARE_CARD_NUMBER"
  }
}'
$ echo '{
  "amount" : 200078,
  "type" : "RECEIVER",
  "sender" : {
    "cardId" : "219834",
    "currency" : "PLN",
    "userId" : "613231"
  },
  "receiver" : {
    "userId" : 2345,
    "card" : "5495984179082645",
    "currency" : "PLN",
    "receiverType" : "BARE_CARD_NUMBER"
  }
}' | http --auth 'login:passwprd' POST 'http://localhost:8080/api/calculate-commission' \
    'Content-Type:application/json;charset=UTF-8'

1.2. Calculate currency rate

1.2.1. Request

GET /api/currency-rate/PLN/EUR HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Basic bG9naW46cGFzc3dwcmQ=
Host: localhost:8080

1.2.2. Request headers

Type

Value

Constraints

Description

Authorization

Basic bG9naW46YWNrbWU=

Required

Authentication header. Product login & password. Provided while integrating to API.

1.2.3. Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 61

{
  "lowerRate" : "0.2342887",
  "higherRate" : "0.2279948"
}

1.2.4. Response body

Path Type Description

lowerRate

String

Lower rate exchange

higherRate

String

Higher rate exchange

1.2.5. Examples

$ curl 'http://localhost:8080/api/currency-rate/PLN/EUR' -i -u 'login:passwprd' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'
$ http --auth 'login:passwprd' GET 'http://localhost:8080/api/currency-rate/PLN/EUR' \
    'Content-Type:application/json;charset=UTF-8'

1.3. Determine currency

1.3.1. Request

POST /api/determine-currency HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Basic bG9naW46cGFzc3dwcmQ=
Content-Length: 172
Host: localhost:8080

{
  "sender" : {
    "cardId" : "219754",
    "userId" : "512714"
  },
  "receiver" : {
    "card" : "444",
    "userId" : "12",
    "receiverType" : "WALLET_CARD_ID"
  }
}

1.3.2. Request headers

Type

Value

Constraints

Description

Authorization

Basic bG9naW46YWNrbWU=

Required

Authentication header. Product login & password. Provided while integrating to API.

1.3.3. Request fields

.

Path Type Constraints Description

sender

Object

Required

Sender

sender.cardId

String

Required

Card ID

sender.userId

String

Required

User ID

receiver

Object

Required

Receiver

receiver.userId

String

Optional

Receiver wallet user id. Required if receiverType = WALLET_CARD_ID

receiver.receiverType

String

Required

Receiver type. One of: {EMPTY, WALLET_CARD_ID, FRIEND_ID, BARE_CARD_NUMBER}

receiver.card

String

Required

Card data[bare card number, card id]. Depends of receiverType property

1.3.4. Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 148

{
  "senderDefaultCurrencies" : "PLN",
  "receiverDefaultCurrencies" : "PLN",
  "senderCurrencies" : [ "PLN" ],
  "receiverCurrencies" : [ "PLN" ]
}

1.3.5. Response body

Path Type Description

senderDefaultCurrencies

String

Sender Default Currencies

receiverDefaultCurrencies

String

Receiver Default Currencies

senderCurrencies

Array

Sender Currencies

receiverCurrencies

Array

Receiver Currencies

1.3.6. Examples

$ curl 'http://localhost:8080/api/determine-currency' -i -u 'login:passwprd' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "sender" : {
    "cardId" : "219754",
    "userId" : "512714"
  },
  "receiver" : {
    "card" : "444",
    "userId" : "12",
    "receiverType" : "WALLET_CARD_ID"
  }
}'
$ echo '{
  "sender" : {
    "cardId" : "219754",
    "userId" : "512714"
  },
  "receiver" : {
    "card" : "444",
    "userId" : "12",
    "receiverType" : "WALLET_CARD_ID"
  }
}' | http --auth 'login:passwprd' POST 'http://localhost:8080/api/determine-currency' \
    'Content-Type:application/json;charset=UTF-8'

1.4. Send Money

1.4.1. Request

POST /api/send-money HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Basic bG9naW46cGFzc3dwcmQ=
Accept-Language: en
Content-Length: 764
Host: localhost:8080

{
  "amount" : 1000,
  "cvc2" : "123",
  "type" : "RECEIVER",
  "addressIp" : "192.168.0.1",
  "sender" : {
    "currency" : "PLN",
    "expirationDate" : "03/20",
    "personalId" : "AGC688910",
    "cardId" : "219708",
    "userId" : "519558",
    "addressId" : "267"
  },
  "receiver" : {
    "firstName" : "Rob",
    "lastName" : "Wring",
    "currency" : "PLN",
    "card" : "219708",
    "displayName" : "displayName",
    "phoneNumber" : "48222111333",
    "receiverType" : "WALLET_CARD_ID",
    "userId" : "123"
  },
  "externalAuthentication" : {
    "authenticationId" : "authenticationId",
    "cavv" : "jEu04WZns7pbARAApU4qgNdJTag",
    "eci" : "02",
    "authenticationStatus" : "Y",
    "transactionXId" : "9742432a-dfdc-41ca-9ae9-b6595de65f1d"
  }
}

1.4.2. Request with external authentication

ONLY_AUTHENTICATION_ID
Listing 1. ExternalAuthentication.authenticationId
{
  "amount" : 1000,
  "cvc2" : "123",
  "type" : "RECEIVER",
  "addressIp" : "192.168.0.1",
  "sender" : {
    "currency" : "PLN",
    "expirationDate" : "03/20",
    "personalId" : "AGC688910",
    "cardId" : "219708",
    "userId" : "12345",
    "addressId" : "12345"
  },
  "receiver" : {
    "firstName" : "Rob",
    "lastName" : "Wring",
    "currency" : "PLN",
    "card" : "219708",
    "displayName" : "displayName",
    "phoneNumber" : "phoneNumber",
    "receiverType" : "WALLET_CARD_ID",
    "userId" : "123"
  },
  "externalAuthentication" : {
    "authenticationId" : "authenticationId"
  }
}
WITHOUT_AUTHENTICATION_ID
Listing 2. ExternalAuthentication.cavv, eci, transactionXId, authenticationStatus
{
  "amount" : 1000,
  "cvc2" : "123",
  "type" : "RECEIVER",
  "addressIp" : "192.168.0.1",
  "sender" : {
    "currency" : "PLN",
    "expirationDate" : "03/20",
    "personalId" : "AGC688910",
    "cardId" : "219708",
    "userId" : "12345",
    "addressId" : "12345"
  },
  "receiver" : {
    "firstName" : "Rob",
    "lastName" : "Wring",
    "currency" : "PLN",
    "card" : "219708",
    "displayName" : "displayName",
    "phoneNumber" : "phoneNumber",
    "receiverType" : "WALLET_CARD_ID",
    "userId" : "123"
  },
  "externalAuthentication" : {
    "cavv" : "jEu04WZns7pbARAApU4qgNdJTag",
    "eci" : "PLN",
    "authenticationStatus" : "Y",
    "transactionXId" : "9742432a-dfdc-41ca-9ae9-b6595de65f1d"
  }
}

1.4.3. Request headers

Type

Value

Constraints

Description

Authorization

Basic bG9naW46YWNrbWU=

Required

Authentication header. Product login & password. Provided while integrating to API.

Accept-Language

en

Optional

Header indicates the language that the client prefers. If you want to start using this header, contact your administrator

1.4.4. Request fields

.

Path Type Constraints Description

amount

Number

Required

Transaction amount

cvc2

String

Required

Card CVC

type

String

Required

SENDER or RECEIVER type transaction payer

addressIp

String

Required

Address Ip

sender

Object

Required

sender.currency

String

Required, Must match length: min = 3 max = 3

Transaction currency

sender.expirationDate

String

Required

Card expiration date

sender.personalId

String

Optional

Personal ID

sender.cardId

String

Required

Card ID

sender.userId

String

Required

User ID

sender.addressId

String

Conditional

Address ID. Required when one of field: sender.street, sender.houseNumber, sender.city, sender.postalCode, sender.flatNumber is null.

receiver

Object

Required

receiver.firstName

String

Required, Must match length: min = 2 max = 35, Must match pattern: "^[^0-9]+$", FirstName cannot be the same as lastName

First name

receiver.lastName

String

Required, Must match length: min = 2 max = 35, Must match pattern: "^[^0-9]+$", LastName cannot be the same as firstName

Last name

receiver.phoneNumber

String

Optional

Receiver phone number

receiver.displayName

String

Required

Display name

receiver.currency

String

Required, Must match length: min = 3 max = 3

Transaction currency

receiver.userId

String

Optional

Receiver wallet user id. Required if receiverType = FRIEND_ID

receiver.receiverType

String

Required

Receiver type. One of: [WALLET_CARD_ID, FRIEND_ID, BARE_CARD_NUMBER]

receiver.card

String

Required

Card data[bare card number, card id]. Depends of receiverType property

externalAuthentication

Object

Optional

External authentication object.

This parameter have 2 options:

Send authenticationId if Authentication process has been performed by this system.

Send remaining parameters (cavv, cavvAlgorithm, eci, transactionXId, authenticationStatus), but without authenticationId if authentication process was performed in another system.

externalAuthentication.authenticationId

String

Optional

Value returned from the Authentication process. Unique external authentication identifier.

externalAuthentication.cavv

String

Optional

This property is determined by the Access Control Server. This property will be valid if the TransactionStatus is "Y" or "A". The value may be used to provide proof of authentication.

externalAuthentication.eci

String

Optional

This property is determined by the Access Control Server. This property contains the two digit Electronic Commerce Indicator (ECI) value, which is to be submitted in a credit card authorization message. This value indicates to the processor that the customer data in the authorization message has been authenticated. The data contained within this property is only valid if the TransactionStatus is "Y" or "A".

externalAuthentication.authenticationStatus

String

Optional

Indicates whether a transaction qualifies as an authenticated transaction or account verification. Possible values are:

Y - Authentication/account verification successful

N - Not authenticated/account not verified; transaction denied

U - Authentication/account verification could not be performed; technical or other problem as indicated in ARes or RReq

A - Attempts processing performed; not authenticated/verified, but a proof of attempted authentication/verification is provided

C - Challenge required; additional authentication is required using the CReq/CRes

R - Authentication/account verification rejected; issuer is rejecting authentication/verification and request that authorization not be attempted

D - Challenge required; decoupled authentication confirmed

I - Informational only; 3DS Requestor challenge preference acknowledged

The CRes message can contain only a value of Y or N. Values of D and I are only applicable for 3DS version 2.2.0.

externalAuthentication.transactionXId

String

Optional

This field indicates the transactionXid from recurring finalize authentication.

1.4.5. Response

HTTP/1.1 200 OK
Location: /api/send-money/77787e10-bdf0-4488-ab22-70dd5875b7e9
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 56

{
  "orderId" : "77787e10-bdf0-4488-ab22-70dd5875b7e9"
}

1.4.6. Response body

Path Type Description

orderId

String

Transaction Id

1.4.7. Examples

$ curl 'http://localhost:8080/api/send-money' -i -u 'login:passwprd' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept-Language: en' \
    -d '{
  "amount" : 1000,
  "cvc2" : "123",
  "type" : "RECEIVER",
  "addressIp" : "192.168.0.1",
  "sender" : {
    "currency" : "PLN",
    "expirationDate" : "03/20",
    "personalId" : "AGC688910",
    "cardId" : "219708",
    "userId" : "519558",
    "addressId" : "267"
  },
  "receiver" : {
    "firstName" : "Rob",
    "lastName" : "Wring",
    "currency" : "PLN",
    "card" : "219708",
    "displayName" : "displayName",
    "phoneNumber" : "48222111333",
    "receiverType" : "WALLET_CARD_ID",
    "userId" : "123"
  },
  "externalAuthentication" : {
    "authenticationId" : "authenticationId",
    "cavv" : "jEu04WZns7pbARAApU4qgNdJTag",
    "eci" : "02",
    "authenticationStatus" : "Y",
    "transactionXId" : "9742432a-dfdc-41ca-9ae9-b6595de65f1d"
  }
}'
$ echo '{
  "amount" : 1000,
  "cvc2" : "123",
  "type" : "RECEIVER",
  "addressIp" : "192.168.0.1",
  "sender" : {
    "currency" : "PLN",
    "expirationDate" : "03/20",
    "personalId" : "AGC688910",
    "cardId" : "219708",
    "userId" : "519558",
    "addressId" : "267"
  },
  "receiver" : {
    "firstName" : "Rob",
    "lastName" : "Wring",
    "currency" : "PLN",
    "card" : "219708",
    "displayName" : "displayName",
    "phoneNumber" : "48222111333",
    "receiverType" : "WALLET_CARD_ID",
    "userId" : "123"
  },
  "externalAuthentication" : {
    "authenticationId" : "authenticationId",
    "cavv" : "jEu04WZns7pbARAApU4qgNdJTag",
    "eci" : "02",
    "authenticationStatus" : "Y",
    "transactionXId" : "9742432a-dfdc-41ca-9ae9-b6595de65f1d"
  }
}' | http --auth 'login:passwprd' POST 'http://localhost:8080/api/send-money' \
    'Content-Type:application/json;charset=UTF-8' \
    'Accept-Language:en'

1.5. Send Money Details

This method allow user to get transaction details using orderId. Parameter orderId is returned by method: Send Money

1.5.1. Request

GET /api/send-money/b2c59d77-7645-470a-b801-e3995700270f HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Basic bG9naW46cGFzc3dwcmQ=
Host: localhost:8080

1.5.2. Request headers

Type

Value

Constraints

Description

Authorization

Basic bG9naW46YWNrbWU=

Required

Authentication header. Product login & password. Provided while integrating to API.

1.5.3. Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 130

{
  "orderId" : "b2c59d77-7645-470a-b801-e3995700270f",
  "createdAt" : "2024-09-04T13:17:58.472469188Z",
  "status" : "SUCCESS"
}

1.5.4. Response body

Path Type Description

orderId

String

Transaction identifier

createdAt

String

Transaction creation date

status

String

Transaction status. One of: PENDING, FAILURE, SUCCESS

1.5.5. Examples

$ curl 'http://localhost:8080/api/send-money/b2c59d77-7645-470a-b801-e3995700270f' -i -u 'login:passwprd' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'
$ http --auth 'login:passwprd' GET 'http://localhost:8080/api/send-money/b2c59d77-7645-470a-b801-e3995700270f' \
    'Content-Type:application/json;charset=UTF-8'

1.6. Add Friend

1.6.1. Request

POST /api/wallet-users/1/friends HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Basic bG9naW46cGFzc3dwcmQ=
Content-Length: 207
Host: localhost:8080

{
  "friendWalletDataCoreId" : 1,
  "displayName" : "Display name",
  "phoneNumber" : "48999111222",
  "friendType" : "WALLET",
  "firstName" : "First",
  "lastName" : "Last",
  "cardNumber" : "4444000000"
}

1.6.2. Request headers

Type

Value

Constraints

Description

Authorization

Basic bG9naW46YWNrbWU=

Required

Authentication header. Product login & password. Provided while integrating to API.

1.6.3. Request fields

.

Path Type Constraints Description

friendWalletDataCoreId

Number

Optional

Friend wallet data core id

displayName

String

Required

Display name

phoneNumber

String

Required

Phone number

friendType

String

Required

Type of friend [WALLET, EXTERNAL]

firstName

String

Optional

First name

lastName

String

Optional

Last name

cardNumber

String

Optional

Card number

1.6.4. Response

HTTP/1.1 204 No Content
Content-Type: application/json
Location: /api/wallet-users/1/friends
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

1.6.5. Examples

$ curl 'http://localhost:8080/api/wallet-users/1/friends' -i -u 'login:passwprd' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "friendWalletDataCoreId" : 1,
  "displayName" : "Display name",
  "phoneNumber" : "48999111222",
  "friendType" : "WALLET",
  "firstName" : "First",
  "lastName" : "Last",
  "cardNumber" : "4444000000"
}'
$ echo '{
  "friendWalletDataCoreId" : 1,
  "displayName" : "Display name",
  "phoneNumber" : "48999111222",
  "friendType" : "WALLET",
  "firstName" : "First",
  "lastName" : "Last",
  "cardNumber" : "4444000000"
}' | http --auth 'login:passwprd' POST 'http://localhost:8080/api/wallet-users/1/friends' \
    'Content-Type:application/json;charset=UTF-8'

1.7. Get User friends list

1.7.1. Request

POST /api/wallet-users/1/friends HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Basic bG9naW46cGFzc3dwcmQ=
Content-Length: 207
Host: localhost:8080

{
  "friendWalletDataCoreId" : 1,
  "displayName" : "Display name",
  "phoneNumber" : "48999111222",
  "friendType" : "WALLET",
  "firstName" : "First",
  "lastName" : "Last",
  "cardNumber" : "4444000000"
}

1.7.2. Request headers

Type

Value

Constraints

Description

Authorization

Basic bG9naW46YWNrbWU=

Required

Authentication header. Product login & password. Provided while integrating to API.

1.7.3. Response

HTTP/1.1 204 No Content
Content-Type: application/json
Location: /api/wallet-users/1/friends
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

1.7.4. Response body

Path Type Description

friends

Array

friends[].friendId

Number

Id of Friend

friends[].firstName

String

Friend first name

friends[].lastName

String

Friend last name

friends[].displayName

String

Friend display name

friends[].phoneNumber

String

Friend phone number

friends[].lastFourDigits

String

Card last 4 digits. Empty for WALLET Friend type

friends[].bin

String

Card bin. Empty for WALLET Friend type

friends[].friendType

String

Type of friend [WALLET, EXTERNAL]

1.7.5. Examples

$ curl 'http://localhost:8080/api/wallet-users/1/friends' -i -u 'login:passwprd' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "friendWalletDataCoreId" : 1,
  "displayName" : "Display name",
  "phoneNumber" : "48999111222",
  "friendType" : "WALLET",
  "firstName" : "First",
  "lastName" : "Last",
  "cardNumber" : "4444000000"
}'
$ echo '{
  "friendWalletDataCoreId" : 1,
  "displayName" : "Display name",
  "phoneNumber" : "48999111222",
  "friendType" : "WALLET",
  "firstName" : "First",
  "lastName" : "Last",
  "cardNumber" : "4444000000"
}' | http --auth 'login:passwprd' POST 'http://localhost:8080/api/wallet-users/1/friends' \
    'Content-Type:application/json;charset=UTF-8'

1.8. Update Friend

1.8.1. Request

PUT /api/wallet-users/1/friends/24 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Basic bG9naW46cGFzc3dwcmQ=
Content-Length: 151
Host: localhost:8080

{
  "phoneNumber" : "48999000111",
  "firstName" : "First",
  "lastName" : "Last",
  "displayName" : "Display name",
  "cardNumber" : "4440000444040"
}

1.8.2. Request headers

Type

Value

Constraints

Description

Authorization

Basic bG9naW46YWNrbWU=

Required

Authentication header. Product login & password. Provided while integrating to API.

1.8.3. Request fields

.

Path Type Constraints Description

displayName

String

Required

Display name

phoneNumber

String

Required

Phone number

firstName

String

Optional

First name

lastName

String

Optional

Last name

cardNumber

String

Optional

Card number

1.8.4. Response

HTTP/1.1 204 No Content
Content-Type: application/json
Location: /api/wallet-users/1/friends/24
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

1.8.5. Examples

$ curl 'http://localhost:8080/api/wallet-users/1/friends/24' -i -u 'login:passwprd' -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "phoneNumber" : "48999000111",
  "firstName" : "First",
  "lastName" : "Last",
  "displayName" : "Display name",
  "cardNumber" : "4440000444040"
}'
$ echo '{
  "phoneNumber" : "48999000111",
  "firstName" : "First",
  "lastName" : "Last",
  "displayName" : "Display name",
  "cardNumber" : "4440000444040"
}' | http --auth 'login:passwprd' PUT 'http://localhost:8080/api/wallet-users/1/friends/24' \
    'Content-Type:application/json;charset=UTF-8'

1.9. Delete Friend

1.9.1. Request

DELETE /api/wallet-users/1/friends/24 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Basic bG9naW46cGFzc3dwcmQ=
Host: localhost:8080

1.9.2. Request headers

Type

Value

Constraints

Description

Authorization

Basic bG9naW46YWNrbWU=

Required

Authentication header. Product login & password. Provided while integrating to API.

1.9.3. Response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

1.9.4. Examples

$ curl 'http://localhost:8080/api/wallet-users/1/friends/24' -i -u 'login:passwprd' -X DELETE \
    -H 'Content-Type: application/json;charset=UTF-8'
$ http --auth 'login:passwprd' DELETE 'http://localhost:8080/api/wallet-users/1/friends/24' \
    'Content-Type:application/json;charset=UTF-8'

1.10. Active Accounts

Method used to find users with valid mc card type (not expired, strong verified). Response will contain phone numbers with user and card identifiers. Users without accepted TOS or without valid MC card will not be returned in response. If user has multiple cards that match criteria response will contain only user’s default card id.

1.10.1. Request

POST /api/active-accounts HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Basic bG9naW46cGFzc3dwcmQ=
Content-Length: 56
Host: localhost:8080

{
  "phoneNumbers" : [ "487973296001", "48795005005" ]
}

1.10.2. Request headers

Type

Value

Constraints

Description

Authorization

Basic bG9naW46YWNrbWU=

Required

Authentication header. Product login & password. Provided while integrating to API.

1.10.3. Request fields

.

Path Type Constraints Description

phoneNumbers

Array

Required, Size must be between 1 and 100 inclusive

This array contains phone numbers that each identify a users

1.10.4. Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 160

[ {
  "phoneNumber" : "48797001002",
  "userId" : 311957,
  "cardId" : 226794
}, {
  "phoneNumber" : "48795005005",
  "userId" : 111944,
  "cardId" : 326097
} ]

1.10.5. Response body

Path Type Description

[].phoneNumber

String

Phone number

[].userId

Number

User identifier

[].cardId

Number

Card identifier

1.10.6. Examples

$ curl 'http://localhost:8080/api/active-accounts' -i -u 'login:passwprd' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "phoneNumbers" : [ "487973296001", "48795005005" ]
}'
$ echo '{
  "phoneNumbers" : [ "487973296001", "48795005005" ]
}' | http --auth 'login:passwprd' POST 'http://localhost:8080/api/active-accounts' \
    'Content-Type:application/json;charset=UTF-8'

2. Authentication

Every single method should contains Authorization and Mobile-Product headers.

2.1. Init Authentication

The authentication stage flow is indicated by the following field: threeDsMode

Method allows us to do initialize authentication using ThreeDs 2.0 protocol.

After this method you have 3 options:

  • FRICTIONLESS - In response: authenticationStatus, transactionXId, cavv, eci and threeDsMode = FRICTIONLESS are present. This response denotes that authentication was finished.

  • ThreeDsMethod flow - In response: threeDsMethodData and threeDsMode = THREE_DS_METHOD are present. This response denotes that you should perform 3DS method flow. After executing ThreeDs method flow, make a request for the method: Continue Authentication

  • CHALLENGE - In response: acsUrl, creq, challengeHtmlFormBase64 and threeDsMode = CHALLENGE are present. This response denotes that you should perform challenge. After executing challenge, make a request for the method: Finalize Authentication

2.1.1. Request headers

Type

Value

Constraints

Description

Authorization

Basic bG9naW46YWNrbWU=

Required

Authentication header. Product login & password. Provided while integrating to API.

2.1.2. Request

POST /api/authentication/v2/init HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Basic bG9naW46cGFzc3dwcmQ=
Content-Length: 649
Host: localhost:8080

{
  "authenticationId" : "authenticationId",
  "amount" : 1000,
  "currency" : "PLN",
  "userId" : "519608",
  "cardId" : "219708",
  "browserDetails" : {
    "browserIp" : "281.123.0.1",
    "language" : "PL",
    "javaEnabled" : "true",
    "jsEnabled" : "true",
    "screenColorDepth" : "32",
    "screenHeight" : "1500",
    "screenWidth" : "1500",
    "timezoneOffset" : "60",
    "userAgent" : "Mozzila",
    "acceptHeader" : "*"
  },
  "requestChallengeIndicator" : "NO_PREFERENCE",
  "threeDsMethodNotificationUrl" : "https://webhook.verestro.com",
  "challengeUrl" : "https://notification.verestro.com",
  "authenticationType" : "PAYMENT"
}

2.1.3. Request fields

.

Path Type Constraints Description

authenticationId

String

Required

Unique authentication identifier per Product

amount

Number

Required

Authentication amount

currency

String

Required

Authentication currency (for example "PLN", "USD")

userId

String

Required

Sender wallet user id.

cardId

String

Required

Wallet cardId belongs to sender account

browserDetails

Object

Required

browserDetails.browserIp

String

Optional

Address IP of the order of authentication

browserDetails.language

String

Required, Must match length: min = 1 max = 35

This field contains the cardholder’s browser language as defined in IETF BCP 47

browserDetails.javaEnabled

String

Required

This field contains a value representing the ability of the cardholder’s browser to execute Java.

browserDetails.jsEnabled

String

Required

This field contains a value representing the ability of the cardholder’s browser to execute JavaScript

browserDetails.screenColorDepth

String

Required

This field contains a value representing the bit depth of the color palette, in bits per pixel, for displaying images. Obtained from Cardholder browser using the screen.colorDepth property. Values accepted:

1 = 1 bit,

4 = 4 bits,

8 = 8 bits,

15 = 15 bits,

16 = 16 bits,

24 = 24 bits,

32 = 32 bits,

48 = 48 bits

browserDetails.screenHeight

String

Required, Must match pattern: "^[0-9]{1,6}$"

This field contains the total height of the cardholder’s screen in pixels

browserDetails.screenWidth

String

Required, Must match pattern: "^[0-9]{1,6}$"

This field contains the total width of the cardholder’s screen in pixels

browserDetails.timezoneOffset

String

Required, Must match pattern: "^[+-]?[0-9]{1,4}$"

This field contains the difference between UTC time and the cardholder’s browser local time in minutes

browserDetails.userAgent

String

Required

This field contains the exact content of the HTTP User-Agent header.

browserDetails.acceptHeader

String

Required

This field contains the exact content of the HTTP accept header as sent to the merchant from the cardholder’s user agent. This field is required only if the cardholder’s user agent supplied a value. e.g Accept: application/json

requestChallengeIndicator

String

Required

Indicates whether a challenge is requested for this transaction. For authenticationType QUASI_CASH, PAYMENT possible values are: NO_PREFERENCE, CHALLENGE_NOT_REQUESTED, CHALLENGE_REQUESTED_MANDATE, CHALLENGE_PREFER_BY_REQUESTOR_3DS

For authenticationType ADD_CARD, VERIFY_CARDHOLDER, INSTALLMENT_PAYMENT, COF_INITIAL, RECURRING_INITIAL possible values are: CHALLENGE_REQUESTED_MANDATE, CHALLENGE_PREFER_BY_REQUESTOR_3DS

threeDsMethodNotificationUrl

String

Required

This field specifies the URL to which the ACS will post threeDsMethodData when the hidden iframe post form from browse

challengeUrl

String

Required

This property specifies the URL to which the final challenge response is POSTed.

authenticationType

String

Required

Authentication Type configuration prepared for specific type. Possible values are:

Non payment authentication - Identity verification and account confirmation: ADD_CARD, VERIFY_CARDHOLDER

Payment authentication - Cardholder authentication during an e-commerce transaction: QUASI_CASH, PAYMENT, COF_INITIAL, INSTALLMENT_PAYMENT, RECURRING_INITIAL

3DS Requestor Initiated (only for protocolVersion 2.2.0) - Confirmation of account information and Cardholder authentication with no direct Cardholder present. For example, a subscription-based e-commerce merchant confirming that an account is still valid: MOTO, RECURRING_SUBSEQUENT

2.1.4. Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 331

{
  "authenticationId" : "authenticationId",
  "threeDsMethodData" : "eyJ0aHJlZURT=Tm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly93ZWJob29rLnNpdGUvc3M=VydmVyVHJhbnNJRCI6IjNmZmU2NjAyLTVkN2=4ODZlLWRhM2ZiMDkwYTJiZCJ9",
  "threeDsMethodUrl" : "https://threeDsMethodNotificationUrl-test.verestro.com/acs-mock",
  "threeDsMode" : "THREE_DS_METHOD"
}

2.1.5. Response fields

Path

Type

Description

authenticationId

String

Unique authentication identifier

threeDsMethodData

String

Encoded data used for request to ACS

threeDsMethodUrl

String

ACS endpoint for hidden request. If endpoint is not present then request is not required.

authenticationStatus

String

Indicates whether a transaction qualifies as an authenticated transaction or account verification. Possible values are:

Y - Authentication/account verification successful

N - Not authenticated/account not verified; transaction denied

U - Authentication/account verification could not be performed; technical or other problem as indicated in ARes or RReq

A - Attempts processing performed; not authenticated/verified, but a proof of attempted authentication/verification is provided

C - Challenge required; additional authentication is required using the CReq/CRes

R - Authentication/account verification rejected; issuer is rejecting authentication/verification and request that authorization not be attempted

D - Challenge required; decoupled authentication confirmed

I - Informational only; 3DS Requestor challenge preference acknowledged

The CRes message can contain only a value of Y or N. Values of D and I are only applicable for ThreeDs version 2.2.0.

transactionXId

String

This field indicates the transactionXid from recurring initial authentication.

cavv

String

This property is determined by the Access Control Server. This property will be valid if the TransactionStatus is "Y" or "A". The value may be used to provide proof of authentication.

eci

String

This property is determined by the Access Control Server. This property contains the two digit Electronic Commerce Indicator (ECI) value, which is to be submitted in a credit card authorization message. This value indicates to the processor that the customer data in the authorization message has been authenticated. The data contained within this property is only valid if the TransactionStatus is "Y" or "A".

acsUrl

String

If challenge is required, data for building a form such as challengeHtmlFormBase64

creq

String

If challenge is required, data for building a form such as challengeHtmlFormBase64

challengeHtmlFormBase64

String

This field is a BASE64 encrypted html source file containing the challenge 3-D Secure frame

threeDsSessionData

String

threeDsSessionData value

threeDsMode

String

threeDs process mode which informs about. One of: [FRICTIONLESS, THREE_DS_METHOD, CHALLENGE]

FRICTIONLESS - this is where the authentication process was finished.

THREE_DS_METHOD - next step is to execute the ThreeDs method process. After it is done, we need to make a request to the method: Continue Authentication

CHALLENGE - next step is to execute the challenge process. After it is done, we need to make a request to the method: Finalize Authentication

2.1.6. Success Response body Examples

FRICTIONLESS
Listing 3. threeDsMode = FRICTIONLESS
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

{
    "authenticationId": "authenticationId",
    "authenticationStatus": "Y",
    "transactionXId": "9742432a-dfdc-41ca-9ae9-b6595de65f1d",
    "cavv": "jEu04WZns7pbARAApU4qgNdJTag",
    "eci": "02",
    "threeDsMode": "FRICTIONLESS"
}
THREE_DS_METHOD
Listing 4. threeDsMode = THREE_DS_METHOD
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

{
    "authenticationId": "authenticationId",
    "threeDsMethodData": "eyJ0aHJlZURWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly93ZWJob29rLnNpdGUvc3MiLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNmYWYwZjFZi1iYjQyLThkN2RhM2M0NjY5OSJ9",
    "threeDsMethodUrl": "https://threeDsMethodUrl-test.verestro.com/acs-mock",
    "threeDsMode": "THREE_DS_METHOD"
}
CHALLENGE
Listing 5. threeDsMode = CHALLENGE
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

{
    "authenticationId": "authenticationId",
    "acsUrl": "https://acs-url.verestro.com/mock-acs",
    "creq": "eyJjYXJkQXV0aGVudGljYNmODlhLTk2MjQtNGQ1OS04NzZmLTNkMWViYTcyNzM3NiIsIm5vdGlmaWNhdGlvblVybvd2ViaG9vay5zaXRlLzE5ODI3MWMyLTljYWYtNGEyMy05ZGJiLWRlZTc3ODExMDdlOSIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiM2ZhZjBmMWQtM2YxNy00MTJmLWJiNDItOGQ3ZGEzYzQ2Njk5IiwibWVzc2FnZVZlcnNpb24iOiIyLjEuMCJ9",
    "challengeHtmlFormBase64": "PGh0bWw+PFNDUklQVCBMQU5mF2YXNjcmlwdCI+ZnVuY3Rpb24gT25Mb2FkRXZlbW1lbnQuZG93bmxvYWRGb3JtLnN1Ym1pdCgpOyB9PC9TQ1JJUFQ+PGJvZHkgT25Mb2FkmVudCgpOyI+PGZvcm0gbmFtZT0iZG93bmxvYWRGb3JtIiBhY3Rpb249Imh0dHBzOi8vbXBpLXN0YWdpbmcuZmVuaWdlLnBsL21vY2stYWNzIiBtZXRob2Q9IlBPU1QiPjxJTlBVVCB0eXBlPSJoaWRkZW4iXEiIHZhbHVlPSJleUpqWVhKa1FYVjBhR1Z1ZEdsallYUnBiMjVKWkNJNkltRmpZbU5tT0RsaExUazJNalF0TkdRMU9TMDROelptTFROa01XVmlZVGN5TnpNM05pSXNJbTV2ZEdsbWFXTmhkR2x2YmxWeWJDSTZJbWgwZEhCek9pOHZkMlZpYUc5dmF5NXphWFJsTHpFNU9ESTNNV015TFRsallXWXROR0V5TXkwNVpHSmlMV1JsWlRjM09ERXhNRGRsT1NJc0luUm9jbVZsUkZOVFpYSjJaWEpVY21GdWMwbEVJam9pTTJaaFpqQm1NV1F0TTJZeE55MDBNVEptTFdKaU5ESXRPR1EzWkdFell6UTJOams1SWl3aWJXVnpjMkZuWlZabGNuTnBiMjRpT2lJeUxqRXVNQ0o5Ij48SU5QVVQgdHlwZT0iaGlkZGVuIiBuYW1lPSJ0aHJlZURTU2Vzc2lvbkRhdGEiIHZhbHVlPSJZV05pWTJZNE9XRXRPVFl5TkMwMFpEVTVMVGczTm1ZdE0yUXhaV0poTnpJM016YzIiPjwvZm9ybT48L2JvZHk+PC9odG1sPg==",
    "threeDsSessionData": "YWNiY2Y4OWEtONC00ZDU5LTg3NmYtM2QxZWJhNzI3Mzc2",
    "threeDsMode": "CHALLENGE"
}

2.1.7. Examples

$ curl 'http://localhost:8080/api/authentication/v2/init' -i -u 'login:passwprd' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "authenticationId" : "authenticationId",
  "amount" : 1000,
  "currency" : "PLN",
  "userId" : "519608",
  "cardId" : "219708",
  "browserDetails" : {
    "browserIp" : "281.123.0.1",
    "language" : "PL",
    "javaEnabled" : "true",
    "jsEnabled" : "true",
    "screenColorDepth" : "32",
    "screenHeight" : "1500",
    "screenWidth" : "1500",
    "timezoneOffset" : "60",
    "userAgent" : "Mozzila",
    "acceptHeader" : "*"
  },
  "requestChallengeIndicator" : "NO_PREFERENCE",
  "threeDsMethodNotificationUrl" : "https://webhook.verestro.com",
  "challengeUrl" : "https://notification.verestro.com",
  "authenticationType" : "PAYMENT"
}'

2.2. Continue Authentication

The authentication stage flow is indicated by the following field: threeDsMode

Method allows us to do continue authentication using ThreeDs 2.0 protocol. Use this method after perform process ThreeDsMethod. This step is optional in the authentication process. Required only if ThreeDsMethod case is present.

After this method you have 2 options:

  • FRICTIONLESS - In response: authenticationStatus, transactionXId, cavv, eci and threeDsMode = FRICTIONLESS are present. This response denotes that authentication was finished.

  • CHALLENGE - In response: acsUrl, creq, challengeHtmlFormBase64 and threeDsMode = CHALLENGE are present. This response denotes that you should perform challenge. After executing challenge, make a request for the method: Finalize Authentication

2.2.1. Request headers

Type

Value

Constraints

Description

Authorization

Basic bG9naW46YWNrbWU=

Required

Authentication header. Product login & password. Provided while integrating to API.

2.2.2. Request

POST /api/authentication/v2/continue HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Basic bG9naW46cGFzc3dwcmQ=
Content-Length: 105
Host: localhost:8080

{
  "authenticationId" : "authenticationId",
  "userId" : "519608",
  "methodCompletionIndicator" : "Y"
}

2.2.3. Request fields

.

Path Type Constraints Description

authenticationId

String

Required

Unique authentication identifier per Product

userId

String

Required

Sender wallet user id.

methodCompletionIndicator

String

Required

Possible values:

Y - if response from hidden form from Pre Authentication is under 10s,

N - if response from hidden form from Pre Authentication is over 10s,

U - if threeDsMethodNotificationUrl is empty

2.2.4. Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 230

{
  "authenticationId" : "authenticationId",
  "authenticationStatus" : "Y",
  "transactionXId" : "9742432a-dfdc-41ca-9ae9-b6595de65f1d",
  "cavv" : "jEu04WZns7pbARAApU4qgNdJTag",
  "eci" : "02",
  "threeDsMode" : "FRICTIONLESS"
}

2.2.5. Response fields

Path

Type

Description

authenticationId

String

Unique authentication identifier

authenticationStatus

String

Indicates whether a transaction qualifies as an authenticated transaction or account verification. Possible values are:

Y - Authentication/account verification successful

N - Not authenticated/account not verified; transaction denied

U - Authentication/account verification could not be performed; technical or other problem as indicated in ARes or RReq

A - Attempts processing performed; not authenticated/verified, but a proof of attempted authentication/verification is provided

C - Challenge required; additional authentication is required using the CReq/CRes

R - Authentication/account verification rejected; issuer is rejecting authentication/verification and request that authorization not be attempted

D - Challenge required; decoupled authentication confirmed

I - Informational only; ThreeDs Requestor challenge preference acknowledged

The CRes message can contain only a value of Y or N. Values of D and I are only applicable for ThreeDs version 2.2.0.

transactionXId

String

This field indicates the transactionXid from recurring initial authentication.

cavv

String

This property is determined by the Access Control Server. This property will be valid if the TransactionStatus is "Y" or "A". The value may be used to provide proof of authentication.

eci

String

This property is determined by the Access Control Server. This property contains the two digit Electronic Commerce Indicator (ECI) value, which is to be submitted in a credit card authorization message. This value indicates to the processor that the customer data in the authorization message has been authenticated. The data contained within this property is only valid if the TransactionStatus is "Y" or "A".

acsUrl

String

If challenge is required, data for building a form such as challengeHtmlFormBase64

creq

String

If challenge is required, data for building a form such as challengeHtmlFormBase64

challengeHtmlFormBase64

String

This field is a BASE64 encrypted html source file containing the challenge 3-D Secure frame

threeDsSessionData

String

threeDsSessionData value

threeDsMode

String

ThreeDs process mode which informs about. One of: [FRICTIONLESS, CHALLENGE]

FRICTIONLESS - this is where the authentication process was finished.

CHALLENGE - next step is to execute the challenge process. After it is done, we need to make a request to the method: Finalize Authentication

2.2.6. Success Response body Examples

FRICTIONLESS
Listing 6. threeDsMode = FRICTIONLESS
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

{
    "authenticationId": "authenticationId",
    "authenticationStatus": "Y",
    "transactionXId": "9742432a-dfdc-41ca-9ae9-b6595de65f1d",
    "cavv": "jEu04WZns7pbARAApU4qgNdJTag",
    "eci": "02",
    "threeDsMode": "FRICTIONLESS"
}
CHALLENGE
Listing 7. threeDsMode = CHALLENGE
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

{
    "authenticationId": "authenticationId",
    "acsUrl": "https://acs-url.verestro.com/mock-acs",
    "creq": "eyJjYXJkQXV0aGVudGljYNmODlhLTk2MjQtNGQ1OS04NzZmLTNkMWViYTcyNzM3NiIsIm5vdGlmaWNhdGlvblVybvd2ViaG9vay5zaXRlLzE5ODI3MWMyLTljYWYtNGEyMy05ZGJiLWRlZTc3ODExMDdlOSIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiM2ZhZjBmMWQtM2YxNy00MTJmLWJiNDItOGQ3ZGEzYzQ2Njk5IiwibWVzc2FnZVZlcnNpb24iOiIyLjEuMCJ9",
    "challengeHtmlFormBase64": "PGh0bWw+PFNDUklQVCBMQU5mF2YXNjcmlwdCI+ZnVuY3Rpb24gT25Mb2FkRXZlbW1lbnQuZG93bmxvYWRGb3JtLnN1Ym1pdCgpOyB9PC9TQ1JJUFQ+PGJvZHkgT25Mb2FkmVudCgpOyI+PGZvcm0gbmFtZT0iZG93bmxvYWRGb3JtIiBhY3Rpb249Imh0dHBzOi8vbXBpLXN0YWdpbmcuZmVuaWdlLnBsL21vY2stYWNzIiBtZXRob2Q9IlBPU1QiPjxJTlBVVCB0eXBlPSJoaWRkZW4iXEiIHZhbHVlPSJleUpqWVhKa1FYVjBhR1Z1ZEdsallYUnBiMjVKWkNJNkltRmpZbU5tT0RsaExUazJNalF0TkdRMU9TMDROelptTFROa01XVmlZVGN5TnpNM05pSXNJbTV2ZEdsbWFXTmhkR2x2YmxWeWJDSTZJbWgwZEhCek9pOHZkMlZpYUc5dmF5NXphWFJsTHpFNU9ESTNNV015TFRsallXWXROR0V5TXkwNVpHSmlMV1JsWlRjM09ERXhNRGRsT1NJc0luUm9jbVZsUkZOVFpYSjJaWEpVY21GdWMwbEVJam9pTTJaaFpqQm1NV1F0TTJZeE55MDBNVEptTFdKaU5ESXRPR1EzWkdFell6UTJOams1SWl3aWJXVnpjMkZuWlZabGNuTnBiMjRpT2lJeUxqRXVNQ0o5Ij48SU5QVVQgdHlwZT0iaGlkZGVuIiBuYW1lPSJ0aHJlZURTU2Vzc2lvbkRhdGEiIHZhbHVlPSJZV05pWTJZNE9XRXRPVFl5TkMwMFpEVTVMVGczTm1ZdE0yUXhaV0poTnpJM016YzIiPjwvZm9ybT48L2JvZHk+PC9odG1sPg==",
    "threeDsSessionData": "YWNiY2Y4OWEtONC00ZDU5LTg3NmYtM2QxZWJhNzI3Mzc2",
    "threeDsMode": "CHALLENGE"
}

2.2.7. Examples

$ curl 'http://localhost:8080/api/authentication/v2/continue' -i -u 'login:passwprd' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "authenticationId" : "authenticationId",
  "userId" : "519608",
  "methodCompletionIndicator" : "Y"
}'

2.3. Finalize Authentication

Method allows us to do finalize authentication using ThreeDs 2.0 protocol.

2.3.1. Request headers

Type

Value

Constraints

Description

Authorization

Basic bG9naW46YWNrbWU=

Required

Authentication header. Product login & password. Provided while integrating to API.

2.3.2. Request

POST /api/authentication/v2/finalize HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Basic bG9naW46cGFzc3dwcmQ=
Content-Length: 68
Host: localhost:8080

{
  "authenticationId" : "authenticationId",
  "userId" : "519608"
}

2.3.3. Request fields

.

Path Type Constraints Description

authenticationId

String

Required

Unique authentication identifier per Product

userId

String

Required

Sender wallet user id.

2.3.4. Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 196

{
  "authenticationId" : "authenticationId",
  "authenticationStatus" : "Y",
  "transactionXId" : "9742432a-dfdc-41ca-9ae9-b6595de65f1d",
  "cavv" : "jEu04WZns7pbARAApU4qgNdJTag",
  "eci" : "02"
}

2.3.5. Response fields

Path

Type

Description

authenticationId

String

Unique authentication identifier

authenticationStatus

String

Indicates whether a transaction qualifies as an authenticated transaction or account verification. Possible values are:

Y - Authentication/account verification successful

N - Not authenticated/account not verified; transaction denied

U - Authentication/account verification could not be performed; technical or other problem as indicated in ARes or RReq

A - Attempts processing performed; not authenticated/verified, but a proof of attempted authentication/verification is provided

C - Challenge required; additional authentication is required using the CReq/CRes

R - Authentication/account verification rejected; issuer is rejecting authentication/verification and request that authorization not be attempted

D - Challenge required; decoupled authentication confirmed

I - Informational only; ThreeDs Requestor challenge preference acknowledged

The CRes message can contain only a value of Y or N. Values of D and I are only applicable for ThreeDs version 2.2.0.

transactionXId

String

This field indicates the transactionXid from recurring initial authentication.

cavv

String

This property is determined by the Access Control Server. This property will be valid if the TransactionStatus is "Y" or "A". The value may be used to provide proof of authentication.

eci

String

This property is determined by the Access Control Server. This property contains the two digit Electronic Commerce Indicator (ECI) value, which is to be submitted in a credit card authorization message. This value indicates to the processor that the customer data in the authorization message has been authenticated. The data contained within this property is only valid if the TransactionStatus is "Y" or "A".

2.3.6. Success Response body Examples

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 196

{
  "authenticationId" : "authenticationId",
  "authenticationStatus" : "Y",
  "transactionXId" : "9742432a-dfdc-41ca-9ae9-b6595de65f1d",
  "cavv" : "jEu04WZns7pbARAApU4qgNdJTag",
  "eci" : "02"
}

2.3.7. Examples

$ curl 'http://localhost:8080/api/authentication/v2/finalize' -i -u 'login:passwprd' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "authenticationId" : "authenticationId",
  "userId" : "519608"
}'