PaymentMethodManagement

This APS type is used to create a singleton APS resource representing the platform service to manage payment methods on the APS bus.

GraphViz

Schema

The considered APS type (download) extends the Resource APS type(s) and looks as follows:

{
  "name": "PaymentMethodManagement",
  "id": "http://www.odin.com/billing/payment-method-management/1.5",
  "apsVersion": "2.0",
  "implements": [
    "http://aps-standard.org/types/core/resource/1.0"
  ],
  "access": {
    "global": true
  },
  "operations": {
    "getPaymentMethods": {
      "path": "/paymentMethods",
      "verb": "GET",
      "response": {
        "type": "array",
        "items": {
          "type": "APSPaymentMethod"
        }
      },
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "accountId": {
          "kind": "query",
          "type": "string"
        },
        "paymentSystemId": {
          "kind": "query",
          "type": "string"
        },
        "externalId": {
          "kind": "query",
          "type": "string"
        }
      }
    },
    "getPaymentSystems": {
      "path": "/paymentSystems",
      "verb": "GET",
      "response": {
        "type": "array",
        "items": {
          "type": "APSPaymentSystem"
        }
      },
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "accountId": {
          "kind": "query",
          "type": "string"
        }
      }
    },
    "addPaymentMethod": {
      "path": "/paymentMethods",
      "verb": "POST",
      "response": {
        "type": "APSPaymentMethod"
      },
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "paymentMethod": {
          "kind": "body",
          "type": "APSPaymentMethod"
        }
      }
    },
    "updatePaymentMethod": {
      "path": "/paymentMethods/{paymentMethodId}",
      "verb": "PUT",
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "paymentMethodId": {
          "kind": "path",
          "type": "integer"
        },
        "paymentMethod": {
          "kind": "body",
          "type": "APSPaymentMethod"
        }
      }
    },
    "deletePaymentMethod": {
      "path": "/paymentMethods/{paymentMethodId}",
      "verb": "DELETE",
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "paymentMethodId": {
          "kind": "path",
          "type": "integer"
        }
      }
    },
    "updatePaymentMethodToken": {
      "path": "/paymentMethods/{paymentMethodId}/token",
      "verb": "PUT",
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "paymentMethodId": {
          "kind": "path",
          "type": "integer"
        }
      }
    },
    "tokenizePaymentMethod": {
      "path": "/paymentMethods/{paymentMethodId}/tokenize",
      "verb": "POST",
      "response": {
        "type": "APSPaymentCreationResult"
      },
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "paymentMethodId": {
          "kind": "path",
          "type": "integer"
        },
        "tokenizeParams": {
          "kind": "body",
          "type": "APSPaymentMethodTokenizeRequest"
        }
      }
    },
    "enableFakePaymentMethod": {
      "path": "/fakePaymentMethods",
      "verb": "POST",
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "config": {
          "kind": "body",
          "type": "FakePaymentMethodConfig"
        }
      }
    }
  },
  "structures": {
    "APSPaymentMethodParameter": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "required": true
        },
        "name": {
          "type": "APSMLString"
        },
        "type": {
          "type": "string"
        },
        "value": {
          "type": "object",
          "required": true
        }
      }
    },
    "APSMLString": {
      "type": "object"
    },
    "APSPaymentMethod": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "paymentSystemId": {
          "type": "string"
        },
        "paymentSystem": {
          "type": "string"
        },
        "ownerAccountId": {
          "type": "string"
        },
        "number": {
          "type": "string"
        },
        "name": {
          "type": "string",
          "readonly": true
        },
        "type": {
          "type": "string",
          "enum": [
            "CREDIT_CARD",
            "BANK_ACCOUNT",
            "EXTERNAL",
            "MANUAL",
            "CUSTOM",
            "MODAL"
          ]
        },
        "perCustomer": {
          "type": "boolean",
          "required": true
        },
        "status": {
          "type": "string",
          "required": true,
          "enum": [
            "ACTIVE",
            "NOT_INSTANTIATED",
            "EXPIRED",
            "SUSPENDED",
            "PENDING",
            "FAILED",
            "CANCELLED",
            "DISABLED",
            "DELETED"
          ]
        },
        "ratified": {
          "type": "string",
          "required": true,
          "enum": [
            "YES",
            "NO",
            "NOT_REQUIRED"
          ]
        },
        "defaultMethod": {
          "type": "boolean"
        },
        "allowedForTopUp": {
          "type": "boolean"
        },
        "tokenizable": {
          "type": "boolean"
        },
        "consentStatus": {
          "type": "string",
          "enum": [
            "CONSENT_NOT_REQUIRED",
            "CONSENT_NOT_PROVIDED",
            "CONSENT_PROVIDED"
          ]
        },
        "consentDate": {
          "type": "string",
          "format": "date"
        },
        "deletionDate": {
          "type": "string",
          "format": "date"
        },
        "whoAgreedId": {
          "type": "string"
        },
        "agreementURL": {
          "type": "string"
        },
        "parameters": {
          "type": "array",
          "items": {
            "type": "APSPaymentMethodParameter"
          }
        }
      }
    },
    "APSPaymentSystemParameter": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "APSMLString"
        },
        "description": {
          "type": "APSMLString"
        },
        "paramType": {
          "type": "APSParameterType"
        },
        "validator": {
          "type": "string"
        },
        "inputHint": {
          "type": "APSMLString"
        },
        "displayAs": {
          "type": "string"
        }
      }
    },
    "APSParameterType": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "APSMLString"
        },
        "dataType": {
          "type": "string"
        },
        "options": {
          "type": "array",
          "items": {
            "type": "APSDataTypeValue"
          }
        }
      }
    },
    "APSDataTypeValue": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "name": {
          "type": "APSMLString"
        }
      }
    },
    "APSPaymentSystem": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "APSMLString"
        },
        "type": {
          "type": "string",
          "enum": [
            "CREDIT_CARD",
            "BANK_ACCOUNT",
            "EXTERNAL",
            "MANUAL",
            "CUSTOM",
            "MODAL"
          ]
        },
        "availableForCustomers": {
          "type": "boolean"
        },
        "parameters": {
          "type": "array",
          "items": {
            "type": "APSPaymentSystemParameter"
          }
        }
      }
    },
    "APSPaymentCreationResultRedirectData": {
      "type": "object",
      "properties": {
        "method": {
          "type": "string",
          "description": "method"
        },
        "message": {
          "type": "string",
          "description": "message"
        },
        "redirectURL": {
          "type": "string",
          "description": "redirect url"
        },
        "postArguments": {
          "type": "array",
          "description": "post arguments",
          "items": {
            "type": "PostArgument"
          }
        }
      }
    },
    "PostArgument": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "Redirect argument id"
        },
        "value": {
          "type": "string",
          "description": "Redirect argument value"
        }
      }
    },
    "APSPaymentCreationResultModalFormData": {
      "type": "object",
      "properties": {
        "checkoutScriptSrc": {
          "type": "string",
          "description": "checkoutScriptSrc"
        },
        "checkoutScriptSection": {
          "type": "string",
          "description": "checkoutScriptSection"
        },
        "checkoutScriptHandler": {
          "type": "string",
          "description": "checkoutScriptHandler"
        },
        "checkoutScriptHtml": {
          "type": "string",
          "description": "checkoutScriptHtml"
        },
        "hints": {
          "type": "string",
          "description": "hints"
        }
      }
    },
    "APSPaymentCreationResult": {
      "type": "object",
      "properties": {
        "paymentId": {
          "type": "integer",
          "description": "PaymentID"
        },
        "redirectData": {
          "type": "APSPaymentCreationResultRedirectData",
          "description": "Redirect payment result"
        },
        "modalForm": {
          "type": "APSPaymentCreationResultModalFormData",
          "description": "Modal Form"
        }
      }
    },
    "APSPaymentMethodTokenizeRequest": {
      "type": "object",
      "properties": {
        "ownerAccountId": {
          "type": "string"
        }
      }
    },
    "FakePaymentMethodConfig": {
      "type": "object",
      "properties": {
        "accountUid": {
          "type": "string",
          "required": true
        }
      }
    }
  }
}

The APS type is used to create a singleton APS resource exposing its operations for API calls. The call syntax depends on the operation. For example, a call of an operation that accepts input parameters both in the URL string and in the body looks as follows:

POST  /aps/2/services/payment-method-manager/<operation-path>?<query-params>

{/*<body params>*/}

In the above call, the verb can be either GET, PUT, POST, or DELETE as specified in the definition of the operation.

Custom Operations

OPERATION

VERB

PATH

RETURNS

Description

getPaymentMethods

GET

/paymentMethods

A list of payment methods.

The operation gets available payment methods for the specified account.

getPaymentSystems

GET

/paymentSystems

A list of payment systems.

The operation returns the payment systems available for the account specified by its APS ID.

addPaymentMethod

POST

/paymentMethods

The added payment method.

Adds a payment method based on a custom payment system.

updatePaymentMethod

PUT

/paymentMethods/{paymentMethodId}

200 (OK) if the payment method was successfully updated.

Updates the status of the specified payment method.

deletePaymentMethod

DELETE

/paymentMethods/{paymentMethodId}

200 (OK) if the payment method was successfully deleted.

Deletes the specified payment method.

updatePaymentMethodToken

PUT

/paymentMethods/{paymentMethodId}/token

HTTP 200 Code.

This operation allows you to update the contents of the token of a payment method. With this operation, you can add a new item to a token or update an existing item by key. The items you need to add or update must be specified in the body of your HTTP request in JSON format. For example: {“item_key”: “item_value”}. Note that provider account credentials are required to perform this operation.

tokenizePaymentMethod

POST

/paymentMethods/{paymentMethodId}/tokenize

APSPaymentCreationResult

Creates a token based on the Redirect or Modal payment method.

enableFakePaymentMethod

POST

/fakePaymentMethods

FakePaymentMethodConfig

Enable and configure fake payment method

getPaymentMethods

HTTP Request

GET /aps/2/services/payment-method-manager/paymentMethods

Description

The operation gets available payment methods for the specified account.

Parameters

PARAMETER

TYPE

DESCRIPTION

accountId

String

The APS ID of the account. If it is null, the payments methods of the current account will be retrieved.

paymentSystemId

String

The payment system ID.

externalId

String

The “external ID” attribute of the payment system.

Returns

A list of payment methods.

getPaymentSystems

HTTP Request

GET /aps/2/services/payment-method-manager/paymentSystems

Description

The operation returns the payment systems available for the account specified by its APS ID.

Parameters

PARAMETER

TYPE

DESCRIPTION

accountId

String

The APS ID of the account. If it is null, the payments methods of the current account will be retrieved.

Returns

A list of payment systems.

addPaymentMethod

HTTP Request

POST /aps/2/services/payment-method-manager/paymentMethods

Description

Adds a payment method based on a custom payment system.

Parameters

PARAMETER

TYPE

DESCRIPTION

paymentMethod

APSPaymentMethod

Payment method parameters.

Returns

The added payment method.

updatePaymentMethod

HTTP Request

PUT /aps/2/services/payment-method-manager/paymentMethods/{paymentMethodId}

Description

Updates the status of the specified payment method.

Parameters

PARAMETER

TYPE

DESCRIPTION

paymentMethodId

Integer

The payment method ID.

paymentMethod

APSPaymentMethod

Payment method parameters to be changed.

Returns

200 (OK) if the payment method was successfully updated.

deletePaymentMethod

HTTP Request

DELETE /aps/2/services/payment-method-manager/paymentMethods/{paymentMethodId}

Description

Deletes the specified payment method.

Parameters

PARAMETER

TYPE

DESCRIPTION

paymentMethodId

Integer

The payment method ID.

Returns

200 (OK) if the payment method was successfully deleted.

updatePaymentMethodToken

HTTP Request

PUT /aps/2/services/payment-method-manager/paymentMethods/{paymentMethodId}/token

Description

This operation allows you to update the contents of the token of a payment method. With this operation, you can add a new item to a token or update an existing item by key. The items you need to add or update must be specified in the body of your HTTP request in JSON format. For example: {“item_key”: “item_value”}. Note that provider account credentials are required to perform this operation.

Parameters

PARAMETER

TYPE

DESCRIPTION

paymentMethodId

Integer

A payment method identifier

Returns

HTTP 200 Code.

tokenizePaymentMethod

HTTP Request

POST /aps/2/services/payment-method-manager/paymentMethods/{paymentMethodId}/tokenize

Description

Creates a token based on the Redirect or Modal payment method.

Parameters

PARAMETER

TYPE

DESCRIPTION

paymentMethodId

Integer

The payment method ID.

tokenizeParams

APSPaymentMethodTokenizeRequest

Optional parameters.

Returns

APSPaymentCreationResult

enableFakePaymentMethod

HTTP Request

POST /aps/2/services/payment-method-manager/fakePaymentMethods

Description

Enable and configure fake payment method

Parameters

PARAMETER

TYPE

DESCRIPTION

config

FakePaymentMethodConfig

Settings.

Returns

FakePaymentMethodConfig

Structures

APSPaymentMethodParameter

Structure of the parameter from an APS Payment Method.

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

id

String

Required

The ID of a payment method parameter.

name

APSMLString

Not Required

A multi-language string that represents the name of a payment method parameter.

type

String

Not Required

The type of payment method parameter.

value

Object

Required

The value of a payment method parameter. The value type depends on the type of this parameter. If the field type is “ENUM”, the value is an APSOptionValue structure. Otherwise, the value is a string.

APSMLString

A structure in the key-value format used to create a string in multiple languages.

APSPaymentMethod

The payment method structure used in operations with payments and payment methods.

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

id

Integer

Not Required

Payment method ID assigned by the platform.

paymentSystemId

String

Not Required

Payment system ID assigned by the platform.

paymentSystem

String

Not Required

The localized name of the payment system.

ownerAccountId

String

Not Required

The APS ID of the payment method owner (account).

number

String

Not Required

The payment method number assigned by the platform.

name

String

Not Required Read Only

The name of the payment method that combines the name of its payment system and its number.

type

Enum

Not Required

The payment method type:
CREDIT_CARD - Locally processed and stored credit card.
BANK_ACCOUNT - Bank account.
EXTERNAL - External payment site.
MANUAL - Manual payment.
CUSTOM - Custom payment method.
MODAL - Modal form.

perCustomer

Boolean

Required

The flag that indicates if a separate payment method should be created for every customer.

status

Enum

Required

The payment method status:
ACTIVE - Payment method is active.
NOT_INSTANTIATED - Payment method is not instantiated.
EXPIRED - Payment method has expired.
SUSPENDED - Payment method is suspended.
PENDING - Payment method creation in 3rd-party system is in progress.
FAILED - Payment method creation in 3rd-party system is failed.
CANCELLED - Payment method is cancelled by 3rd-party system.
DISABLED - Payment method is disabled by vendor.
DELETED - Not used, as API neither returns deleted payment methods nor allows to set this status.

ratified

Enum

Required

The ratification status of the payment method:
YES - Payment method is ratified.
NO - Payment method is not ratified.
NOT_REQUIRED - Ratifications is not required.

defaultMethod

Boolean

Not Required

Flag that indicates if the payment method is default.

allowedForTopUp

Boolean

Not Required

Flag that indicates if the payment method is allowed for TopUp selection.

tokenizable

Boolean

Not Required

Flag that indicates if the payment method is tokenizable.

consentStatus

Enum

Not Required

consentDate

String

Not Required

Date, when user agreed on storing his/her credential for payment method

deletionDate

String

Not Required

The date when the payment method will be deleted. This field is retrieved from table PayToolConsent

whoAgreedId

String

Not Required

User APS UUID who accepted consent.

agreementURL

String

Not Required

Link to the page on provider’s web site with consent conditions

parameters

Array of APSPaymentMethodParameter

Not Required

Payment method parameters.

APSPaymentSystemParameter

Represents an APS Payment System Parameter, used for conversion from BMPTParamType.

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

id

String

Not Required

The ID of a payment system parameter.

name

APSMLString

Not Required

A multi-lang string that represents the name of a payment system parameter.

description

APSMLString

Not Required

A multi-lang string that represents the description of a payment system parameter.

paramType

APSParameterType

Not Required

The type of a payment system parameter (See APSParameterType. Depending on the payment system it can be customizable or hardcoded.

validator

String

Not Required

A regular expression used for the input field validation.

inputHint

APSMLString

Not Required

A multi-lang string in the form of a plain text or regular expression used as the input field hint.

displayAs

String

Not Required

Determines how the parameter must be processed and displayed in a user interface (UI):
HIDDEN - the parameter is not displayed and cannot be edited.
OPTIONAL - a user can edit the parameter in UI if necessary.
REQUIRED - a user must enter the parameter value.

APSParameterType

Represents an APS Parameter Type, used for conversion between APS types and BM types.

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

id

String

Not Required

Generally, a string that represents the ID of a parameter type. Depending on an implementation, it can be a pre-defined value (“INT”, “PASSWORD”, and other) or a custom string.

name

APSMLString

Not Required

A multi-lang string that represents the name of the parameter type.

dataType

String

Not Required

The type of the parameter data that can be one of:
PASSWD - a password.
STR - a string.
INT - an integer.
DATE - a date.
ENUM - a list of custom values.

options

Array of APSDataTypeValue

Not Required

A list of APSDataTypeValue for the custom data type configured in the BSS system settings (with the data type name as in the name field).

APSDataTypeValue

A class that represent an APS Data Type Value. It is used for conversion between APS types and BM types.

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

id

Integer

Not Required

name

APSMLString

Not Required

APSPaymentSystem

The payment system structure used in operations with payments and payment methods.

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

id

String

Not Required

Payment system ID.

name

APSMLString

Not Required

A multi-language string that represents the payment system name.

type

Enum

Not Required

| The payment system type that accepts one of the following values:
CREDIT_CARD - the credit cards that are processed and stored locally.
CUSTOM - a custom payment system.
EXTERNAL - the system processes payments on an external payment site.
BANK_ACCOUNT - the system uses the Direct Debit methods.
MANUAL - this represents any manual payment methods.
MODAL - the system processes a payment in a modal form.
The payment method type:
CREDIT_CARD - Locally processed and stored credit card.
BANK_ACCOUNT - Bank account.
EXTERNAL - External payment site.
MANUAL - Manual payment.
CUSTOM - Custom payment method.
MODAL - Modal form.

availableForCustomers

Boolean

Not Required

Specifies if the payment system is available for customers (true) or not (false).

parameters

Array of APSPaymentSystemParameter

Not Required

List of APSPaymentSystemParameter. These are the payment system parameters. For custom payment systems this field is configurable.

APSPaymentCreationResultRedirectData

Payment redirect data

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

method

String

Not Required

message

String

Not Required

redirectURL

String

Not Required

postArguments

Array of PostArgument

Not Required

PostArgument

Payment redirect post argument

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

key

String

Not Required

value

String

Not Required

APSPaymentCreationResultModalFormData

Redirect payment callback form data

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

checkoutScriptSrc

String

Not Required

checkoutScriptSection

String

Not Required

checkoutScriptHandler

String

Not Required

checkoutScriptHtml

String

Not Required

hints

String

Not Required

APSPaymentCreationResult

The structure to be returned by the payment creation operation.

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

paymentId

Integer

Not Required

The payment ID assigned by the platform.

redirectData

APSPaymentCreationResultRedirectData

Not Required

The response returned by the redirect payment callback.

modalForm

APSPaymentCreationResultModalFormData

Not Required

Redirect payment callback form data.

APSPaymentMethodTokenizeRequest

The structure of the request for tokenizing a particular payment method.

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

ownerAccountId

String

Not Required

The ID of the payment method owner (account ID).

FakePaymentMethodConfig

Input fake payment method config

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

accountUid

String

Required

Examples

Below are examples of using the PaymentMethodManagement operations in some common cases.

Get Payment Methods

An external management system can get a list of payment methods that a particular account can use to pay the acquired services. The following call of the paymentMethods operation contains the APS ID of an account identified in accordance with the Account Lookup section.

GET /aps/2/services/payment-method-manager/paymentMethods?accountId=c0f26f33-0514-4be1-ad7e-3b5b50be56cb

The response will look similar to the following:

HTTP/1.1 200 OK

[
   {
      "id": 12,
      "paymentSystemId": "Visa",
      "paymentSystem": "Visa",
      "ownerAccountId": "8349472a-efe8-417f-a7be-ef6b900ed9c6",
      "number": "****1111",
      "name": "Visa ****1111",
      "type": "CREDIT_CARD",
      "perCustomer": true,
      "status": "ACTIVE",
      "ratified": "NOT_REQUIRED",
      "defaultMethod": false,
      "consentStatus": "CONSENT_NOT_REQUIRED",
      "consentDate": null,
      "deletionDate": null,
      "whoAgreedId": null,
      "agreementURL": null,
      "parameters": []
   },
   {
      "id": 0,
      "paymentSystemId": "Check/Cash",
      "paymentSystem": "Check/Cash",
      "ownerAccountId": null,
      "number": null,
      "name": "Check/Cash",
      "type": "MANUAL",
      "perCustomer": false,
      "status": "ACTIVE",
      "ratified": "NOT_REQUIRED",
      "defaultMethod": false,
      "consentStatus": "CONSENT_NOT_REQUIRED",
      "consentDate": null,
      "deletionDate": null,
      "whoAgreedId": null,
      "agreementURL": null,
      "parameters": []
   },
   /* ... */
]

Note

Among payment methods, there are two groups:

  • System-wide methods (for example, Check/Cash) that are not assigned to particular accounts and can therefore be used by any account. In these methods, the method ID is the same for all accounts and the ownerAccountId property is null.

  • Personal methods that are assigned individually to every account that will use them. In these methods, the method ID is unique and ownerAccountId is the respective account APS ID.

Update Payment Methods

With the updatePaymentMethod operation, an external management system can change the status of a payment method, as in the following example:

PUT /aps/2/services/payment-method-manager/paymentMethods/12

{
   "id": 12,
   "status": "EXPIRED"
}

For a payment method created before the platform-wide requirement for the customer consent was added, the following call will require the owner’s consent for that method:

PUT /aps/2/services/payment-method-manager/paymentMethods/12

{
   "consentStatus": "CONSENT_NOT_PROVIDED",
   "deletionDate": "2019-05-25"
}

After the consent is received, the GET request will return a response similar to the following:

HTTP/1.1 200 OK

[
  {
    "id": 12,
    "paymentSystemId": "Visa",
    "paymentSystem": "Visa",
    "ownerAccountId": "1c591150-9af1-4c74-9dab-a50fdfc32d51",
    "number": "****1111",
    "name": "Visa ****1111",
    "type": "CREDIT_CARD",
    "perCustomer": true,
    "status": "ACTIVE",
    "ratified": "NOT_REQUIRED",
    "defaultMethod": false,
    "consentStatus": "CONSENT_PROVIDED",
    "consentDate": "2019-05-22",
    "deletionDate": null,
    "whoAgreedId": "2d4d3969-6595-4412-ac6b-a0b5d99ff432",
    "agreementURL": "https://ingrammicrocloud.com/marketplace-legal/general-terms-of-service/"
  },
  {
    "id": 0,
    "paymentSystemId": "Check/Cash",
    "paymentSystem": "Check/Cash",
    "ownerAccountId": null,
    "number": null,
    "name": "Check/Cash",
    "type": "MANUAL",
    "perCustomer": false,
    "status": "ACTIVE",
    "ratified": "NOT_REQUIRED",
    "defaultMethod": false,
    "consentStatus": "CONSENT_NOT_REQUIRED",
    "consentDate": null,
    "deletionDate": null,
    "whoAgreedId": null,
    "agreementURL": null
  },
  {
    "id": 3,
    "paymentSystemId": "Demo.Redirect",
    "paymentSystem": "Demo Payment Gateway",
    "ownerAccountId": null,
    "number": null,
    "name": "Demo Payment Gateway",
    "type": "EXTERNAL",
    "perCustomer": false,
    "status": "ACTIVE",
    "ratified": "NOT_REQUIRED",
    "defaultMethod": false,
    "consentStatus": "CONSENT_NOT_REQUIRED",
    "consentDate": null,
    "deletionDate": null,
    "whoAgreedId": null,
    "agreementURL": null
  }
]

Delete Payment Methods

An external management system can delete a certain payment method (for example, if its owner requires) by sending the DELETE request containing the platform’s internal ID of the method, for example:

DELETE /aps/2/services/payment-manager/paymentspaymentMethods/12

If successful, the response code is “200 OK”.

Add Payment Methods

If a custom payment system is added to the BSS (using the BSS provider control panel), an external management system can assign payment methods based on this system to customers. To do this, complete these steps:

  1. In the BSS provider control panel, identify or create the custom payment system you are going to use:

    • Navigate to System > Settings, click the Payment Processing link, and on the Payment Systems tab, find the required system. You can create a new system by clicking the Add New Payment System button. Open the system details and on the Parameters tab, identify or configure the system parameters. For the next steps, you need to know the system ID. In this example, the ID is “Custom_Payment_System_1”.

    • Ensure the payment system is allowed to create payment methods. For this purpose, on the Payment Methods tab, click Manage Payment Methods and enable this system.

  2. The external management system receives a list of payment systems allowed to be assigned to a specific customer (specified by the accountId query parameter) using the following request:

    GET /aps/2/services/payment-manager/paymentSystems?accountId=94675c4d-3655-4f34-8226-f09aed6df67e
    

    The result will look as follows:

    HTTP/1.1 200 OK
    
    [
      {
        "id": "CustomPaymentSystem_1",
        "name": {
          "en": "Custom Payment System 1"
        },
        "type": "CUSTOM",
        "availableForCustomers": true,
        "parameters": [
          {
            "id": "phone",
            "name": {
              "en": "Phone"
            },
            "description": {
              "en": "Phone number"
            },
            "paramType": {
              "id": "STR",
              "name": {
                "en": "String"
              },
              "dataType": "STR",
              "options": []
            },
            "validator": null,
            "inputHint": {
              "en": "1(888)123-4567"
            },
            "displayAs": "REQUIRED"
          },
          {
            "id": "username",
            "name": {
              "en": "User Name"
            },
            "description": {
              "en": "First name and last name"
            },
            "paramType": {
              "id": "STR",
              "name": {
                "en": "String"
              },
              "dataType": "STR",
              "options": []
            },
            "validator": null,
            "inputHint": {
              "en": "John Smith"
            },
            "displayAs": "REQUIRED"
          }
        ]
      },
      {
        "id": "Check/Cash",
        "name": {
          "en": "Check/Cash"
        },
        "type": "MANUAL",
        "availableForCustomers": true,
        "parameters": []
      }
    ]
    

    Note

    The accountId query parameter is optional. If it is missing the platform will return a list of payment systems available for the requester.

    As follows from the above response, the custom payment system requires the phone and username string parameters.

  3. Before adding a custom payment method to a customer, ensure that this payment method is not already assigned to that customer (Get Payment Methods).

  4. To assign a payment method based on the custom payment system to a customer, the external system sends the following request:

    POST /aps/2/services/payment-method-manager/paymentMethods
    
    {
       "ownerAccountId": "94675c4d-3655-4f34-8226-f09aed6df67e",
       "paymentSystemId": "CustomPaymentSystem_1",
       "parameters": [
          {
            "id": "phone",
            "value": "1(111)123-4567"
          },
          {
             "id": "username",
             "value": "John Smith"
          }
       ]
     }
    

    The result will look as follows:

    HTTP/1.1 200 OK
    
    {
      "id": 11,
      "paymentSystemId": "CustomPaymentSystem_1",
      "paymentSystem": "Custom Payment System 1",
      "ownerAccountId": "94675c4d-3655-4f34-8226-f09aed6df67e",
      "number": "****4567",
      "name": "Custom Payment System 1 ****4567",
      "type": "CUSTOM",
      "perCustomer": true,
      "status": "ACTIVE",
      "ratified": "NOT_REQUIRED",
      "defaultMethod": false,
      "consentStatus": null,
      "consentDate": null,
      "deletionDate": null,
      "whoAgreedId": null,
      "agreementURL": null,
      "parameters": [
        {
          "id": "phone",
          "name": {
            "en": "Phone"
          },
          "type": "STR",
          "value": "1(111)123-4567"
        },
        {
          "id": "username",
          "name": {
            "en": "User Name"
          },
          "type": "STR",
          "value": "John Smith"
        }
      ]
    }
    
  5. You can check the list of payment methods assigned to the customer after the previous operation using the Get Payment Methods operation. The list is increased by one more method as follows from the response:

    HTTP/1.1 200 OK
    
    [
      {
        "id": 11,
        "paymentSystemId": "CustomPaymentSystem_1",
        "paymentSystem": "Custom Payment System 1",
        "ownerAccountId": "94675c4d-3655-4f34-8226-f09aed6df67e",
        "number": "****4567",
        "name": "Custom Payment System 1 ****4567",
        "type": "CUSTOM",
        "perCustomer": true,
        "status": "ACTIVE",
        "ratified": "NOT_REQUIRED",
        "defaultMethod": false,
        "consentStatus": "CONSENT_NOT_REQUIRED",
        "consentDate": null,
        "deletionDate": null,
        "whoAgreedId": null,
        "agreementURL": null,
        "parameters": [
          {
            "id": "phone",
            "name": {
              "en": "Phone"
            },
            "type": "STR",
            "value": "1(111)123-4567"
          },
          {
            "id": "username",
            "name": {
              "en": "User Name"
            },
            "type": "STR",
            "value": "John Smith"
          }
        ]
      },
      {
        "id": 0,
        "paymentSystemId": "Check/Cash",
        "paymentSystem": "Check/Cash",
        "ownerAccountId": null,
        "number": null,
        "name": "Check/Cash",
        "type": "MANUAL",
        "perCustomer": false,
        "status": "ACTIVE",
        "ratified": "NOT_REQUIRED",
        "defaultMethod": false,
        "consentStatus": "CONSENT_NOT_REQUIRED",
        "consentDate": null,
        "deletionDate": null,
        "whoAgreedId": null,
        "agreementURL": null,
        "parameters": []
      },
       /* Other methods */
    ]
    

Set the Default Payment Method for a Customer

If an account has a payment method allowed for auto payments, the recurring and other invoices generated for that account will be paid automatically using this payment method.

To set auto payment for a certain payment method through API, use the Update Payment Methods operation with the default property set to true. The following request makes the payment method 11 the default one:

PUT /aps/2/services/payment-method-manager/paymentMethods/11

{
   "defaultMethod": true
}

If successful, the response is “200 OK” with an empty body. You can verify if the default property is set by sending a GET request or by checking in the BSS control panel whether the respective payment method is set for auto payment.

For system-wide payment methods (for more details, refer to Get Payment Methods), the request body must also contain the ownerAccountId property. The following request makes the Check/Cash payment method (its ID is 0 for all accounts) the default one:

PUT /aps/2/services/payment-method-manager/paymentMethods/0

{
   "ownerAccountId": "94675c4d-3655-4f34-8226-f09aed6df67e",
   "defaultMethod": true
}

Attach Payment Methods to Subscriptions

For the relevant methods and examples, refer to BSSSubscription.