Technical Documentation API

Money Transfer Hub provides possibility to process Person-2-Person and Person-2-Merchant transactions in various forms. Please check details in the below documentation.

This documentation contains the methods for mobile-server integration. The methods included in the documentation are intended for Customers creating their own mobile SDK.

The Customer creating the SDK must also remember about the integration with the MobileDC component.

Receiver types which can be used to set Receiver.Type

Based on ReceiverType user can fill different field in Receiver object in requests.

ReceiverType	Description
BARE_CARD_NUMBER	Bare card number in Receiver.card field
FRIEND_ID	Should pass FriendId in Receiver.Card field
WALLET_CARD_ID	Should pass DataCoreCardId to Receiver.Card field and UserDataCoreCardId to Receiver.userId field
EMPTY	Means that the receiver have the same card data like sender. This type may be useful on Determine Currency

JWE

Peer To Peer Transaction Service supports encryption of requests and responses as standard JSON Web Encryption (JWE) per RFC 7516.

Recommended to read the JWE standard: RFC 7516.

Methods that support request encryption in the JWE standard are tagged in the documentation with the header: Content-Type:application/x-jwe-encryption-body+json. If the response is to be encrypted with the JWE standard then the header must be added: X-Encryption-Public-Key with the public key.

Processing requests and responses can be divided into 4 options listed below:

1. Base request → Base response - the following headers should be provided to pass this case:

   • Content-Type: application/json

2. Base request → Encrypted response - the following headers should be provided to pass this case:

   • Content-Type: application/json
     

3. Encrypted request → Base response - the following headers should be provided to pass this case:

   • Content-Type: application/x-jwe-encryption-body+json

4. Encrypted request → Encrypted response - the following headers should be provided to pass this case:

   • Content-Type: application/x-jwe-encryption-body+json
     

Overview

JWE represents encrypted content using JSON data structures and Base64 encoding. The representation consists of three parts: a JWE Header, a encrypted payload, and a signature. The three parts are serialized to UTF-8 bytes, then encoded using base64url encoding. The JWE’s header, payload, and signature are concatenated with periods (.).

JWE typically takes the following form:

{Base64 encoded header}.{Base64 encoded payload}.{Base64 encoded signature}

JWE header contains:

Type	Value	Constraints	Description
alg	RSA-OAEP-256	Required	Identifies the cryptographic algorithm used to secure the JWE Encrypted Key. Supported algorithms: RSA-OAEP-256, RSA-OAEP-384, RSA-OAEP-512. Recommend value: RSA-OAEP-256.
enc	A256GCM	Required	Identifies the cryptographic algorithm used to secure the payload. Supported algorithms: A128GCM, A192GCM, A256GCM, A128CBC-HS256, A192CBC-HS384, A256CBC-HS512. Recommend value: A256GCM.
typ	JOSE	Optional	Identifies the type of encrypted payload. Recommend value: JOSE.
iat	1637929226	Optional	Identifies the time of generation of the JWT token. Supported date format: unix time in UTC. In the case of iat send, the validity of JWE is validated. Recommend send the header due to the increase in the security level.
kid	5638742a5094327fcd7a5945d06a45a9d83e9006	Optional	Identifies the public key of use to encrypt payload. Supported format: SHA-1 value of the public key. In the case of kid send, the validity of public key is validated, so we can inform the client that the public key has changed.

Payload Encryption

Every encrypted request should include JWE token. The jwe token should be passed in the field: value.

In case of problems with the implementation of JWE, please contact the administrator.

To prepare the encrypted payload:

The steps may differ depending on the libraries used.

1. Get the public key using the method: [???](#Get publicKey). The public key is encoded with Base64.

2. Decode the public key.

3. Then create a correct object to be encrypted.

4. Encrypt the created object with the public key.

5. Create JWE header compatible with: JWE Header

6. Make a request on the method that supports JWE. Set the JWE token in the field: value. Methods supporting JWE use the following header: Content-Type:application/x-jwe-encryption-body+json.

Payload Decryption

To prepare the decrypted payload:

The steps may differ depending on the libraries used.

The cryptographic algorithm used to secure the payload is: A256GCM, while to secure the encrypted JWE key: RSA-OAEP-256.

1. For the response to be encrypted you need to send public key in the header: X-Encryption-Public-Key. The header value must be encoded Base64.

2. After receiving the response, you should get the JWE token from the field: value.

3. Decrypt the JWE token from the field: value with the private key.

Public key format to be encoded in Base64.

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0IDAQAB...
-----END PUBLIC KEY-----

P2P

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

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.

Request

POST /mobile-api/active-accounts HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Mobile eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJiNjUzNGJhIiwiZXhwIjoxNjUxNzU2Njk4fQ.tBs5Os24ux-zmYNGYx5MCRAIYOg4Wtnu51NGs39doZ0
Product-Name: TestProduct
Content-Length: 56
Host: localhost:8080

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

Request headers

Request body with header: X-Encryption-Public-Key

Type	Value	Constraints	Description
Authorization	Mobile bG9naW46YWNrbWU=	Required	Device token with "Mobile " prefix
Product-Name	TestProduct	Required	Application product name
Content-Type	application/x-jwe-encryption-body+json	Optional	Header must be present if the request body is encrypted using the JWE standard.
X-Encryption-Public-Key		Optional	Header must be present if the response body is to be encrypted using the JWE standard. Public key must be encoded Base64.

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

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

Error response - ERROR_VALIDATION.

HTTP/1.1 400 BAD REQUEST
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

{
    "traceId": "{{traceId}}",
    "errorStatus": "ERROR_VALIDATION",
    "message": "Some fields are invalid",
    "data": [
        {
            "field": "{{field_name_from_request}}",
            "message": "{{message}}"
        }
    ]
}

Error response - ERROR_BAD_TOKEN.

HTTP/1.1 400 BAD REQUEST
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

{
    "traceId": "{{traceId}}",
    "errorStatus": "ERROR_BAD_TOKEN"
}

Error response - PRODUCT_NOT_FOUND.

HTTP/1.1 404 NOT FOUND
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

{
    "traceId": "{{traceId}}",
    "errorStatus": "PRODUCT_NOT_FOUND",
    "message": "Product by name {{product_name}} not found."
}

Error response - INTERNAL_SERVER_ERROR.

HTTP/1.1 500 INTERNAL SERVER ERROR
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

{
    "traceId": "{{traceId}}",
    "errorStatus": "INTERNAL_SERVER_ERROR"
}

Response fields

Path	Type	Description
[].phoneNumber	String	Phone number
[].userId	Number	User identifier
[].cardId	Number	Card identifier

Errors

Encrypted response fields when sent header: X-Encryption-Public-Key

Http Status	Error Status	Description
400 - Bad Request	ERROR_VALIDATION	Some fields are invalid
400 - Bad Request	ERROR_BAD_TOKEN	Invalid authorization token
400 - Bad Request	CRYPTOGRAPHY_ERROR	Error decoding public key has sent in header: X-Encryption-Public-Key
400 - Bad Request	CRYPTOGRAPHY_ERROR	Error on decrypting request
400 - Bad Request	CRYPTOGRAPHY_ERROR	Error on encrypting response
400 - Bad Request	CRYPTOGRAPHY_ERROR	JWE encryption Key is invalid
400 - Bad Request	CRYPTOGRAPHY_ERROR	JWE payload is expired
400 - Bad Request	INVALID_PHONE_NUMBERS	Phone numbers has incorrect format
404 - Not Found	PRODUCT_NOT_FOUND	Product not found based on sent header: Product-Name
500 - Internal Server Error	INTERNAL_SERVER_ERROR	Internal application error

Determine currency

Request body with header: X-Encryption-Public-Key.

Method is used to determine currencies applied for given sender and receiver cards.

Request

Receiver.receiverType = WALLET_CARD_ID.

POST /mobile-api/determine-currency HTTP/1.1
Content-Type: application/json
Authorization: Mobile eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJiNjg4MjIyYmEiLCJleHAiOjE2NTE3NTY2OTh9.bbGrMfHjTtvHNmHzW_IKG6lUVzVJhJX8UUQ1ZuuvwWg
Product-Name:
Content-Type: application/json
Content-Length: 56

{
    "sender": {
        "cardId": "219754"
    },
    "receiver": {
        "card": ["2","1","4","4","9","2"],
        "userId": "1223",
        "receiverType": "WALLET_CARD_ID"
    }
}

Receiver.receiverType = FRIEND_ID.

POST /mobile-api/determine-currency HTTP/1.1
Content-Type: application/json
Authorization: Mobile eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJiNjg4MjIyYmEiLCJleHAiOjE2NTE3NTY2OTh9.bbGrMfHjTtvHNmHzW_IKG6lUVzVJhJX8UUQ1ZuuvwWg
Product-Name: TestProduct
Content-Length: 56

{
    "sender": {
        "cardId": "219754"
    },
    "receiver": {
        "userId": "21",
        "receiverType": "FRIEND_ID"
    }
}

Receiver.receiverType = EMPTY.

POST /mobile-api/determine-currency HTTP/1.1
Content-Type: application/json
Authorization: Mobile eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJiNjg4MjIyYmEiLCJleHAiOjE2NTE3NTY2OTh9.bbGrMfHjTtvHNmHzW_IKG6lUVzVJhJX8UUQ1ZuuvwWg
Product-Name: TestProduct
Content-Length: 56

{
    "sender": {
        "cardId": "219754"
    },
    "receiver": {
        "receiverType": "EMPTY"
    }
}

Receiver.receiverType = BARE_CARD_NUMBER.

POST /mobile-api/determine-currency HTTP/1.1
Content-Type: application/json
Authorization: Mobile eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJiNjg4MjIyYmEiLCJleHAiOjE2NTE3NTY2OTh9.bbGrMfHjTtvHNmHzW_IKG6lUVzVJhJX8UUQ1ZuuvwWg
Product-Name: TestProduct
Content-Length: 56

{
    "sender": {
        "cardId": "219754"
    },
    "receiver": {
        "card": ["2","2","2","1","0","0","4","0","7","2","1","9","0","1","8","5"],
        "receiverType": "BARE_CARD_NUMBER"
    }
}

Request headers

Request body with header: X-Encryption-Public-Key

Type	Value	Constraints	Description
Authorization	Mobile bG9naW46YWNrbWU=	Required	Device token with "Mobile " prefix
Product-Name	TestProduct	Required	Application product name
Content-Type	application/x-jwe-encryption-body+json	Optional	Header must be present if the request body is encrypted using the JWE standard.
X-Encryption-Public-Key		Optional	Header must be present if the response body is to be encrypted using the JWE standard. Public key must be encoded Base64.

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

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

Error response - ERROR_VALIDATION.

HTTP/1.1 400 BAD REQUEST
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

{
    "traceId": "{{traceId}}",
    "errorStatus": "ERROR_VALIDATION",
    "message": "Some fields are invalid",
    "data": [
        {
            "field": "{{field_name_from_request}}",
            "message": "{{message}}"
        }
    ]
}

Error response - ERROR_BAD_TOKEN.

HTTP/1.1 400 BAD REQUEST
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

{
    "traceId": "{{traceId}}",
    "errorStatus": "ERROR_BAD_TOKEN"
}

Error response - PRODUCT_NOT_FOUND.

HTTP/1.1 404 NOT FOUND
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

{
    "traceId": "{{traceId}}",
    "errorStatus": "PRODUCT_NOT_FOUND",
    "message": "Product by name {{product_name}} not found."
}

Error response - INTERNAL_SERVER_ERROR.

HTTP/1.1 500 INTERNAL SERVER ERROR
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

{
    "traceId": "{{traceId}}",
    "errorStatus": "INTERNAL_SERVER_ERROR"
}

Response fields

Path	Type	Description
senderDefaultCurrencies	String	Sender Default Currencies
receiverDefaultCurrencies	String	Receiver Default Currencies
senderCurrencies	Array	Sender Currencies
receiverCurrencies	Array	Receiver Currencies

Errors

Encrypted response fields when sent header: X-Encryption-Public-Key

Http Status	Error Status	Description
400 - Bad Request	ERROR_VALIDATION	Some fields are invalid
400 - Bad Request	ERROR_BAD_TOKEN	Invalid authorization token
400 - Bad Request	CRYPTOGRAPHY_ERROR	Error decoding public key has sent in header: X-Encryption-Public-Key
400 - Bad Request	CRYPTOGRAPHY_ERROR	Error on decrypting request
400 - Bad Request	CRYPTOGRAPHY_ERROR	Error on encrypting response
400 - Bad Request	CRYPTOGRAPHY_ERROR	JWE encryption Key is invalid
400 - Bad Request	CRYPTOGRAPHY_ERROR	JWE payload is expired
400 - Bad Request	ERROR_SENDER_CARD_NOT_ACTIVE	Sender card is not active
400 - Bad Request	ERROR_RECEIVER_CARD_NOT_ACTIVE	Receiver card is not active
400 - Bad Request	UNKNOWN_ERROR	Unknown error
404 - Not Found	PRODUCT_NOT_FOUND	Product not found based on sent header: Product-Name
404 - Not Found	CANT_FIND_CARD	Not found card
404 - Not Found	FRIEND_NOT_EXISTS	Not found friend
500 - Internal Server Error	INTERNAL_SERVER_ERROR	Internal application error
500 - Internal Server Error	ERROR_ON_GETTING_DEFAULT_CARD	Error on getting card for friend
500 - Internal Server Error	FENIGE_ERROR	Fenige error

Currency Rate

Request body with header: X-Encryption-Public-Key.

Method is used for determine currency rate for revaluation from funding to payment (lowerRate) and payment to funding (higherRate).
Notice that lowerRate is used to transaction processing.

Api Send-money allows users to select the direction of revaluation by providing specify type value in send-money request.
1 - User by selecting type = SENDER defines amount of funding in given currency. This amount is collected from sender card in selected currency.
2 - User by selecting type = RECEIVER defines amount of payment in given currency.
This amount is transferred to receiver card in selected currency.In case there’s need revaluation from one currency to another, system uses lowerRate for situation 1 and higherRate for situation 2

Request

GET /mobile-api/currency-rate/PLN/EUR HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Mobile eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJiNjUzNGJhIiwiZXhwIjoxNjUxNzU2Njk4fQ.tBs5Os24ux-zmYNGYx5MCRAIYOg4Wtnu51NGs39doZ0
Product-Name: TestProduct
Host: localhost:8080

Request headers

Request body with header: X-Encryption-Public-Key

Type	Value	Constraints	Description
Authorization	Mobile bG9naW46YWNrbWU=	Required	Device token with "Mobile " prefix
Product-Name	TestProduct	Required	Application product name
X-Encryption-Public-Key		Optional	Header must be present if the response body is to be encrypted using the JWE standard. Public key must be encoded Base64.

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

Error response - ERROR_BAD_TOKEN.

HTTP/1.1 400 BAD REQUEST
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

{
    "traceId": "{{traceId}}",
    "errorStatus": "ERROR_BAD_TOKEN"
}

Error response - PRODUCT_NOT_FOUND.

HTTP/1.1 404 NOT FOUND
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

{
    "traceId": "{{traceId}}",
    "errorStatus": "PRODUCT_NOT_FOUND",
    "message": "Product by name {{product_name}} not found."
}

Error response - INTERNAL_SERVER_ERROR.

HTTP/1.1 500 INTERNAL SERVER ERROR
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

{
    "traceId": "{{traceId}}",
    "errorStatus": "INTERNAL_SERVER_ERROR"
}

Response fields

Path	Type	Description
lowerRate	String	Lower rate exchange
higherRate	String	Higher rate exchange

Errors

Encrypted response fields when sent header: X-Encryption-Public-Key

Http Status	Error Status	Description
400 - Bad Request	ERROR_BAD_TOKEN	Invalid authorization token
400 - Bad Request	CRYPTOGRAPHY_ERROR	Error decoding public key has sent in header: X-Encryption-Public-Key
400 - Bad Request	CRYPTOGRAPHY_ERROR	Error on encrypting response
400 - Bad Request	CRYPTOGRAPHY_ERROR	JWE encryption Key is invalid
400 - Bad Request	CRYPTOGRAPHY_ERROR	JWE payload is expired
404 - Not Found	PRODUCT_NOT_FOUND	Product not found based on sent header: Product-Name
500 - Internal Server Error	INTERNAL_SERVER_ERROR	Internal application error
500 - Internal Server Error	FENIGE_ERROR	Fenige error

Calculate commission

Request body with header: X-Encryption-Public-Key.

This method is used to receive information about the commission that will be charged for the transaction. Additional description:

• If value the field: "reconciliationType" is "PLUS", the commission during the transaction will be added to the amount sent (the amount charged from the sender will be increased by a commission).
• If value the field: "reconciliationType" is "MINUS", then the commission during the transaction will be deducted from the amount received (the amount that will be received by the receiver will be reduced by the commission).
• If value the field: "reconciliationType" is "DEPOSITED", the commission during the transaction will neither be subtracted nor added (the amount to be received by the receiver is the same as the amount sent).

In addition, the user may specify in the field: type two values SENDER or RECEIVER.
After selecting the value: SENDER, the transaction will be sent in the amount indicated in the field: amount. Whereas after choosing the value: RECEIVER, the transaction will be received in the amount indicated in the field: amount. The method allows user to calculate commissions for the currencies that have been entered.

Request

Receiver.receiverType = WALLET_CARD_ID.

POST /mobile-api/calculate-commission HTTP/1.1
Content-Type: application/json
Authorization: Mobile eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJiNjg4MjIyYmEiLCJleHAiOjE2NTE3NTY2OTh9.bbGrMfHjTtvHNmHzW_IKG6lUVzVJhJX8UUQ1ZuuvwWg
Product-Name: TestProduct
Content-Length: 101

{
    "amount": 200078,
    "type": "RECEIVER",
    "sender":{
    	"cardId":"219834",
    	"currency":"PLN"
    },
    "receiver":{
    	"userId": 2345,
    	"card": ["2","2","1","2","4","5"],
    	"currency": "PLN",
    	"receiverType": "WALLET_CARD_ID"
    }
}

Receiver.receiverType = FRIEND_ID.

POST /mobile-api/calculate-commission HTTP/1.1
Content-Type: application/json
Authorization: Mobile eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJiNjg4MjIyYmEiLCJleHAiOjE2NTE3NTY2OTh9.bbGrMfHjTtvHNmHzW_IKG6lUVzVJhJX8UUQ1ZuuvwWg
Product-Name: TestProduct
Content-Length: 101

{
    "amount": 200078,
    "type": "RECEIVER",
    "sender":{
    	"cardId":"219834",
    	"currency":"PLN"
    },
    "receiver":{
    	"userId": 2345,
    	"currency": "PLN",
    	"receiverType": "FRIEND_ID"
    }
}

Receiver.receiverType = BARE_CARD_NUMBER.

POST /mobile-api/calculate-commission HTTP/1.1
Content-Type: application/json
Authorization: Mobile eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJiNjg4MjIyYmEiLCJleHAiOjE2NTE3NTY2OTh9.bbGrMfHjTtvHNmHzW_IKG6lUVzVJhJX8UUQ1ZuuvwWg
Product-Name: TestProduct
Content-Length: 101

{
    "amount": 200078,
    "type": "RECEIVER",
    "sender":{
    	"cardId":"219834",
    	"currency":"PLN"
    },
    "receiver":{
    	"card": ["5","4","9","5","9","8","4","1","7","9","0","8","2","6","4","5"],
    	"currency": "PLN",
    	"receiverType": "BARE_CARD_NUMBER"
    }
}

Request headers

Request body with header: X-Encryption-Public-Key

Type	Value	Constraints	Description
Authorization	Mobile bG9naW46YWNrbWU=	Required	Device token with "Mobile " prefix
Product-Name	TestProduct	Required	Application product name
Content-Type	application/x-jwe-encryption-body+json	Optional	Header must be present if the request body is encrypted using the JWE standard.
X-Encryption-Public-Key		Optional	Header must be present if the response body is to be encrypted using the JWE standard. Public key must be encoded Base64.

Request fields

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

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: 1007

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

Error response - ERROR_VALIDATION.

HTTP/1.1 400 BAD REQUEST
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

{
    "traceId": "{{traceId}}",
    "errorStatus": "ERROR_VALIDATION",
    "message": "Some fields are invalid",
    "data": [
        {
            "field": "{{field_name_from_request}}",
            "message": "{{message}}"
        }
    ]
}

Error response - ERROR_BAD_TOKEN.

HTTP/1.1 400 BAD REQUEST
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

{
    "traceId": "{{traceId}}",
    "errorStatus": "ERROR_BAD_TOKEN"
}

Error response - PRODUCT_NOT_FOUND.

HTTP/1.1 404 NOT FOUND
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

{
    "traceId": "{{traceId}}",
    "errorStatus": "PRODUCT_NOT_FOUND",
    "message": "Product by name {{product_name}} not found."
}

Error response - INTERNAL_SERVER_ERROR.

HTTP/1.1 500 INTERNAL SERVER ERROR
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

{
    "traceId": "{{traceId}}",
    "errorStatus": "INTERNAL_SERVER_ERROR"
}

Errors

Encrypted response fields when sent header: X-Encryption-Public-Key

Http Status	Error Status	Description
400 - Bad Request	ERROR_VALIDATION	Some fields are invalid
400 - Bad Request	ERROR_BAD_TOKEN	Invalid authorization token
400 - Bad Request	CRYPTOGRAPHY_ERROR	Error decoding public key has sent in header: X-Encryption-Public-Key
400 - Bad Request	CRYPTOGRAPHY_ERROR	Error on decrypting request
400 - Bad Request	CRYPTOGRAPHY_ERROR	Error on encrypting response
400 - Bad Request	CRYPTOGRAPHY_ERROR	JWE encryption Key is invalid
400 - Bad Request	CRYPTOGRAPHY_ERROR	JWE payload is expired
400 - Bad Request	ERROR_WHILE_GETTING_COUNTRY_CODE	Could not get card country code
400 - Bad Request	ERROR_WHILE_GETTING_SENDER_COUNTRY_CODE	Could not get card country code for sender
400 - Bad Request	ERROR_WHILE_GETTING_RECEIVER_COUNTRY_CODE	Could not get card country code for receiver
400 - Bad Request	ERROR_SENDER_CARD_NOT_ACTIVE	Sender card is not active
400 - Bad Request	ERROR_RECEIVER_CARD_NOT_ACTIVE	Receiver card is not active
400 - Bad Request	UNKNOWN_ERROR	Unknown error
404 - Not Found	PRODUCT_NOT_FOUND	Product not found based on sent header: Product-Name
404 - Not Found	CANT_FIND_CARD	Not found card
404 - Not Found	FRIEND_NOT_EXISTS	Not found friend
500 - Internal Server Error	INTERNAL_SERVER_ERROR	Internal application error
500 - Internal Server Error	ERROR_ON_GETTING_DEFAULT_CARD	Error on getting card for friend
500 - Internal Server Error	FENIGE_ERROR	Fenige error

Send Money

Request body with header: X-Encryption-Public-Key.

This method is used to full MoneySend transaction (funding and payment).
Transfers can be make in any currency.
1 - User by selecting type = SENDER defines amount of funding in given currency.
This amount is collected from sender card in selected currency. 2 - User by selecting type = RECEIVER defines amount of payment in given currency.
This amount is transferred to receiver card in selected currency.

In case there’s need revaluation from one currency to another, system uses lowerRate for situation 1 and higherRate for situation 2. For more details about specific rates please refer to Currency Rate method.
This method adds friend to sender after successful transaction.

Additionally, you can perform full MoneySend transaction with externalAuthentication (see: ??? and Authentication)

Request

Receiver.receiverType = WALLET_CARD_ID.

POST /mobile-api/send-money HTTP/1.1
Content-Type: application/json
Authorization: Mobile bG9nzW46YWNrbWU=
Product-Name: TestProduct
Content-Length: 56

{
    "amount": 1000,
    "cvc2": ["1","2","3"],
    "type": "RECEIVER",
    "addressIp": "192.168.0.1",
    "sender": {
        "firstName": "Mark",
        "lastName": "Wards",
        "street": "Olszewskiego",
        "houseNumber": "17A",
        "city": "Lublin",
        "postalCode": "20-400",
        "flatNumber": "2",
        "email": "senderEmail@fenige.pl",
        "currency": "PLN",
        "expirationDate": "03/20",
        "personalId": "AGC688910",
        "cardId": "219708"
    },
    "receiver": {
        "firstName": "Rob",
        "lastName": "Wring",
        "currency": "PLN",
        "card": ["2","1","9","7","0","8"],
        "displayName": "Rob W.",
        "phoneNumber": "48718222333",
        "receiverType": "WALLET_CARD_ID",
        "userId": "13001"
    }
}

Receiver.receiverType = FRIEND_ID.

POST /mobile-api/send-money HTTP/1.1
Content-Type: application/json
Authorization: Mobile bG9nzW46YWNrbWU=
Product-Name: TestProduct
Content-Length: 56

{
    "amount": 1000,
    "cvc2": ["1","2","3"],
    "type": "RECEIVER",
    "addressIp": "192.168.0.1",
    "sender": {
        "firstName": "Mark",
        "lastName": "Wards",
        "street": "Olszewskiego",
        "houseNumber": "17A",
        "city": "Lublin",
        "postalCode": "20-400",
        "flatNumber": "2",
        "email": "senderEmail@fenige.pl",
        "currency": "PLN",
        "expirationDate": "03/20",
        "personalId": "AGC688910",
        "cardId": "219708"
    },
    "receiver": {
        "firstName": "Rob",
        "lastName": "Wring",
        "currency": "PLN",
        "displayName": "Rob W.",
        "receiverType": "FRIEND_ID",
        "userId": "123"
    }
}

Receiver.receiverType = BARE_CARD_NUMBER.

POST /mobile-api/send-money HTTP/1.1
Content-Type: application/json
Authorization: Mobile bG9nzW46YWNrbWU=
Product-Name: TestProduct
Content-Length: 56

{
    "amount": 1000,
    "cvc2": ["1","2","3"],
    "type": "RECEIVER",
    "addressIp": "192.168.0.1",
    "sender": {
        "firstName": "Mark",
        "lastName": "Wards",
        "street": "Olszewskiego",
        "houseNumber": "17A",
        "city": "Lublin",
        "postalCode": "20-400",
        "flatNumber": "2",
        "email": "senderEmail@fenige.pl",
        "currency": "PLN",
        "expirationDate": "03/20",
        "personalId": "AGC688910",
        "cardId": "219708"
    },
    "receiver": {
        "firstName": "Rob",
        "lastName": "Wring",
        "currency": "PLN",
        "card": ["5","1","4","2","3","3","3","6","2","9","5","2","3","7","3","2"],
        "displayName": "displayName",
        "phoneNumber": "48299000111",
        "receiverType": "BARE_CARD_NUMBER"
    }
}

ExternalAuthentication.authenticationId.

POST /mobile-api/send-money HTTP/1.1
Content-Type: application/json
Authorization: Mobile bG9nzW46YWNrbWU=
Product-Name: TestProduct
Content-Length: 56

{
  "amount" : 1000,
  "cvc2" : [ "1", "2", "3" ],
  "type" : "RECEIVER",
  "addressIp" : "192.168.0.1",
  "sender" : {
    "firstName" : "Mark",
    "lastName" : "Asdasd",
    "street" : "Olszewskiego",
    "houseNumber" : "17A",
    "city" : "Lublin",
    "postalCode" : "20-400",
    "flatNumber" : "2",
    "email" : "senderEmail@fenige.pl",
    "currency" : "PLN",
    "expirationDate" : "03/20",
    "personalId" : "AGC688910",
    "cardId" : "219708"
  },
  "receiver" : {
    "firstName" : "Rob",
    "lastName" : "Wring",
    "currency" : "PLN",
    "card" : [ "2", "1", "9", "7", "0", "8" ],
    "displayName" : "displayName",
    "phoneNumber" : "phoneNumber",
    "receiverType" : "WALLET_CARD_ID",
    "userId" : "123"
  },
  "externalAuthentication" : {
    "authenticationId" : "authenticationId"
  }
}

ExternalAuthentication.cavv, eci, transactionXId, authenticationStatus.

POST /mobile-api/send-money HTTP/1.1
Content-Type: application/json
Authorization: Mobile bG9nzW46YWNrbWU=
Product-Name: TestProduct
Content-Length: 56

{
  "amount" : 1000,
  "cvc2" : [ "1", "2", "3" ],
  "type" : "RECEIVER",
  "addressIp" : "192.168.0.1",
  "sender" : {
    "firstName" : "Mark",
    "lastName" : "Asdasd",
    "street" : "Olszewskiego",
    "houseNumber" : "17A",
    "city" : "Lublin",
    "postalCode" : "20-400",
    "flatNumber" : "2",
    "email" : "senderEmail@fenige.pl",
    "currency" : "PLN",
    "expirationDate" : "03/20",
    "personalId" : "AGC688910",
    "cardId" : "219708"
  },
  "receiver" : {
    "firstName" : "Rob",
    "lastName" : "Wring",
    "currency" : "PLN",
    "card" : [ "2", "1", "9", "7", "0", "8" ],
    "displayName" : "displayName",
    "phoneNumber" : "phoneNumber",
    "receiverType" : "WALLET_CARD_ID",
    "userId" : "123"
  },
  "externalAuthentication" : {
    "cavv" : "jEu04WZns7pbARAApU4qgNdJTag",
    "eci" : "PLN",
    "authenticationStatus" : "Y",
    "transactionXId" : "9742432a-dfdc-41ca-9ae9-b6595de65f1d"
  }
}

Request headers

Type	Value	Constraints	Description
Authorization	Mobile bG9naW46YWNrbWU=	Required	Device token with "Mobile " prefix
Product-Name	TestProduct	Required	Application product name
Content-Type	application/x-jwe-encryption-body+json	Optional	Header must be present if the request body is encrypted using the JWE standard.
X-Encryption-Public-Key		Optional	Header must be present if the response body is to be encrypted using the JWE standard. Public key must be encoded Base64.

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.street	String	Required, Must match length: min = 1 max = 55, Must match pattern: ^[^\s]+(\s+[^\s]+)*$	Street
sender.houseNumber	String	Required, Must match length: min = 1, max = 10, Must match pattern: "^[0-9]{1,5}[A-z]?(?:/[0-9]{1,5}[A-z]?)?$"	House number
sender.city	String	Required, Must match length: min = 1 max = 55	City
sender.postalCode	String	Required, Must match length: min = 1, max = 10, Must match pattern: "^(?=.*\d)(?=.*[1-9,a-zA-Z]).{1,10}$"	Postal code
sender.flatNumber	String	Optional, Must match length: min = 1 max = 5, Must match pattern: "^[a-zA-Z0-9 ]*$"	Flat number
sender.email	String	Optional, Must match length: min = 1 max = 128, Must match pattern: "^(?:[A-Za-z0-9]{1,}[\\.!#$%&'*/=?`{|}~^\\-_]?){1,}[A-Za-z0-9]{1,}@((?:[a-zA-Z0-9](?:-[a-zA-Z0-9]+)*\\.){1,}[a-zA-Z]{2,})$", Email cannot be the same for 2 different persons sender and receiver	Email
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.

Response

HTTP/1.1 200 OK
Location: /api/send-money/4979532e-dca1-40f6-b13a-0f3039d26e71
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" : "4979532e-dca1-40f6-b13a-0f3039d26e71"
}

Error response - ERROR_VALIDATION.

HTTP/1.1 400 BAD REQUEST
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

{
    "traceId": "{{traceId}}",
    "errorStatus": "ERROR_VALIDATION",
    "message": "Some fields are invalid",
    "data": [
        {
            "field": "{{field_name_from_request}}",
            "message": "{{message}}"
        }
    ]
}

Error response - ERROR_BAD_TOKEN.

HTTP/1.1 400 BAD REQUEST
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

{
    "traceId": "{{traceId}}",
    "errorStatus": "ERROR_BAD_TOKEN"
}

Error response - PRODUCT_NOT_FOUND.

HTTP/1.1 404 NOT FOUND
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

{
    "traceId": "{{traceId}}",
    "errorStatus": "PRODUCT_NOT_FOUND",
    "message": "Product by name {{product_name}} not found."
}

Error response - INTERNAL_SERVER_ERROR.

HTTP/1.1 500 INTERNAL SERVER ERROR
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

{
    "traceId": "{{traceId}}",
    "errorStatus": "INTERNAL_SERVER_ERROR"
}

Response fields

Path	Type	Description
orderId	String	Transaction Id

Errors

Encrypted response fields when sent header: X-Encryption-Public-Key

Http Status	Error Status	Description
400 - Bad Request	ERROR_VALIDATION	Some fields are invalid
400 - Bad Request	ERROR_BAD_TOKEN	Invalid authorization token
400 - Bad Request	CRYPTOGRAPHY_ERROR	Error decoding public key has sent in header: X-Encryption-Public-Key
400 - Bad Request	CRYPTOGRAPHY_ERROR	Error on decrypting request
400 - Bad Request	CRYPTOGRAPHY_ERROR	Error on encrypting response
400 - Bad Request	CRYPTOGRAPHY_ERROR	JWE encryption Key is invalid
400 - Bad Request	CRYPTOGRAPHY_ERROR	JWE payload is expired
400 - Bad Request	ERROR_WHILE_GETTING_COUNTRY_CODE	Could not get card country code
400 - Bad Request	ERROR_MERCHANT_NOT_SUPPORT_CARD_PROVIDER	Merchant not support card provider
400 - Bad Request	ERROR_SENDER_CARD_NOT_ACTIVE	Sender card is not active
400 - Bad Request	ERROR_RECEIVER_CARD_NOT_ACTIVE	Receiver card is not active
400 - Bad Request	ERROR_SENDER_CARD_IS_BLOCKED	Sender card is blocked
400 - Bad Request	ERROR_RECEIVER_CARD_IS_BLOCKED	Receiver card is blocked
400 - Bad Request	UNKNOWN_ERROR	Unknown error
404 - Not Found	PRODUCT_NOT_FOUND	Product not found based on sent header: Product-Name
404 - Not Found	CANT_FIND_CARD	Not found card
404 - Not Found	FRIEND_NOT_EXISTS	Not found friend
500 - Internal Server Error	INTERNAL_SERVER_ERROR	Internal application error
500 - Internal Server Error	FENIGE_ERROR	Fenige error
500 - Internal Server Error	ERROR_ON_GETTING_DEFAULT_CARD	Error on getting card for friend

Send Money Details

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

Request

GET /mobile-api/send-money/6c476efe-71d6-4d9d-b14a-0c311743b0d8 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Mobile eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJiNjUzNGJhIiwiZXhwIjoxNjUxNzU2Njk4fQ.tBs5Os24ux-zmYNGYx5MCRAIYOg4Wtnu51NGs39doZ0
Product-Name: TestProduct
Host: localhost:8080

Request headers

Type	Value	Constraints	Description
Authorization	Mobile eyJhbGciOiJIUzI1NiJ9. eyJzdWIiOiJiNjUzNGJhIiwiZXhwIjoxNjUxNzU2Njk4fQ. tBs5Os24ux-zmYNGYx5MCRAIYOg4Wtnu51NGs39doZ0	Required	Device token with "Mobile " prefix
Product-Name	TestProduct	Required	Application product name
X-Encryption-Public-Key	{{base64_encoded_public_key}}	Optional	Header must be present if the response body is to be encrypted using the JWE standard. Public key must be encoded Base64.

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" : "6c476efe-71d6-4d9d-b14a-0c311743b0d8",
  "createdAt" : "2023-06-23T08:08:01.983233981Z",
  "status" : "SUCCESS"
}

Error response - ERROR_BAD_TOKEN.

HTTP/1.1 400 BAD REQUEST
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

{
    "traceId": "{{traceId}}",
    "errorStatus": "ERROR_BAD_TOKEN"
}

Error response - PRODUCT_NOT_FOUND.

HTTP/1.1 404 NOT FOUND
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

{
    "traceId": "{{traceId}}",
    "errorStatus": "PRODUCT_NOT_FOUND",
    "message": "Product by name {{product_name}} not found."
}

Error response - INTERNAL_SERVER_ERROR.

HTTP/1.1 500 INTERNAL SERVER ERROR
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

{
    "traceId": "{{traceId}}",
    "errorStatus": "INTERNAL_SERVER_ERROR"
}

Response fields

Path	Type	Description
orderId	String	Transaction identifier
createdAt	String	Transaction creation date
status	String	Transaction status. One of: PENDING, FAILURE, SUCCESS

Errors

Http Status	Error Status	Description
400 - Bad Request	ERROR_BAD_TOKEN	Invalid authorization token
400 - Bad Request	CRYPTOGRAPHY_ERROR	Error decoding public key has sent in header: X-Encryption-Public-Key
400 - Bad Request	CRYPTOGRAPHY_ERROR	Error on encrypting response
400 - Bad Request	CRYPTOGRAPHY_ERROR	JWE encryption Key is invalid
404 - Not Found	PRODUCT_NOT_FOUND	Product not found based on sent header: _Product-Name
404 - Not Found	TRANSACTION_NOT_FOUND	Transation not found
500 - Internal Server Error	INTERNAL_SERVER_ERROR	Internal application error

Add Friend

Request body with header: X-Encryption-Public-Key.

This method allow user to add Friend.

Request

friendType = WALLET.

POST /mobile-api/wallet-users/friends HTTP/1.1
Content-Type: application/json
Authorization: Mobile bG9nzW46YWNrbWU=
Product-Name: TestProduct
Content-Length: 56

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

friendType = EXTERNAL.

POST /mobile-api/wallet-users/friends HTTP/1.1
Content-Type: application/json
Authorization: Mobile bG9nzW46YWNrbWU=
Product-Name: TestProduct
Content-Length: 56

{
  "displayName": "Display name",
  "phoneNumber": "48999111222",
  "friendType": "EXTERNAL",
  "firstName": "First",
  "lastName": "Last",
  "cardNumber": ["5","5","2","7","4","7","9","6","6","8","3","9","0","9","5","7"]
}

Request headers

Request body with header: X-Encryption-Public-Key

Type	Value	Constraints	Description
Authorization	Mobile bG9naW46YWNrbWU=	Required	Device token with "Mobile " prefix
Product-Name	TestProduct	Required	Application product name
Content-Type	application/x-response-body+json	Optional	Header must be present if the response body must have body.
Content-Type	application/x-jwe-encryption-body+json	Optional	Header must be present if the request body is encrypted using the JWE standard.
X-Encryption-Public-Key		Optional	Header must be present if the response body is to be encrypted using the JWE standard. Public key must be encoded Base64.

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

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

Get User friends

Request body with header: X-Encryption-Public-Key.

This method allow user to get all his friends

Request

GET /mobile-api/wallet-users/friends HTTP/1.1
Authorization: Mobile eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJiNjUzNGJhIiwiZXhwIjoxNjUxNzU2Njk4fQ.tBs5Os24ux-zmYNGYx5MCRAIYOg4Wtnu51NGs39doZ0
Product-Name: TestProduct
Host: localhost:8080

Request headers

Encrypted request body with header: Content-Type: application/x-jwe-encryption-body+json

Type	Value	Constraints	Description
Authorization	Mobile bG9naW46YWNrbWU=	Required	Device token with "Mobile " prefix
Product-Name	TestProduct	Required	Application product name
X-Encryption-Public-Key		Optional	Header must be present if the response body is to be encrypted using the JWE standard. Public key must be encoded Base64.

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: 251

{
  "friends" : [ {
    "friendId" : 2,
    "firstName" : "First",
    "lastName" : "Last",
    "displayName" : "Display name",
    "phoneNumber" : "48991193211",
    "friendType" : "WALLET",
    "lastFourDigits" : "4444",
    "bin" : "666222"
  } ]
}

Response fields

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]

Update Friend

Request body with header: X-Encryption-Public-Key.

This method allow user to update friend. For a friend of the type: WALLET, can update only the field: displayName. For a friend of the type: EXTERNAL, can update the fields: phoneNumber, displayName, firstName, lastName, cardNumber.

Request

friendType = WALLET.

PUT /mobile-api/wallet-users/friends/24 HTTP/1.1
Content-Type: application/json
Authorization: Mobile bG9naW46YWNrbWU=
Product-Name: TestProduct
Content-Length: 101

{
   "displayName":"Display name"
}

friendType = EXTERNAL.

PUT /mobile-api/wallet-users/friends/24 HTTP/1.1
Content-Type: application/json
Authorization: Mobile bG9naW46YWNrbWU=
Product-Name: TestProduct
Content-Length: 101

{
   "phoneNumber":"48999000111",
   "displayName":"Display name",
   "firstName":"First",
   "lastName":"Last",
   "cardNumber":["4","4","4","0","0","0","0","4","4","4","0","4","0"]
}

Request headers

Encrypted request body with header: Content-Type: application/x-jwe-encryption-body+json

Type	Value	Constraints	Description
Authorization	Mobile bG9naW46YWNrbWU=	Required	Device token with "Mobile " prefix
Product-Name	TestProduct	Required	Application product name
Content-Type	application/x-jwe-encryption-body+json	Optional	Header must be present if the request body is encrypted using the JWE standard.

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

Response

HTTP/1.1 204 No Content
Content-Type: application/json
Location: /mobile-api/wallet-users/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

Delete friend

Encrypted request body with header: Content-Type: application/x-jwe-encryption-body+json.

This method allow user to delete friend

Request

DELETE /mobile-api/wallet-users/friends/24 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Mobile eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJiNjUzNGJhIiwiZXhwIjoxNjUxNzU2Njk4fQ.tBs5Os24ux-zmYNGYx5MCRAIYOg4Wtnu51NGs39doZ0
Product-Name: TestProduct
Host: localhost:8080

Request headers

Type	Value	Constraints	Description
Authorization	Mobile bG9naW46YWNrbWU=	Required	Device token with "Mobile " prefix
Product-Name	TestProduct	Required	Application product name

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

Get publicKey

This method allow user to get publicKey

Request

GET /mobile-api/public-key HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Mobile eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJiNjUzNGJhIiwiZXhwIjoxNjUxNzU2Njk4fQ.tBs5Os24ux-zmYNGYx5MCRAIYOg4Wtnu51NGs39doZ0
Product-Name: TestProduct
Host: localhost:8080

Request headers

Type	Value	Constraints	Description
Authorization	Mobile bG9naW46YWNrbWU=	Required	Device token with "Mobile " prefix
Product-Name	TestProduct	Required	Application product name

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: 610

{
  "value" : "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQklqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FROEFNSUlCQ2dLQ0FRRUE5QXdvaDlzRW1CeDFUK2llb0lVMWpLUVJuUmg3SGFBS0tHdGdPTFQ3WDIyYlVuaHNDbld0SEVSR2pOcVBsQ205Wmh5SHo2ajFlSi9UVmdhQ1NEYmtKZFNUMmpCVDZDKzBKb0NnYld0S2EwbllIMVI4NWNVWUgzT3dYcFBZSHhGMW1MRlRVU2doUXFBVXZ1QzVla2FTQi9lTGV2WmRXTTcyazAybTZ0bGJUVWRhbUtQRnp1VzhxMGpZYUZ0Z01XYXlZUG81WXJJU1ZWWVZTVGdVZjZqR2ZCQUZ3N2d5dHVBaFlUMTVpT2g0NWtpc2pZb1BzaEd2RitqQ0FSbzlDMDhKSTdubVVGSEUrczNYQm84S0t0THNNKzhvcWNZdy9maVhIbkljSHNvcTQ2bnBWMEtTWW9MZm5pa0hnTnoxUFR0dnpBZ29NeXdSSDVrdURhYmNEeVRoZVFJREFRQUIKLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0t"
}

Response fields

Path	Type	Description
value	String	Public key encoded with Base64

Examples

MC Send

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

Master Card Send

Methods allow sending money in MasterCard Send 2.0

Request

Sender.paymentAccountType = WALLET_CARD_ID.

POST /mobile-api/mc-send HTTP/1.1
Content-Type: application/json
Authorization: Mobile bG9naW46YWNrbWU=
Product-Name: TestProduct
Content-Length: 885

{
  "transactionId" : "bbb8597d-582c-4a12-a1c8-be9377aed6f9",
  "amount" : 40,
  "currency" : "INR",
  "sender" : {
    "account" : "walletCardId",
    "cvc2": ["3","2","1"],
    "addressId" : "123",
    "paymentAccountType" : "WALLET_CARD_ID"
  },
  "recipient" : {
    "name" : "Juniper Jane",
    "accountUri" : "402414000000006",
    "nationality" : "USA",
    "dateOfBirth" : "2011-05-13",
    "address" : {
      "city" : "Cape Girardeau",
      "country" : "USA",
      "state" : "MO",
      "postalCode" : "23232",
      "street" : "Mastercard Blvd"
    },
    "phone" : "1234567890",
    "email" : "jane.doe@mastercard.com",
    "governmentIds" : [ "123456789", "123456789" ],
    "receiverType" : "BARE_CARD_NUMBER"
  },
  "qrData" : "12",
  "transactionPurpose" : "07",
  "additionalMessage" : "message",
  "merchantCategoryCode" : "6536"
}

Sender.paymentAccountType = IBAN_ID.

POST /mobile-api/mc-send HTTP/1.1
Content-Type: application/json
Authorization: Mobile bG9naW46YWNrbWU=
Product-Name: TestProduct
Content-Length: 885

{
  "transactionId" : "bbb8597d-582c-4a12-a1c8-be9377aed6f9",
  "amount" : 40,
  "currency" : "INR",
  "sender" : {
    "account" : "ibanId",
    "addressId" : "123",
    "paymentAccountType" : "IBAN_ID"
  },
  "recipient" : {
    "name" : "Juniper Jane",
    "accountUri" : "402414000000006",
    "nationality" : "USA",
    "dateOfBirth" : "2011-05-13",
    "address" : {
      "city" : "Cape Girardeau",
      "country" : "USA",
      "state" : "MO",
      "postalCode" : "23232",
      "street" : "Mastercard Blvd"
    },
    "phone" : "1234567890",
    "email" : "jane.doe@mastercard.com",
    "governmentIds" : [ "123456789", "123456789" ],
    "receiverType" : "BARE_CARD_NUMBER"
  },
  "qrData" : "12",
  "transactionPurpose" : "07",
  "additionalMessage" : "message",
  "merchantCategoryCode" : "6536"
}

Recipient.receiverType = WALLET_CARD_ID.

POST /mobile-api/mc-send HTTP/1.1
Content-Type: application/json
Authorization: Mobile bG9naW46YWNrbWU=
Product-Name: TestProduct
Content-Length: 885

{
  "transactionId" : "bbb8597d-582c-4a12-a1c8-be9377aed6f9",
  "amount" : 40,
  "currency" : "INR",
  "sender" : {
    "account" : "ibanId",
    "addressId" : "123",
    "paymentAccountType" : "IBAN_ID"
  },
  "recipient" : {
    "name" : "Juniper Jane",
    "accountUri" : "4024",
    "nationality" : "USA",
    "dateOfBirth" : "2011-05-13",
    "address" : {
      "city" : "Cape Girardeau",
      "country" : "USA",
      "state" : "MO",
      "postalCode" : "23232",
      "street" : "Mastercard Blvd"
    },
    "phone" : "1234567890",
    "email" : "jane.doe@mastercard.com",
    "governmentIds" : [ "123456789", "123456789" ],
    "userId" : 13001,
    "receiverType" : "WALLET_CARD_ID"
  },
  "qrData" : "12",
  "transactionPurpose" : "07",
  "additionalMessage" : "message",
  "merchantCategoryCode" : "6536"
}

Recipient.receiverType = FRIEND_ID.

POST /mobile-api/mc-send HTTP/1.1
Content-Type: application/json
Authorization: Mobile bG9naW46YWNrbWU=
Product-Name: TestProduct
Content-Length: 885

{
  "transactionId" : "bbb8597d-582c-4a12-a1c8-be9377aed6f9",
  "amount" : 40,
  "currency" : "INR",
  "sender" : {
    "account" : "ibanId",
    "addressId" : "123",
    "paymentAccountType" : "IBAN_ID"
  },
  "recipient" : {
    "name" : "Juniper Jane",
    "nationality" : "USA",
    "dateOfBirth" : "2011-05-13",
    "address" : {
      "city" : "Cape Girardeau",
      "country" : "USA",
      "state" : "MO",
      "postalCode" : "23232",
      "street" : "Mastercard Blvd"
    },
    "phone" : "1234567890",
    "email" : "jane.doe@mastercard.com",
    "governmentIds" : [ "123456789", "123456789" ],
    "userId" : 13001,
    "receiverType" : "FRIEND_ID"
  },
  "qrData" : "12",
  "transactionPurpose" : "07",
  "additionalMessage" : "message",
  "merchantCategoryCode" : "6536"
}

Recipient.receiverType = BARE_CARD_NUMBER.

POST /mobile-api/mc-send HTTP/1.1
Content-Type: application/json
Authorization: Mobile bG9naW46YWNrbWU=
Product-Name: TestProduct
Content-Length: 885

{
  "transactionId" : "bbb8597d-582c-4a12-a1c8-be9377aed6f9",
  "amount" : 40,
  "currency" : "INR",
  "sender" : {
    "account" : "ibanId",
    "addressId" : "123",
    "paymentAccountType" : "IBAN_ID"
  },
  "recipient" : {
    "name" : "Juniper Jane",
    "accountUri" : "402414000000006",
    "nationality" : "USA",
    "dateOfBirth" : "2011-05-13",
    "address" : {
      "city" : "Cape Girardeau",
      "country" : "USA",
      "state" : "MO",
      "postalCode" : "23232",
      "street" : "Mastercard Blvd"
    },
    "phone" : "1234567890",
    "email" : "jane.doe@mastercard.com",
    "governmentIds" : [ "123456789", "123456789" ],
    "receiverType" : "BARE_CARD_NUMBER"
  },
  "qrData" : "12",
  "transactionPurpose" : "07",
  "additionalMessage" : "message",
  "merchantCategoryCode" : "6536"
}

Request headers

Request body with header: X-Encryption-Public-Key

Type	Value	Constraints	Description
Authorization	Mobile bG9naW46YWNrbWU=	Required	Device token with "Mobile " prefix
Product-Name	TestProduct	Required	Application product name
Content-Type	application/x-jwe-encryption-body+json	Optional	Header must be present if the request body is encrypted using the JWE standard.
X-Encryption-Public-Key		Optional	Header must be present if the response body is to be encrypted using the JWE standard. Public key must be encoded Base64.

Request fields

Path	Type	Constraints	Description
transactionId	String	Required	A unique transaction reference ID for the transaction
amount	Number	Required, Must match length: min = 1 max = 12	The transaction amount, in the currency identified by the currency field. The decimal point is implied based on the currency. For example, a $1 transaction will be a value of 100.
currency	String	Required	The 3-character ISO 4217 alpha-3 code identifying the currency for the transaction amount in the amount field. See Currency Codes. For example, for U.S. Dollars, the value is USD.
merchantCategoryCode	String	Optional	Mastercard-defined merchant category code. This identifies the type of business of the merchant. If provided, this merchant category code should match one of the valid codes set by the Mastercard rules.
sender	Object	Required	Sender information
sender.account	String	Required	One of: {Iban id - represented as sha256Hex(iban), Wallet Card ID}
sender.cvc2	Array	Conditional	Cvc2 data. Depends of receiver.paymentAccountType property. Required for receiver.paymentAccountType = WALLET_CARD_ID
sender.addressId	String	Optional	Address id of user address. If addressId will be null, one of the user’s addresses will be chosen. If addressId is not null, the address matching the specified id will be chosen.
sender.paymentAccountType	String	Required	One of: { WALLET_CARD_ID - if sender account is type of wallet card id, IBAN_ID - if sender.account is type of iban_id}. Depends of sender.account
recipient	Object	Required	Recipient information object
recipient.name	String	Required, Must match length: min = 1 max = 120	The full name of the Recipient. Recommended format: Last Name/Family Name + space + First Name + space
recipient.accountUri	String	Conditional	A deposit account or generic account number. Depends of recipient.receiverType property. Required for receiver.receiverType = WALLET_CARD_ID or BARE_CARD_NUMBER
recipient.nationality	String	Optional	The 3-character ISO 3166-1 alpha-3 code for the country in which the Recipient is a citizen;
recipient.dateOfBirth	String	Optional	The date of birth of the Recipient, in ISO 8601 full date format (YYYY-MM-DD)
recipient.userId	Number	Conditional	Receiver wallet user id. Required if recipient.receiverType = FRIEND_ID
recipient.receiverType	String	Optional	Receiver type. One of: [BARE_CARD_NUMBER, FRIEND_ID, WALLET_CARD_ID]. Default value: BARE_CARD_NUMBER.
recipient.address	Object	Required	Address information object
recipient.address.city	String	Optional, Must match length: min = 1 max = 25	The city of the individual or merchant.
recipient.address.country	String	Required	The 3-character ISO 3166-1 alpha-3 code for the country of the individual
recipient.address.state	String	Conditional, Must match length: min = 2 max = 3	State or province of the individual or merchant. If the recipient’s country is USA or CAN, the country’s state or Province is required.
recipient.address.postalCode	String	Optional, Must match length: min = 1 max = 10	The ZIP Code or postal code of the individual or merchant.
recipient.address.street	String	Optional, Must match length: min = 1 max = 50	The street address of the individual or merchant.
recipient.phone	String	Optional, Must match length: max = 15	The phone number of the receiver.
recipient.email	String	Optional, Must match length: max = 254	The email address of the Recipient.
recipient.governmentIds[]	Array	Optional	This array contains data strings that each identify a Government ID number for the Recipient;
qrData	String	Optional	The Mastercard QR data for P2M payments. MaxLength: 237.
transactionPurpose	String	Optional	The purpose of the transaction. Valid numeric values: 00 = Family Support, 01 = Regular Labor Transfers (expatriates), 02 = Travel & Tourism, 03 = Education, 04 = Hospitalization and Medical Treatment, 05 = Emergency Need, 06 = Savings, 07 = Gifts, 08 = Other, 09 – 15 = Reserved
additionalMessage	String	Optional	Message a financial institution will associate to the transfer and may display. Max length is 65.
paymentType	String	Optional	The appropriate payment type for the funds transfer taking place. Default value: P2M. Valid values: P2M = Merchant payment, P2P = Person to person

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: 255

{
  "transactionId" : "68f59ba2-9cbb-4ab9-8606-5f483f97482d",
  "transactionStatus" : "APPROVED",
  "transactionStatusReason" : "APPROVED",
  "processingCode" : "28",
  "fundsAvailability" : "IMMEDIATE",
  "transmissionDateTime" : "2019-06-17T18:05:02Z"
}

errorStatus = INVALID_INPUT_FORMAT.

HTTP/1.1 400 BAD REQUEST
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

{
    "traceId": "b4ce7ad5-758d-444f-90b3-ffbadb757e3f",
    "errorStatus": "INVALID_INPUT_FORMAT",
    "message": "Invalid Format",
    "data": {
        "error": [
            {
                "source": "recipient.accountURI.Expiration date",
                "reasonCode": "INVALID_INPUT_FORMAT",
                "errorDetailCode": "062000",
                "description": "Invalid Format"
            }
        ]
    }
}

A formal table with Reason Code

Error Detail Code	Reason Code	Description
062000	INVALID_INPUT_FORMAT	Value contains invalid character
072000	INVALID_INPUT_LENGTH	Invalid length
082000	INVALID_INPUT_VALUE	Invalid value
092000	MISSING_REQUIRED_INPUT	Value is required
110501	RESOURCE_ERROR	Duplicate value
110503	RESOURCE_ERROR	Account not eligible
110505	RESOURCE_ERROR	Invalid currency
110507	RESOURCE_UNKNOWN	Record not found
110510	RESOURCE_ERROR	Invalid Request
110537	RESOURCE_ERROR	Value is not supported for the merchant
130004	DECLINE	Per transaction maximum amount limit reached
130006	DECLINE	Transaction Limit is less than the minimum configured for the partner
130010	DECLINE	Partner not onboarded for the network to reach the account

errorStatus = ERROR_BAD_TOKEN.

HTTP/1.1 400 BAD REQUEST
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

{
    "traceId": "{{traceId}}",
    "errorStatus": "ERROR_BAD_TOKEN"
}

errorStatus = CANT_FIND_PAYMENT_TOKEN.

HTTP/1.1 404 NOT FOUND
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

{
    "traceId": "89cdfc2b-346e-42d0-b20d-f3afa01cec68",
    "errorStatus": "CANT_FIND_PAYMENT_TOKEN",
    "message": "Payment token with given id was not found"
}

errorStatus = SYSTEM_ERROR.

HTTP/1.1 500 INTERNAL SERVER ERROR
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

{
    "traceId": "1c8d4f1f-16db-4c43-bdce-0fe43ae39195",
    "errorStatus": "SYSTEM_ERROR",
    "message": "Internal exception occurred.",
    "data": {
        "error": [
            {
                "source": "SYSTEM",
                "reasonCode": "SYSTEM_ERROR",
                "errorDetailCode": null,
                "description": "Internal exception occurred."
            }
        ]
    }
}

Response fields

Examples

Authentication

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

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 ThreeDs 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

Request

Base request:

POST /mobile-api/authentication/v2/init HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Mobile eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJiNjUzNGJhIiwiZXhwIjoxNjUxNzU2Njk4fQ.tBs5Os24ux-zmYNGYx5MCRAIYOg4Wtnu51NGs39doZ0
Product-Name: TestProduct
Content-Length: 639
Host: localhost:8080

{
  "authenticationId" : "authenticationId",
  "amount" : 1000,
  "currency" : "PLN",
  "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",
  "challengeNotificationUrl" : "https://notification.verestro.com",
  "authenticationType" : "PAYMENT"
}

Encrypted request:

POST /mobile-api/authentication/v2/init HTTP/1.1
Content-Type: application/x-jwe-encryption-body+json;charset=UTF-8
Authorization: Mobile eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJiNjUzNGJhIiwiZXhwIjoxNjUxNzU2Njk4fQ.tBs5Os24ux-zmYNGYx5MCRAIYOg4Wtnu51NGs39doZ0
Product-Name: TestProduct
Content-Length: 101
Host: localhost:8080

{
  "value" : "eyJ0eXAiONFIiwiZWDTSIsImlhdCI6MTYRjwJTAHd1iw.WqJ1NtTDapO40RPA.ub5wVd2yaaCX-PdjWq..."
}

Request headers

Request body with header: X-Encryption-Public-Key

Type	Value	Constraints	Description
Authorization	Mobile bG9naW46YWNrbWU=	Required	Device token with "Mobile " prefix
Product-Name	TestProduct	Required	Application product name
Content-Type	application/x-jwe-encryption-body+json	Optional	Header must be present if the request body is encrypted using the JWE standard.
X-Encryption-Public-Key		Optional	Header must be present if the response body is to be encrypted using the JWE standard. Public key must be encoded Base64.

Request fields

Base request:

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")
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	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
challengeNotificationUrl	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

Encrypted request:

Path	Type	Constraints	Description
value	String	Required	The field contains encrypted JSON using the JWT standard. JSON is the same as the request body from the section: BASE_REQUEST.

Response

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

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

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

Response fields

Base 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; 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, 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

Errors

Request body with header: X-Encryption-Public-Key

Http Status	Error Status	Description
400 - Bad Request	PROCESS_NOT_ALLOWED	Method not allowed - invoke calculate commission method is necessary first.
400 - Bad Request	ERROR_SENDER_CARD_NOT_ACTIVE	Sender card is not active

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

Request

Base request:

POST /mobile-api/authentication/v2/continue HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Mobile eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJiNjUzNGJhIiwiZXhwIjoxNjUxNzU2Njk4fQ.tBs5Os24ux-zmYNGYx5MCRAIYOg4Wtnu51NGs39doZ0
Product-Name: TestProduct
Content-Length: 82
Host: localhost:8080

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

Encrypted request:

POST /mobile-api/authentication/v2/continue HTTP/1.1
Content-Type: application/x-jwe-encryption-body+json;charset=UTF-8
Authorization: Mobile eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJiNjUzNGJhIiwiZXhwIjoxNjUxNzU2Njk4fQ.tBs5Os24ux-zmYNGYx5MCRAIYOg4Wtnu51NGs39doZ0
Product-Name: TestProduct
Content-Length: 101
Host: localhost:8080

{
  "value" : "eyJ0eXAiONFIiwiZWDTSIsImlhdCI6MTYRjwJTAHd1iw.WqJ1NtTDapO40RPA.ub5wVd2yaaCX-PdjWq..."
}

Request headers

Request body with header: X-Encryption-Public-Key

Type	Value	Constraints	Description
Authorization	Mobile bG9naW46YWNrbWU=	Required	Device token with "Mobile " prefix
Product-Name	TestProduct	Required	Application product name
Content-Type	application/x-jwe-encryption-body+json	Optional	Header must be present if the request body is encrypted using the JWE standard.
X-Encryption-Public-Key		Optional	Header must be present if the response body is to be encrypted using the JWE standard. Public key must be encoded Base64.

Request fields

Path	Type	Constraints	Description
authenticationId	String	Required	Unique authentication identifier per Product
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 threeDsMethodUrl is empty

Response

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

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

Response fields

Base 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

Finalize Authentication

Request body with header: X-Encryption-Public-Key.

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

Request

Base request:

POST /mobile-api/authentication/v2/finalize HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Mobile eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJiNjUzNGJhIiwiZXhwIjoxNjUxNzU2Njk4fQ.tBs5Os24ux-zmYNGYx5MCRAIYOg4Wtnu51NGs39doZ0
Product-Name: TestProduct
Content-Length: 45
Host: localhost:8080

{
  "authenticationId" : "authenticationId"
}

Encrypted request:

POST /mobile-api/authentication/v2/finalize HTTP/1.1
Content-Type: application/x-jwe-encryption-body+json;charset=UTF-8
Authorization: Mobile eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJiNjUzNGJhIiwiZXhwIjoxNjUxNzU2Njk4fQ.tBs5Os24ux-zmYNGYx5MCRAIYOg4Wtnu51NGs39doZ0
Product-Name: TestProduct
Content-Length: 101
Host: localhost:8080

{
  "value" : "eyJ0eXAiONFIiwiZWDTSIsImlhdCI6MTYRjwJTAHd1iw.WqJ1NtTDapO40RPA.ub5wVd2yaaCX-PdjWq..."
}

Request headers

Request body with header: X-Encryption-Public-Key

Type	Value	Constraints	Description
Authorization	Mobile bG9naW46YWNrbWU=	Required	Device token with "Mobile " prefix
Product-Name	TestProduct	Required	Application product name
Content-Type	application/x-jwe-encryption-body+json	Optional	Header must be present if the request body is encrypted using the JWE standard.
X-Encryption-Public-Key		Optional	Header must be present if the response body is to be encrypted using the JWE standard. Public key must be encoded Base64.

Request fields

Base request:

Response

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

Response fields

Base 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".