Remote Messaging API for Non-Companion Clients
Remote messaging API allows Paymentology to call you to send administrative advice messages for Card API. These advice messages are sent using webhook-like schema. If you are integrating the service, you must create an endpoint accessible from the Paymentology network, which would be able to process the requests outlined below.
How it works
- All messages are sent as HTTP POST requests.
- Message content is always a JSON document.
- Methods structure is defined below, and it corresponds to the schema of the JSON document sent.
- The message type (eg. 3DSecure.OTP, digitization.event, etc.) is to be included in the JSON message as messageType. The message will be sent using the client-supplied URL eg. http://www.example.com/api/endpoint
- In the code samples provided, we use cURL to send requests
- In the code samples provided, we use a mock endpoint for testing – https://api.voucherengine.com/remoteMessaging/v1_0/jsonMock.cfm
Expectations
Total round-trip time, including network overload, should be less than 4 seconds. Failing to meet this, the transaction is considered failed.
Security
For detailed security measures, please see the end of the Method summary – Payload Integrity Verification
Client specific headers can be used, if previously agreed, in accordance to measures used for all methods simultaneously.
Response
HTTP response code 200 (OK) is expected to confirm that the message was accepted.
Request
Path parameters
string, required
OTP challenge code
string, required
Customer reference this card is linked to
string, required
Method name: 3DSecure.OTP
string, required
Tracking number of the card, for which OTP token is being sent
string, required
Name of or information related to the merchant
integer, required
The monetary amount related the transaction
string
Dynamic generated 4 letters code to be used along with OTP messages
if Campaign is configured to.
integer, required
The local currency code of the acquirer or source location of the transaction
curl --location --request POST 'https: //api.voucherengine.com/remoteMessaging/v1_0/jsonMock.cfm' \
--header 'Authorization: CS-HMAC-SHA-256 Terminal=0123456789,Checksum=1A11111B2222222C33D44E5555C3F666F1111722228B168892D544050B9B4D3A' \
--header 'Content-Type: application/json' \
--data-raw ‘{
"challenge": "123456",
"customerReference": "12b6405c-1120-123b-b55b-12b8f5a46ac1",
"messageType": "3DSecure.OTP",
"trackingNumber": "765432100000123",
"merchantDescription": "SellerDesc4",
"transactionAmount": "5105",
"refCode": "QUJA",
"currencyCode": "840"
}'
Response
STATUS200 OK
Schema
string
Echo
string
As described in response reference
string
Echo
string
Method name: 3DSecure.OTP
string
Echo
integer
Echo
string
Echo
integer
Echo
{
"challenge": "123456",
"resultCode": "0000",
"customerReference": "12b6405c-1120-123b-b55b-12b8f5a46ac1",
"messageType": "3DSecure.OTP",
"merchantDescription": "SellerDesc4",
"transactionAmount": "5105",
"trackingNumber": "765432100000123",
"currencyCode": "840"
}
Request
Path parameters
string, required
cardholder.maskedContactDetails
string, required
Tracking number of the card, for which OTP token is being sent
string, required
Customer reference this card is linked to
curl --location --request POST 'https://api.voucherengine.com/remoteMessaging/v1_0/jsonMock.cfm' \
--header 'Authorization: CS-HMAC-SHA-256 Terminal=0123456789,Checksum=1A11111B2222222C33D44E5555C3F666F1111722228B168892D544050B9B4D3A' \
--header 'Content-Type: application/json' \
--data-raw ‘{
"messageType":"cardholder.maskedContactDetails",
"trackingNumber":"212345678900321",
"customerReference":"7353500987654321",}'
Response
STATUS200 OK
Schema
string
Status code indicating transaction result
array
Masked contact details (phone number and email address) linked with the card
STATUS 200 OK
{
"resultCode":"1",
"maskedContactDetails" : [ { "phoneNumber" : "(###) ### 4321", "emailAddress" : "t****a@g****.com" } ] ",
}
Request
Path parameters
string, required
Method name: digitization.activation
string, required
Tracking number of the card, for which tokenization is being performed
string, required
Customer reference this card is linked to
string, required
3-digit wallet identifier:
103 – Apple Pay 216 – Google Pay 217 – Samsung Pay 327 – Merchant tokenization programstring, required
OTP activation code
string, required
The ID assigned by the Token Service Provider to the Token Requestor
curl --location --request POST 'https://api.voucherengine.com/remoteMessaging/v1_0/jsonMock.cfm' \
--header 'Authorization: CS-HMAC-SHA-256 Terminal=0061218987,Checksum=a6d5abb4a4c0e5a6f45287b040ed6cccc82900454959cbf65bbe8cbbf3c24794' \
--header 'Content-Type: application/json' \
--data-raw '{"challenge":"123456","customerReference":"500110022","messageType":"digitization.activation","walletIdentifier":"217","trackingNumber":"544911100000042","tokenRequestorId":"54139059333"}'
Response
STATUS200 OK
Schema
string
Echo
integer
As described in response reference
string
Echo
string
Echo
string
Echo
string
Echo
string
Echo
{
"challenge": "123456",
"resultCode": "0000",
"customerReference": "500110022",
"messageType": "digitization.activation",
"walletIdentifier": "217",
"trackingNumber": "544911100000042",
"tokenRequestorId": "54139059333"
}
Request
Path parameters
string, required
Method name: digitization.event
string, required
MDES digitalization status:
Digitized
Stopped
Deleted
Digitization_exception
Deleted_from_Device
Replacement
complete
string, required
Tracking number of the card, for which tokenization is being performed
string, required
Customer reference the card is linked to
string, required
3-digit wallet identifier:
103 – Apple Pay
216 – Google Pay
217 – Samsung Pay
327 – Merchant tokenization program
string, required
Single digit device type identifier:
1 – Mobile phone
2 – Tablet
3 – Watch
string, required
The DPAN (Token)
string, required
Expiry date of the DPAN
string, required
Masked Funding Account PAN
string, required
Token reference
string, required
The ID assigned by the Token Service Provider to the Token Requestor
curl --location --request POST 'https://api.voucherengine.com/remoteMessaging/v1_0/jsonMock.cfm' \
--header 'Authorization: CS-HMAC-SHA-256 Terminal=0061218987,Checksum=1282C9FFD2586A2DAD5A74B003A34531310007521E65DA17F55D1B744A28B409' \
--header 'Content-Type: application/json' \
--data-raw ‘{"eventType":"complete","digitizedDeviceIdentifier":"21","digitizedPan":"5412345678908888","digitizedTokenReference":"DSACBA000012290985be8cd35f7e46f38b569829de110852","customerReference":"15e6405d-9220-453b-b66b-02d8f9a46ac7","messageType":"digitization.event","walletIdentifier":"217","digitizedFpanMasked":"5473XXXXXXXX1234","digitizedPanExpiry":"2402","trackingNumber":"533223100000004","tokenRequestorId":"54239059112"}'
Response
STATUS200 OK
Schema
string
As described in response reference
{"digitizedTokenReference":"DSACBA000012290985be8cd35f7e46f38b569829de110852","customerReference":"15e6405d-9220-453b-b66b-02d8f9a46ac7","walletIdentifier":"217","resultCode":"0000","eventType":"complete","digitizedDeviceIdentifier":"21","digitizedPan":"5412345678908888","messageType":"digitization.event","digitizedFpanMasked":"5473XXXXXXXX1234","digitizedPanExpiry":"2402","trackingNumber":"533223100000004","tokenRequestorId":"54239059112"}
digitization.activationmethods
This message signals that a token provision has been made and requires a verification method in order to push the OTP validation. The type of method will need to be returned as well as the data for the method. At the moment only activation types 1 (mobile phone number) and 2 (cardholder’s email address) are supported.
The response will follow the same conventions described in response reference but in this case it will contain additional information (the activation methods). For simplicity the input parameters are omitted although they are expected in the response.
Request
Path parameters
string, required
Method name: digitization.activationmethods
string, required
Tracking number of the card, for which tokenization is being performed
string, required
Customer reference the card is linked to
string, required
3-digit wallet identifier:
103 – Apple Pay 216 – Google Pay 217 – Samsung Pay 327 – Merchant tokenization programstring, required
The ID assigned by the Token Service Provider to the Token Requestor
string, required
Specifies which path was chosen based on our logic and rules: green, yellow, orange or red
string, required
Indicates the type of device used at the terminal.
string, required
Tokenization decision suggested by the wallet provider. One of the following values: decline, approve or require_additional_authentication
string, required
Identifies the method which the cardholder is attempting to tokenize a primary account number. One of the following values: card_on_file, card_added_manually, card_added_via_application, existing_token_credential or card_added_via_browser
curl --location --request POST 'https://api.voucherengine.com/remoteMessaging/v1_0/jsonMock.cfm' \
--header 'Authorization: CS-HMAC-SHA-256 Terminal=0061218987,Checksum=9AE9FC1FCA7602C7000B708CA10B396C0E44FF324976AF70D406C22DC0D89A9B' \
--header 'Content-Type: application/json' \
--data-raw ‘{“messageType":"digitization.activationmethods","customerReference":"15e6405d-9220-453b-b66b-02d8f9a46ac7","trackingNumber":"162961400000233","walletIdentifier":"217","tokenRequestorId":"50139059239","digitizationPath":"GREEN","digitizedDeviceType":"00","walletRecommendation":"approve",
"tokenizationPanSource":"card_on_file"}'
Response
STATUS200 OK
Schema
string
As described in response reference
array
JSON array of methods where each element has:
type: 1 (phone number) or 2 (email). value: Cardholder’s phone number (type 1) or email (type 2).{"resultCode":"0000","customerReference":"15e6405d-9220-453b-b66b-02d8f9a46ac7","messageType":"digitization.activationmethods","walletIdentifier":"217","activationMethods":[{"value":"555123451","type":1}],"trackingNumber":"162961400000233","tokenRequestorId":"50139059239"}
3DSecure.AppAuthentication
This message is used to trigger the process of cardholder authentication. You only need to respond to this message to indicate you have received the message and will initiate the cardholder authentication. Once you have completed cardholder authentication you will send a message to our ThreeDSAuthenticationOutcome API.
Messages should be as following:
Request
Path parameters
string, required
Method name: 3DSecure.AppAuthentication
string, required
Tracking number of the card, for which authorisation is being performed
string, required
Customer reference this card is linked to
string, required
Transaction ID to link all messages. The same transaction ID should be used for the following message send to Paymentology.
string, required
Amount of the transaction, formatted with currency included
string, required
Name of the merchant transaction is being done at
integer, required
Numeric value of the amount, unformatted, in minor units
integer, required
ISO code of the currency of the transaction
curl --location --request POST 'https://api.voucherengine.com/remoteMessaging/v1_0/jsonMock.cfm' \--header 'Authorization: CS-HMAC-SHA-256 Terminal=0061218987,Checksum=1282C9FFD2586A2DAD5A74B003A34531310007521E65DA17F55D1B744A28B409' \--header 'Content-Type: application/json' \--data-raw ‘{"messageType":"3DSecure.AppAuthentication","customerReference":"12e1234d-1234-123b-b12b-12d8f9a12ac7","trackingNumber":"123456700000004","transactionID":"123456-123456","purchaseAmount":"R100.00","amount":"10000", "merchant": "Itunes", "currency": "840"}'
Response
STATUS200 OK
Schema
string
As described in response reference
{"resultCode":"0000"}
Request
Path parameters
string, required
Method name: 3DSecure.AppFinalisation
string, required
Tracking number of the card, for which authorisation is being performed
string, required
Customer reference this card is linked to
string, required
Unique ID provided by the ACS
string, required
Value indicating the status. Values include:
0 – Successfully received final status
1 – Timer on browser expired before response was received
2 – General error
3 – Transaction cancelled before response was received
Note:
- The range of response codes may be expanded in the future. Other response codes, not in the table above, should not be used without explicit written confirmation. The behavior of the system is undefined when using codes not in the listing.
- Response codes should always be four-digit codes. For example, using “0” instead of “0000” (approval) can, and will, yield different than expected results.
Optional Payload Integrity Verification
In order to ensure the integrity of data, all messages can optionally (enabled per client) have a HTTP header named Authorization with a key and a hash of the entire payload.
NOTE: Unless otherwise declared – this is applicable to all the methods of the API.
Example
Authorization: CS-HMAC-SHA-256 Terminal=0061218987,Checksum=9AE9FC1FCA7602C7000B708CA10B396C0E44FF324976AF70D406C22DC0D89A9B
Method
To calculate the checksum, the payload is treated as a single UTF-8 byte stream, excluding surrounding space characters, if any. The resulting value is passed into HMAC function: HMAC(secret, payload), which signifies the HMAC-keyed hash algorithm using octet string represented by “secret” as the key and the octet string “payload” as the input string. The size of the result is the hash result size for the hash function in use. In this case, it is 32 octets for SHA-256 as mandated. The “secret” is associated with the Terminal value and shared in a separate communication medium prior to enactment of the API.
All the examples supplied in the documentation calculate the authorization header using the non existing terminal 0061218987 with the password: 1234567890
Example (javascript)
const crypto = require('crypto-js')
const authorizationTerminal = '0061218987'
const terminalPassword = '1234567890'
const payload = `{"challenge":"123456","customerReference":"500110022","messageType":"digitization.activation","walletIdentifier":"217","trackingNumber":"544911100000042","tokenRequestorId":"54139059333"}`
const hashing = crypto.HmacSHA256(payload,terminalPassword).toString(crypto.enc.Hex)
const httpHeader = 'Authorization: CS-HMAC-SHA-256 Terminal=' + authorizationTerminal + ',Checksum=' + hashing
console.log(httpHeader)
Will produce the following output:
Authorization: CS-HMAC-SHA-256 Termi-nal=0061218987,Checksum=a6d5abb4a4c0e5a6f45287b040ed6cccc82900454959cbf65bbe8cbbf3c24794
Was this page helpful?