Services

Pay Service

GET /aalam/base/service/pay

Service to handle the payment solutions. This would return the paymentURL that the apps can redirect to land on the payment gatewayinterface. This API will be hooked by payment solution providing apps.This API can be used for payment refunds as well.

Parameters

  • contact_id

The contact_id of the customer who is going to pay.

  • amount

The amount to pay or refund.

  • ack_url

The URL to be invoked when a transaction is completed successfully. This parameter will be ignored if refund is present. This URL will be passed with three parameters namely, ‘txn_id’ - the ID for this transaction, ‘amount’ - the amount collected during this transaction, ‘pg’ - the name of the payment gateway used.

  • ack_meth

The URL method to be invoked when a transaction is completed successfully. This parameter will be ignored if refund is present

  • redirect_to

If present, after the transaction is completed, user will be redirected to this URL. This will be ignored if refund is present

  • refund

If present, the respective app that completed the transaction indicated by the ‘txn_id’ parameter which was passed while invoking ‘ack_url’ will initiate the refunding.

  • txn_id

The ‘txn_id’ for the successfull transaction that was passed while ‘ack_url’ was invoked. This will be used only on refunds.

  • pg

The name of the payment gateway solution which made the transaction and that was passed while ‘ack_url’ was invoked. This will be used only on refunds.

  • reason

Reason for refund. This is an optional parameter.

  • det

This is a URL which when requested will send the payment details including the ack_url, amount, ack_meth, redirect_to

Outputs

  • Sends the URL of the payment gateway if the ‘Accept:’ was ‘application/json’ else redirects to the app handling the payments if there is just one app or a page with the list of options and link to each payment option

    Status code: 200

    Content type: application/json

    Content specification

{
    "url": "The url to the payment app"
}

Hooks Input

  • The app would return the URL to which the user has to be redirected to start the payment transaction in case of non-refunds, else the method and URL for refunding will be returned Content type: application/json Content specification

{
    "url": "Entry url to initiate the payment transaction or refund."
    "method": "The HTTP method to be invoked on the 'url'",
    "title": "Title for the gateway, possibly the list of payment methods",
    "img": "URL to an image that is 92x92 px size"
}

Communicate Service

POST /aalam/base/service/communicate

This service is responsible to communicating message on multiplechannels. The apps that can communicate on a medium will be hookkingthis API and would return the URLs to which the content to be deliveredwill be sent. This API accepts JSON input describing the contact_idsand the medium of communication and the content for that medium.

Permissions

Flags

  • deny_anon

Parameters

  • action

This is an optional parameter. For now action can only be create_template. If set, the input data should have template text. The text to be substituted should have a placeholder like {name-of-substitution}. For example, for a template I am a {gender}, gender is the name of the substitution and it can match I am a boy or I am a girl.

Outputs

  • The communication happens asynchronously so this call will always be successful. If the Accept header is application/json, it will return the APIs, and the client will have to take care of the actual communication.

    Status code: 200

Inputs

  • In the JSON input ‘contact_ids’ field is mandatory. This should have the list of contact ids to which the message has to be sent. The other fields represent the name of the medium and the corresponding content as its value. If the contacts have fields in the name of the mediums, those fields values will be used for communication. For example, if a contact has ‘Mobile’, ‘Email’ and ‘Facebook’ fields and, the communicate service will deliver content to all these channels provided it has the necessary apps and the client is requesting to send to all these channels.

    Content type: application/json

    Content specification

{
    "contact_ids": [1, 2, 3, 4, ...],
    "Email": {"body": "This is the body",
              "to": "Optional field to send emails to custom email ids",
              "subject": "This is the subject"},
    "Mobile": "This is the SMS content",
    "Facebook": "This is the content to be posted on Facebook",
    "<Channel name, e.x, Email, Mobile, ..>": "<Corresponding content>",
    ...
}

Hooks Input

  • Apps hooking this will return the URL, method and the name of the medium to communicate. Content type: application/json Content specification

{
    "url": "URL to be invoked to start communication"
    "method": "The HTTP method to be invoked on the 'url'"
    "medium": "Name of the communication medium"
}

Communicate Service

POST /aalam/base/service/communicate

This service is responsible to communicating message on multiplechannels. The apps that can communicate on a medium will be hookkingthis API and would return the URLs to which the content to be deliveredwill be sent. This API accepts JSON input describing the contact_idsand the medium of communication and the content for that medium.

Permissions

Flags

  • deny_anon

Parameters

  • action

This is an optional parameter. For now action can only be create_template. If set, the input data should have template text. The text to be substituted should have a placeholder like {name-of-substitution}. For example, for a template I am a {gender}, gender is the name of the substitution and it can match I am a boy or I am a girl.

Outputs

  • The communication happens asynchronously so this call will always be successful. If the Accept header is application/json, it will return the APIs, and the client will have to take care of the actual communication.

    Status code: 200

Inputs

  • In the JSON input ‘contact_ids’ field is mandatory. This should have the list of contact ids to which the message has to be sent. The other fields represent the name of the medium and the corresponding content as its value. If the contacts have fields in the name of the mediums, those fields values will be used for communication. For example, if a contact has ‘Mobile’, ‘Email’ and ‘Facebook’ fields and, the communicate service will deliver content to all these channels provided it has the necessary apps and the client is requesting to send to all these channels.

    Content type: application/json

    Content specification

{
    "contact_ids": [1, 2, 3, 4, ...],
    "Email": {"body": "This is the body",
              "to": "Optional field to send emails to custom email ids",
              "subject": "This is the subject"},
    "Mobile": "This is the SMS content",
    "Facebook": "This is the content to be posted on Facebook",
    "<Channel name, e.x, Email, Mobile, ..>": "<Corresponding content>",
    ...
}

Hooks Input

  • Apps hooking this will return the URL, method and the name of the medium to communicate. Content type: application/json Content specification

{
    "url": "URL to be invoked to start communication"
    "method": "The HTTP method to be invoked on the 'url'"
    "medium": "Name of the communication medium"
}

Communicate Service V2

POST /aalam/base/service/communicatev2

This service is responsible to communicating message on multiplechannels. The apps that can communicate on a medium will be registeringthe URL to which the content to be delivered will be sent. This APIaccepts JSON input describing the contact_ids and the medium ofcommunication and the content to fill in the templates fixed for thatmedium

Permissions

Flags

  • deny_anon

Outputs

  • The communication happens asynchronously so this call will always be successful. If the Accept header is application/json, it will return the APIs, and the client will have to take care of the actual communication.

    Status code: 200

Inputs

  • In the JSON input ‘contact_ids’ field is mandatory. This should have the list of contact ids to which the message has to be sent. The other fields represent the name of the medium and the corresponding content as its value. If the contacts have fields in the name of the mediums, those fields values will be used for communication. For example, if a contact has ‘Mobile’, ‘Email’ and ‘Facebook’ fields and, the communicate service will deliver content to all these channels provided it has the necessary apps and the client is requesting to send to all these channels.

    Content type: application/json

    Content specification

{
    "contact_ids": [1, 2, 3, 4, ...],
    "placeholder_data": {template fillers},
    "channel-name": "custom destination for the channel, (optional)"
    "app": "provider-code/app-code (optional) if request from the app"
    "category": {
        "to": "Optional destination when contact_ids not present",
        .. optional data like "attachments" for email}:,
    "event": "Name of the message event, given while registration",
}