Callbacks

POST api/callback/{paymentTypeName}/{actionType}

Request: POST api/callback/{paymentTypeName}/{actionType} POST api/callback/{paymentTypeName}/{actionType}?api-version=2.0

Request information

Request information

Name

Value

Description

Data Type

Example

paymentTypeName

required

PartnerId provided by LINK Mobility AS

string

“some-string“

actionType

required

Transaction Id

string

“some-string“

Response

Response

Name

Description

RequestMessage

HttpRequestMessage

StatusCode

HttpStatusCode

Content

HttpContent

 

Callbacks are executed from Mobile Invoice servers towards your URLs provided in MI request payload.

If the server behind your Callback URL has a firewall protection, you should whitelist these outbound IPs below

137.117.228.149, 137.117.228.150, 137.117.228.217, 137.117.225.138, 40.113.150.153, 40.114.255.140, 13.69.103.135, 40.114.255.135, 40.114.250.3, 20.103.131.252, 20.103.132.212, 20.103.133.137, 20.126.241.193, 20.126.243.229, 20.126.244.108, 137.117.224.218

Authentication

We support basic authentication for all callbacks. All credentials should be encoded(special characters should be escaped). For example check this link. 

If your endpoint has basic authentication your URL should look like the following example:
https://username:password@yourdomain.com/api/status-callback?id={{transactionId}}&status={{status}}&paymentType={{paymentType}}

The provided username and password will be added as Authentication header in the request.



smsStatusCallbackUrl

This callback is related to the text message delivery status.

Verb: GET
Examplehttps://username:password@yourdomain.com/api/sms-status-callback?pretransaction={{PreTransactionId}}&smssent={{SmsNotificationDelivered}}&reference={{ReferenceId}} 
The query parameters in the example pretransaction, smssent and reference as well as all others can be changed according to the implementation of the callbacks for every customer.
Triggers: When delivery report is received (when the operator notifies about the delivery of the message).

Available parameters

Description

Available parameters

Description

{{PreTransactionId}}

Тhe internal ID of the preТransaction.

{{SmsNotificationDelivered}}

The delivery status of the text message (if it was delivered to the specified phone number).
True if the message was delivered to the phone number, false if the message delivery failed.

{{ReferenceId}}

The value of the “referenceId” parameter that was added in the POST request towards the PayCore API.
If it was not added in the POST request, the value of this parameter in the callback will be empty.

{{Msisdn}}

The phone number of the recipient of the text message.

{{TransactionReconRef}}

The value of the “ocr” parameter that was added in the POST request towards the PayCore API.
If it was not added in the POST request, the value of this parameter in the callback will be empty.

{{OrderNumber}}

The value of the “orderNumber” parameter that was added in the POST request towards the PayCore API.
If it was not added in the POST request, the value of this parameter in the callback will be empty.

{{Key of the custom property}}

If in the initial preTransaction POST request custom property(s) is added, the smsStatusCallbackUrl should specify the key of custom property(s) and they will be replaced with the value(s).

{{SmsNotificationParts}}

The number of the parts of the text message (if a message is too long it can be split into two or more parts).



statusCallbackUrl

This callback is related to the payment transaction status.

Verb: GET
Examplehttps://username:password@yourdomain.com/api/status-callback?id={{transactionId}}&status={{status}}&type={{paymentType}}
The query parameters in the example id, status and type as well as all others can be changed according to the implementation of the callbacks for every customer.
Triggers: When the preTransaction POST request is sent towards the PayCore API and whenever the status of the payment transaction is updated.

Available parameters

Description

Available parameters

Description

{{TransactionId}}

The internal preTransaction ID (the same as {{PreTransactionId}} in the smsStatusCallbackUrl)

{{Currency}}

The currency of the payment transaction

{{Amount}}

The amount of the payment transaction

{{PaymentType}}

The Payment provider that has been selected for completing the payment.

{{ReferenceId}}

The value of the “referenceId” parameter that was added in the POST request towards the PayCore API.
If it was not added in the POST request, the value of this parameter in the callback will be empty.

{{PaymentTransactionId}}

The ID of the transaction on the Payment Provider’s side.

{{PaymentEntity}}

The phone number that is assigned to the end user that will pay. For some payment providers the phone number of the payer is the unique ID in their system.

{{Status}}

The status of the payment transaction through the process (not only the final payment status).
Please refer to the description of the statuses below.

{{Success}}

A final payment statement based on the statuses of the transaction.
True if the transaction was successfully paid or false if the transaction failed to be paid.

{{StatusDescription}}

The description of the error that caused the payment of the transaction to fail. It is provided by the payment provider.
In case of a successful transaction, this value will be empty.

{{TransactionReconRef}}

The value of the “ocr” parameter that was added in the POST request towards the PayCore API.
If it was not added in the POST request, the value of this parameter in the callback will be empty.

{{StatusCode}}

Annulled - usually when the end user didn’t act upon a given time; time out (that may vary for different providers).
Authorized - when the payment is paid from the end user but the amount is still not captured by the merchant.
Captured - when payment is completed successfully.
Failed - when payment has failed (not enough money, card declined, etc.)
Refunded - amount is refunded to the payer after it was completed successfully.
Registered - the request for the payment on the payment provider’s side is registered.

{{PaymentDateUtc}}

The date when the payment has been completed (regardless if it was successful or not).

{{Key of the custom property}}

If in the initial preTransaction POST request custom property(s) is added, the smsStatusCallbackUrl should specify the key of custom property(s) and they will be replaced with the value(s).



Statuses

Accessed - the end user has clicked the link in the SMS and opened the landing page for selecting a payment provider.

Authorize: Failed - the authorization towards the selected payment provider has failed (for example if the merchant’s credentials are invalid).

Authorize: OK - the payment has been approved by the end user but still it hasn’t been captured/collected by the merchant.

Capture: Failed - the capture of the already approved payment by the end user has failed (the reason of the failed capture should be specified in the {{StatusDescription}} parameter in the callbacks).

Capture: OK - the payment transaction has been captured (completed successfully).

Refund: OK - the captured payment has been refunded.

Register: Annulled - the end user has not acted upon a given time period and the transaction is terminated by payment provider side.

Register: Failed - the payment transaction has failed to be registered by the payment provider (for example if a payment is sent to the payment provider for an end user that doesn’t have an account in the specific payment provider).

Register: OK - the payment transaction has been successfully registered on the payment provider’s side and awaits for end user’s actions.



Callbacks based on the “transaction’s journey”

  1. Text message is delivered/not delivered to the stated phone number (based on the operator’s delivery report)
    Callback to smsStatusCallbackUrl

  2. End user clicks on the text message’s link and opens the mobile invoice landing page
    Callback to statusCallbackUrl

  3. End user selects a payment provider and it is redirected to the provider’s page/app
    Callback to statusCallbackUrl

  4. The payment transaction’s status is changed on the provider’s side (for example the end user has accepted to pay the transaction; the payment transcation is captured successfully; the capture failed; the end user didn’t act on the payment at all)
    Callback to statusCallbackUrl



Feeling lost? Click on this link! Portal page