Notifications

To work with TMS notifications it is required to: - prepare an endpoint to which the notifications are to be delivered. - provide USP team with the URL of the endpoint

Notifications are sent when there is a need to notify the partner that some event has occured. The event can be a completed payment, a waring that addictional redirection is required and so on.

After the notification is sent TMS expects to receive a response with a valid status which indicates it is accepted. In other case the notification will be renewed every few minutes until it gets accepted or it would be expired after 10.

Example notification
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
    "jsonrpc": "2.0",
    "id": "<call_id>",
    "method": "new_payment",
    "params": {
        "user_id": "<user-indetificator>",
        "user_email": "<user-email>",
        "amount": "<payment-amount>",
        "currency": "<currency-code>",
        "order_id": "<order-id>"
        "signature": "<signature>"
    }
}
Example response
1
2
3
4
5
6
7
{
    "jsonrpc": "2.0",
    "id": "<call_id>"
    "result": {
        "status": 1
    }
}

Every notification is signed using a secret which is exchanged between the partner and USP team. The partner can verify the signature of received notifications to ensure it originates from TMS.

The Events for notifications are:

  • Payment for a tranasaction is completed

  • Redirection is requested (eg for 3ds)

  • Payment failure

  • Invoice for a transaction is ready

Payment is completed:

method: new_payment

params:

  • “user_id”: str - User ID passed by the seller to set_transaction as ext_user_id param

  • “user_email”: str - User’s email,

  • “amount”: numeric - payment’s amount,

  • “currency”: str -payment’s currency,

  • “order_id”: int - transaction id passed by the seller to set_transaction as trans_ext_id param

  • “card_details”: object - (optional - present if card registretion transaction was preformed){

    • “card_access_key”: str- access key representing the token for charging the registered card in the future,

    • “card_issuer”: str - (VISA, MASTER CARD, MAESTRO),

    • “card_number_mask”: str - (eg 9876 **** **** 1234)

  • “signature”: str - a result of sha1 function from concatenation of strings for params: user_id, user_email, amount, currency, order_id, secret_key

If the configuration for the used payment channels allows that it is possible to set status in response to “REJECT” or -1 and in that way to reqeust from TMS to return the payment to the buyer.

Redirection required

method: error_notification

params:

  • “order_id”: str - transaction id passed by the seller to set_transaction as trans_ext_id param

  • “message”: str - redirection url for 3ds verification

  • “status”: int - for redirection value is -302

  • “signature”: str - a result of sha1 function from concatenation of strings for order_id param

Transaction Failure

method: error_notification

params:

  • “order_id”: str - transaction id passed by the seller to set_transaction as trans_ext_id param

  • “message”: str - in case of redirection it’s value consists of the redirection url for 3ds verification

  • “status”: int Status code for the problem

  • “signature”: str - a result of sha1 function from concatenation of strings for order_id param and secret_key

Statuses:

  • -302: Redirection required (‘message’ contains the location)

  • -3: Payment rejected

  • -6: internal TMS error

  • -7: internal TMS error

  • -8: internal TMS error

Invoice created:

method: new_invoice

params:

  • “order_id”: transaction id passed by the seller to set_transaction as trans_ext_id param

  • “invoice_id: id assigned by SAP to the created invoice

  • “signature”: a result of sha1 function from concatenation of strings for order_id param and secret_key