Callbacks
POST api/callback/{paymentTypeName}/{actionType}
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 | |
---|---|
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
Example: https://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 |
---|---|
{{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). |
{{ReferenceId}} | The value of the “referenceId” parameter that was added in the POST request towards the PayCore API. |
{{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. |
{{OrderNumber}} | The value of the “orderNumber” parameter that was added in the POST request towards the PayCore API. |
{{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
Example: https://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 |
---|---|
{{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. |
{{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). |
{{Success}} | A final payment statement based on the statuses of the transaction. |
{{StatusDescription}} | The description of the error that caused the payment of the transaction to fail. It is provided by the payment provider. |
{{TransactionReconRef}} | The value of the “ocr” parameter that was added in the POST request towards the PayCore API. |
{{StatusCode}} | Annulled - usually when the end user didn’t act upon a given time; time out (that may vary for different providers). |
{{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”
Text message is delivered/not delivered to the stated phone number (based on the operator’s delivery report)
Callback to smsStatusCallbackUrlEnd user clicks on the text message’s link and opens the mobile invoice landing page
Callback to statusCallbackUrlEnd user selects a payment provider and it is redirected to the provider’s page/app
Callback to statusCallbackUrlThe 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