Paiwise API documentation

The following documentation describes the API resources published by the Paiwise service. External payment service providers can implement this API to publish their payment services to users of the Neuron®.

Security

All requests made to the external payment service will be made using HTTPS. The Neuron® will validate the name of the payment service, by validating the server certificate of the external service.

In requests made to the external payment service, the token will be provided in a Bearer HTTP header. This token should be seen as an API key, and does not change. It provides very little security.

To validate the identity of the Neuron®, the payment service should use Mutual TLS. If enabled by the external service provider, the Neuron® will send the public part of its server certificate in the request, enabling the external payment service to validate the origin of the call, and make sure the caller has the right to use the associated token.

Host

The host name is the domain name of the server hosting the service. All API calls will be made to this host name. When listing resources for the API below, it will be assumed they are prefixed by https://HOSTNAME, where HOSTNAME is replaced by the domain name provided here.

Buying eDaler®

The following resources describe the steps for allowing a user on a TAG Neuron® to buy eDaler®. An outline is as follows:

1. A list of services available for the purpose is requested
2. User selects a service.
3. Payment options are retrieved and presented to the user, to simplify user input.
4. User initiates the buying of eDaler®.
5. An optional web page can be presented to the user.
6. State of the process is polled by the Neuron®, until a response is returned or the process is cancelled.

Getting list of services for buying eDaler®

The /payment/available-buy-payment-method resource returns available payment methods for buying eDaler®.

Request

{
	"currency": CURRENCY_CODE,
	"country": COUNTRY_CODE
}

Response

[
	{
		"id": SERVICE_ID,
		"displayName": DISPLAY_NAME,
		"logo": {
			"url": LOGO_URL,
			"width": LOGO_WIDTH,
			"height": LOGO_HEIGHT
		},
		"contractId": CONTRACT_ID,
		"fields": [
			{
				"field": FIELD_ID,
				"dataType": FIELD_TYPE,
				"required": FIELD_REQUIRED
			}, ...],
		"endpoint": {
			"method": HTTP_METHOD,
			"url": SERVICE_URL,
			"optionsUrl": OPTIONS_URL
		}
	},
	...
]

User selecting service for buying eDaler®

The user selects a service, by creating and signing a smart contract, based on the template defined for the service. The template must include parameters referenced to by the service (FIELD_ID) that have the corresponding types. The contract must also contain the amount to buy, and in what currency. References to these parameters are provided in the machine-readable section of the contract. The machine-readable section must also contain a reference to the external payment service to be used.

The following example contains the machine-readable section of a smart contract used to initiate the buying of eDaler® using an external payment service using this service:

<BuyEDaler serviceId="SERVICE_ID" serviceProvider="Paiwise.Internal.PaiwisePaymentServices" xmlns="https://paiwise.tagroot.io/Schema/PaymentInstructions.xsd">
	<Amount>
		<ParameterReference parameter="AMOUNT_PARAMETER" />
	</Amount>
	<Currency>
		<ParameterReference parameter="CURRENCIY_PARAMETER" />
	</Currency>
</BuyEDaler>

Once the contract has been properly signed, the Neuron® will process and validate it. Once validated, and found to be OK, the process will be initiated.

Retrieving payment options for buying eDaler®

A JSON object comprised of the fields listed in the service description is sent in this request. Some of the fields in this JSON object are predefined, others are taken from the legal identity of the user, attempting to buy eDaler®. Parameters that are collected via the smart contract, and not available in the legal identity, are set to null, for reference. The smart contract has not been signed at this point.

Response

The response to this request is a JSON array of object. Each object represents one option that the user can select from a list, with related parameters. This may be bank name, bank code, bank account, etc. If an option is presented to the user, and the user selects this option, all named parameters will be set accordingly.

Note It is up to the external service provider, who defines the smart contract template, to define the property names of the options returned. The client application will receive these options, and create drop-down-lists where possible, where the user can select among available values, instead of having to manually fill in the corresponding parameter values.

Initiating process of buying eDaler®

Once sufficient information has been collected from the user, the payment process is initiated by the Neuron®. When the Neuron® initiates the process to buy eDaler®, an HTTP POST request is made to the SERVICE_URL provided by the service.

Request

A JSON object comprised of the fields listed in the service description is sent in this request. Some of the fields in this JSON object are predefined, others are taken from the smart contract that has been signed, or the legal identity of the user, buying the eDaler®.

Response

If the external service provider accepts the request as valid, it can respond in the following ways:

Amount paid

If immediately accepting the payment, a paid response is returned. In this case, polling for a result will not be necessary, and the process is considered completed.

{
	"status": "paid",
	"amount": AMOUNT,
	"currency": CURRENCY
}

Payment pending

If the result of the request is not immediately known, a pending response is returned. In this case, the Neuron® will regularly poll the external payment service, until the process concludes, fails or times out.

{
	"status": "pending",
	"id": TRANSACTION_ID,
	"redirectUrl": CLIENT_URL
}

Note: If the CLIENT_URL is provided in the response, it is sent to the user of the Neuron®, and the client will open it out-of-band (i.e. without passing the Neuron®). The external payment service can publish such client URLs to collect additional information from the user, before accepting or rejecting the request.

Payment cancelled

If the result of the request is cancelled by the user, or the external service itself, a cancelled response is returned. In this case, the Neuron® will terminate the process, without any eDaler® being bought.

{
	"status": "cancelled"
}

Polling status of process to buy eDaler®

If a pending response is returned, the Neuron® will begin a process of polling the external payment service, to get any updates on the status of the process. At the same time, if a client URL is presented to the client, the client can provide additional information to the external payment service out-of-band.

Request

When polling the external payment service, a POST is made to the /payment/retrieve resource on the external payment host. A simple JSON object is sent with this request:

{
	"id": TRANSACTION_ID
}

Response

The response to the request, can be any of the paid, pending or cancelled responses described earlier.

Note: The Neuron® will cancel the polling after a given number of minutes. This number is set when you configure the Paiwise service in the Neuron®.

Cancelling a process for buying eDaler®

If a process is still pending after the timeout threshold has been reached, the Neuron® will cancel the process.

Request

Cancelling a request is done by sending a POST to /payment/cancel containing the following simple JSON object (same as when polling):

{
	"id": TRANSACTION_ID
}

Response

The response to the cancel request is:

{
	"status": STATUS,
	"message": MESSAGE
}

Selling eDaler®

The following resources describe the steps for allowing a user on a TAG Neuron® to sell eDaler®. An outline is as follows:

1. A list of services available for the purpose is requested
2. User selects a service.
3. Payment options are retrieved and presented to the user, to simplify user input.
4. User initiates the selling of eDaler®.
5. An optional web page can be presented to the user.
6. State of the process is polled by the Neuron®, until a response is returned or the process is cancelled.

Getting list of services for selling eDaler®

The /payout/available-sell-payment-method resource, returns available payment methods for selling eDaler®.

Request

{
	"currency": CURRENCY_CODE,
	"country": COUNTRY_CODE
}

Response

[
	{
		"id": SERVICE_ID,
		"displayName": DISPLAY_NAME,
		"logo": {
			"url": LOGO_URL,
			"width": LOGO_WIDTH,
			"height": LOGO_HEIGHT
		},
		"contractId": CONTRACT_ID,
		"fields": [
			{
				"field": FIELD_ID,
				"dataType": FIELD_TYPE,
				"required": FIELD_REQUIRED
			}, ...],
		"endpoint": {
			"method": HTTP_METHOD,
			"url": SERVICE_URL,
			"optionsUrl": OPTIONS_URL
		}
	},
	...
]

User selecting service for selling eDaler®

The user selects a service, by creating and signing a smart contract, based on the template defined for the service. The template must include parameters referenced to by the service (FIELD_ID) that have the corresponding types. The contract must also contain the amount to sell, and in what currency. References to these parameters are provided in the machine-readable section of the contract. The machine-readable section must also contain a reference to the external payment service to be used.

The following example contains the machine-readable section of a smart contract used to initiate the selling of eDaler® using an external payment service using this service:

<SellEDaler serviceId="SERVICE_ID" serviceProvider="Paiwise.Internal.PaiwisePaymentServices" xmlns="https://paiwise.tagroot.io/Schema/PaymentInstructions.xsd">
	<Amount>
		<ParameterReference parameter="AMOUNT_PARAMETER" />
	</Amount>
	<Currency>
		<ParameterReference parameter="CURRENCIY_PARAMETER" />
	</Currency>
</SellEDaler>

Once the contract has been properly signed, the Neuron® will process and validate it. Once validated, and found to be OK, the process will be initiated.

Retrieving payment options for selling eDaler®

A JSON object comprised of the fields listed in the service description is sent in this request. Some of the fields in this JSON object are predefined, others are taken from the legal identity of the user, attempting to buy eDaler®. Parameters that are collected via the smart contract, and not available in the legal identity, are set to null, for reference. The smart contract has not been signed at this point.

Note: While the name and address fields are listed here specifically, they were added before the concept of Role Reference Parameters were introduced to smart contracts. By adding such role reference parameters to your smart contracts, you can extract any information necessary from the legal identity of the signatory, without having to define explicit parameters the user has to fill in.

Response

The response to this request is a JSON array of object. Each object represents one option that the user can select from a list, with related parameters. This may be bank name, bank code, bank account, etc. If an option is presented to the user, and the user selects this option, all named parameters will be set accordingly.

Note It is up to the external service provider, who defines the smart contract template, to define the property names of the options returned. The client application will receive these options, and create drop-down-lists where possible, where the user can select among available values, instead of having to manually fill in the corresponding parameter values.

Initiating process of selling eDaler®

Once sufficient information has been collected from the user, the payment process is initiated by the Neuron®. When the Neuron® initiates the process to sell eDaler®, an HTTP POST request is made to the SERVICE_URL provided by the service.

Request

A JSON object comprised of the fields listed in the service description is sent in this request. Some of the fields in this JSON object are predefined, others are taken from the smart contract that has been signed, or the legal identity of the user, selling the eDaler®.

Note: While the name and address fields are listed here specifically, they were added before the concept of Role Reference Parameters were introduced to smart contracts. By adding such role reference parameters to your smart contracts, you can extract any information necessary from the legal identity of the signatory, without having to define explicit parameters the user has to fill in.

Response

The Output follows the same pattern as for buying eDaler®.

Polling status of process to sell eDaler®

The polling process follows the same pattern as for buying eDaler®.

Cancelling a process for buying eDaler®

Cancelling a process to sell eDaler®, follows the same pattern as for cancelling a process for buying eDaler®.