This APS type is used to create a singleton APS resource representing the platform service to manage payment methods on the APS bus.
In this document:
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.
OPERATION |
VERB |
PATH |
RETURNS |
Description |
---|---|---|---|---|
GET |
/paymentMethods |
A list of payment methods. |
The operation gets available payment methods for the specified account. |
|
GET |
/paymentSystems |
A list of payment systems. |
The operation returns the payment systems available for the account specified by its APS ID. |
|
POST |
/paymentMethods |
The added payment method. |
Adds a payment method based on a custom payment system. |
|
PUT |
/paymentMethods/{paymentMethodId} |
200 (OK) if the payment method was successfully updated. |
Updates the status of the specified payment method. |
|
DELETE |
/paymentMethods/{paymentMethodId} |
200 (OK) if the payment method was successfully deleted. |
Deletes the specified payment method. |
|
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. |
|
POST |
/paymentMethods/{paymentMethodId}/tokenize |
Creates a token based on the Redirect or Modal payment method. |
||
POST |
/fakePaymentMethods |
Enable and configure fake payment method |
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.
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.
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 |
Payment method parameters. |
Returns
The added payment method.
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 |
Payment method parameters to be changed. |
Returns
200 (OK) if the payment method was successfully updated.
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.
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.
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 |
Optional parameters. |
Returns
HTTP Request
POST /aps/2/services/payment-method-manager/fakePaymentMethods
Description
Enable and configure fake payment method
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
---|---|---|
config |
Settings. |
Returns
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 |
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 |
A structure in the key-value format used to create a string in multiple languages.
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. |
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 |
Not Required |
A multi-lang string that represents the name of a payment system parameter. |
||
description |
Not Required |
A multi-lang string that represents the description of a payment system parameter. |
||
paramType |
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 |
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. |
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 |
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 |
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 |
Not Required |
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 |
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. |
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 |
Payment redirect post argument
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
key |
String |
Not Required |
||
value |
String |
Not Required |
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 |
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 |
Not Required |
The response returned by the redirect payment callback. |
||
modalForm |
Not Required |
Redirect payment callback form data. |
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). |
Input fake payment method config
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
accountUid |
String |
Required |
Below are examples of using the PaymentMethodManagement
operations in some common cases.
In this section:
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.
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
}
]
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”.
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:
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.
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.
Before adding a custom payment method to a customer, ensure that this payment method is not already assigned to that customer (Get Payment Methods).
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"
}
]
}
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 */
]
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
}
For the relevant methods and examples, refer to BSSSubscription.