Overview

Three are the main concepts that are the base to build a wallet with inswitch APIs:

• Entity: represents a final customer. It can be a legal entity or a natural person.
• Wallet: represents the container of the payment methods an entity possess.
• Payment Method: represents the payment instruments that an entity can use to make payments.

As shown in the above picture, an entity can have up to one wallet, which may or may not have payment methods associated with it. A wallet is related only to one entity. On the other hand, a payment method can be associated with one or more wallets because it's possible to share payment methods between different wallets. This occurs when a customer shares a payment method to allow another customer to use it.

Entity

An entity is the representation of a final customer or company within the platform. Each instance of the platform is associated with an entity, which is the company that signed the contract with Inswitch. Multiple entities can be created within an instance to represent the company's clients, including natural persons or legal entities associated with the company.

A wallet can be defined for each entity as a container for multiple payment methods that a company or customer can use to make financial transactions.

In addition, users can be defined for each entity. A user is a pair of a username and credentials that can be used by the entity as a security factor to access resources and make transactions. Available users include:

• Phone number/pin (usernameType = mobile)
• Email/password (usernameType = email)
• Username/password (usernameType = text)

Users are not mandatory, as sometimes authentication is managed outside the platform, and resources are accessible with channel credentials.

Entity Status

Different status are defined for an entity:

The possible actions an entity is able to do when it has active/blocked or suspended state should be defined in the business portal by defining rules. In order to have more segregation in the rules that can be defined multiple custom sub-status can be defined for each state.

Entity APIs

Multiple operations can be performed over an entity:

• Create an entity
• Update entity information
• Obtain entity information
• Create an alias for an entity, an alias is information that can be used to identify an entity instead of the entityReference. Take into account that the unicity of the information selected as alias should be ensure by the use case.
• Create/update and delete users from an entity
• Change credentials for a user
• Define profile data for an entity. Profile Data is additional information that can be used to define rules.
• Define metadata from entity. Metadata is additional information that only will be store as par of an entity.

For more information about the Entity API see: Entity

Handling Errors

In the case of POST operations a success response is identified with the HTTP Code 201 (Created). A different HTTP Code Response means that there was a problem with the operation. HTTP Error codes possible for POST operations are:

• 400: Bad Request
• 401: An unauthorized execution attemp was detected.
• 403: The received token does not contain any of the required roles.
• 404: There is no resource matching the requested ID or reference. Only applicable when the resource the it's being created is over a different resource (i.e. a metadata that is created over an entity and the provided entity reference or alias does not exist).
• 500: An internal error occurred.

In the case of GET operations a success response is identified with the HTTP Code 200 (OK). In the case the resource is not found the HTTP response code is 404. HTTP Error codes possible for GET operations are:

• 400: Bad Request
• 401: An unauthorized execution attemp was detected.
• 403: The received token does not contain any of the required roles.
• 404: There is no resource matching the requested ID or reference.
• 500: An internal error occurred.

In the case of PUT/PATCH/DELETE operations a success response is idenfied with the HTTP Code 204 (No Content). A different HTTP Code Response means that there was a problem with the operation. HTTP Error codes possible for PUT/PATCH/DELETE operations are:

• 400: Bad Request
• 401: An unauthorized execution attemp was detected.
• 403: The received token does not contain any of the required roles.
• 404: There is no resource matching the requested ID or reference.
• 500: An internal error occurred.

A response body is returned when an error is triggered (HTPP Code different than 201/200):

{
  "errorCategory": "string",
  "errorCode": "string",
  "errorDescription": "string",
  "errorDateTime": "2023-04-16T19:01:23.672Z",
  "errorParameters": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

For the possible error categories and error code please se the section Entity Error Codes.

Wallet

For an entity a unique wallet can be created. The wallet is the container for the payment methods that belong to an entity.

A Wallet can be batch or not, a wallet should be set as batch a when the emoney/emoney in/emponeyout class payments methods must support a heavy traffic.

Wallet APIs

Multiple operations can be performed over a wallet:

• Create a wallet for an entity
• Create an alias for a wallet, an alias is information that can be used to identify a wallet instead of the walletReference. Take into account that the unicity of the information selected as alias should be ensure by the use case.
• Obtain the information related to a wallet
• Obtain the entity that owns the wallet
• Obtain the balance of each payment methods that a wallet contains. The balance it is only shown If it is possible to obtain it.
• Add a payment method to the wallet.
• Obtain the payment methods included in the wallet.
• Obtain the transactions executer over the payment methods that are included in the wallet.

For more information about the Wallet API see: Wallet

Handling Errors

In the case of POST operations a success response is identified with the HTTP Code 201 (Created). A different HTTP Code Response means that there was a problem with the operation. HTTP Error codes possible for POST operations are:

• 400: Bad Request
• 401: An unauthorized execution attemp was detected.
• 404: There is no resource matching the requested ID or reference. Only applicable when the resource the it's being created is over a different resource (i.e. a payment method that is added to an wallet and the provided wallet reference or alias does not exist).
• 500: An internal error occurred.
• 503: Represents an error caused by system unavailability.

In the case of GET operations a success response is identified with the HTTP Code 200 (OK). In the case the resource is not found the HTTP response code is 404. HTTP Error codes possible for GET operations are:

• 400: Bad Request
• 401: An unauthorized execution attemp was detected.
• 404: There is no resource matching the requested ID or reference.
• 500: An internal error occurred.
• 503: Represents an error caused by system unavailability.

In the case of PUT/PATCH/DELETE operations a success response is idenfied with the HTTP Code 204 (No Content) or 200 (OK). A different HTTP Code Response means that there was a problem with the operation. HTTP Error codes possible for PUT/PATCH/DELETE operations are:

• 400: Bad Request
• 401: An unauthorized execution attemp was detected.
• 403: The received token does not contain any of the required roles.
• 404: There is no resource matching the requested ID or reference.
• 500: An internal error occurred.

A response body is returned when an error is triggered (HTPP Code different than 201/200):

{
  "errorCategory": "string",
  "errorCode": "string",
  "errorDescription": "string",
  "errorDateTime": "2023-04-16T19:01:23.672Z",
  "errorParameters": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

Payment Methods

Payment Methods are the payment instruments that an entity can use to make financial transactions. Different class of payment methods exists:

• emoney: the payment methods that are used to build a digital wallet within our platform have this payment method class.
• emoneyin: the payment methods that are used as collection account for Payments(Pay-in) have this payment method class.
• emoneyout: the payment methods that are used as disbursement account for Payments (Pay-out) have this payment method class.
• cash: the payment methods that are used for cash payments.
• bank: the payment methods that are used for bank payments.
• card: the payment methods that are used for card payments.
• crypto: the payment methods that are used for crypto payments.
• digitalWallet: the payment methods that are used when using an external digital wallet for payments.
• virtualAccount: the payment methods that are used when a virtual account is used to receive payment.
• giftcard: the payment methods that are used for the internal giftftcard platform.
• topup: the payment method that allow to make top ups.
• billpay: he payment method that allow to make bill payments.

Payment methods have three possible directions when we are taking about payments:

• in : for payment methods that allows to receive payments. Available for cash, bank, crypto, digitalWallet and Virtual Accounts classes.
• out: for payment methods that allows to make payment. Available for cash, digitalWallet and bank classes
• null: when the direction it is not defined(emoney, emoneyin, emoneyout).

A payment method can be used directly or should be created before, payment methods class that allows direct usage are cash, bank, crypto and digitalWallet. This means that you can provide the payment method at the moment of the payment without need to create something before use it (i.e. emoney ).

In the case of emoney class it is possible to define the following configurations to a payment method:

• maxBalance: the maximum balance the account can reach.
• overdraft: the amount that account can be overdraft. If there is no limit for the overdraft infinity should be defined.

Payment Methods Status

A Payment Methods can have to different status:

• active: when the payment method it is usable.
• inactive: when the payment method it is not able to be used. A transaction executed over a inactive payment method will fail.

The property that should be seen to get the payment method status is paymentMethodStatus

When a payment methods is inactivated an inactiveReason can be set. Also for both cases a metadata can be defined in order to set any information that can be updated when the account is activated or inactivated.

Payment Methods APIs

Multiple operations can be performed over a payment mehod:

• Create an alias for a payment method, an alias is information that can be used to identify the paymentMethod instead of the paymentMethodReference. Take into account that the unicity of the information selected as alias should be ensure by the use case.
• Obtain the information about a payment method.
• Obtain the balance from a payment methods. Only available if it possible to obtain the information.
• Update a payment method: update information from a payment method and also its status.
• Add a link to the payment method, a link gives the possibility that another customer than the owner can use the payment method. When a link is created you should set the role that the new entity will have over the payment method and also the usage limits.
• Obtain the created links for a payment method .
• Create metadata information assocaited to the Payments Method
• Obtain the transaction executed over the payment method.
• Delete a payment method

For more information about the Payment Method API see: Payment Methods

Handling Errors

In the case of POST operations a success response is identified with the HTTP Code 201 (Created). A different HTTP Code Response means that there was a problem with the operation. HTTP Error codes possible for POST operations are:

• 400: Bad Request
• 401: An unauthorized execution attemp was detected.
• 404: There is no resource matching the requested ID or reference. Only applicable when the resource the it's being created is over a different resource (i.e. a payment method that is added to an wallet and the provided wallet reference or alias does not exist).
• 500: An internal error occurred.
• 503: Represents an error caused by system unavailability.

In the case of GET operations a success response is identified with the HTTP Code 200 (OK). In the case the resource is not found the HTTP response code is 404. HTTP Error codes possible for GET operations are:

• 400: Bad Request
• 401: An unauthorized execution attemp was detected.
• 404: There is no resource matching the requested ID or reference.
• 500: An internal error occurred.
• 503: Represents an error caused by system unavailability.

In the case of PUT/PATCH/DELETE operations a success response is idenfied with the HTTP Code 204 (No Content) or 200 (OK). A different HTTP Code Response means that there was a problem with the operation. HTTP Error codes possible for PUT/PATCH/DELETE operations are:

• 400: Bad Request
• 401: An unauthorized execution attemp was detected.
• 404: There is no resource matching the requested ID or reference.
• 500: An internal error occurred.
• 503: Represents an error caused by system unavailability.

A response body is returned when an error is triggered (HTPP Code different than 201/200):

{
  "errorCategory": "string",
  "errorCode": "string",
  "errorDescription": "string",
  "errorDateTime": "2023-04-16T19:01:23.672Z",
  "errorParameters": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}